# Fieldmark

> Farm financial planning for Midwest corn and soybean farmers (Hackathon Problem #1 — Baseline). Per-field input costs vs **MU Extension 2026** industry benchmarks and **anonymized regional peer cohorts**, interpreted by **D.A.L.E.** — Data Analytics for Land Economics (no vendor ties).

## Hackathon / judge review

**Challenge:** Independent benchmarks, conflict-of-interest framing, per-field costs vs anonymized peer data.

| Layer | What it is |
|-------|------------|
| Industry data | MU Extension 2026 crop budgets (`benchmark_regions`) — independent university planning defaults |
| Peer data | Anonymized aggregates from other Fieldmark farms in your region (min 5 farms; medians/percentiles only) |
| AI | D.A.L.E. (Claude) explains gaps using both baselines + scenario margins; never recommends vendors |
| Live research | Perplexity Sonar fetches cited USDA/drought/MU context into `regional_risk` (retrieval only — not Dale's voice) |

**Full judge guide:** [docs/JUDGE_REVIEW.md](docs/JUDGE_REVIEW.md) (start here — code & verification) · **Agent entry:** [AGENTS.md](AGENTS.md) · **Strategy:** [docs/BUSINESS_MODEL.md](docs/BUSINESS_MODEL.md) · [docs/MARKETING_PLAN.md](docs/MARKETING_PLAN.md)

**Showcase API:** `POST /api/v1/farms/:farm_id/scenarios/:id/compare` — peer + benchmark comparison after per-field costs are entered.

## Product (D.A.L.E.)

D.A.L.E. is Fieldmark's independent agricultural financial analyst — no ties to input vendors, co-ops, or agronomists. Focus on honest, data-backed margin and benchmark analysis in plain Midwest language. Product copy: `client/src/constants/dale.js`.

## Repository structure

- **Rails API**: `api/` — JSON API at `/api/v1`
- **Farmer app**: `client/` — Vite + React
- **Admin app**: `frontend/admin/` — Vite + React
- **Public website**: `website/` — marketing + `/developer` API docs and playground
- **Docs**: `docs/`, `api/docs/API.md`
- **CLI & MCP**: `tools/fieldmark/`

## Local URLs

| Service | `./bin/dev` (ports) | `npm run dev:local` (domains) |
|---------|---------------------|-------------------------------|
| Website | http://localhost:5174 | http://fieldmark.local |
| Farmer app | http://localhost:5173 | http://app.fieldmark.local |
| API | http://localhost:3000 | http://api.fieldmark.local |
| Admin | http://localhost:5175 | http://admin.fieldmark.local |

Setup for custom domains: `npm run setup:local-domains` — see `docs/LOCAL_DOMAINS.md`.

## API

- **Version prefix**: `/api/v1`
- **Auth**: `Authorization: Bearer <jwt>` from `POST /api/v1/auth/login` or `POST /api/v1/auth/demo`
- **Envelope**: success `{ "data": {}, "meta": {}, "errors": [] }` — errors `{ "errors": [{ "field": "", "message": "" }] }`
- **Scoping**: all farm resources are user-scoped via JWT; never use unscoped `Farm.find`
- **Full reference**: `api/docs/API.md`
- **Interactive docs**: http://fieldmark.local/developer (or http://localhost:5174/developer)
- **Local dev (all apps)**: `./bin/dev` from repo root — see `config/local-urls.env.example`

## Recommended client flow

1. `POST /api/v1/auth/register` or `POST /api/v1/auth/demo`
2. `POST /api/v1/farms` → `POST /api/v1/farms/:farm_id/fields`
3. `POST /api/v1/fields/:field_id/input_costs` (per category: seed, fertilizer, chemicals, …)
4. `GET /api/v1/benchmarks?region=central&commodity=corn&year=2026`
5. `POST /api/v1/farms/:farm_id/scenarios` → `POST …/scenarios/:id/calculate` → `POST …/compare`
6. `POST /api/v1/conversations` with `farm_id`, `scenario_id` → `POST …/messages` for AI chat
7. `POST /api/v1/scenarios/:scenario_id/report` → poll `GET …/report` until `status` is `completed` or `failed`
8. `POST /api/v1/scenarios/:scenario_id/decision`

## Async lender reports

- `POST /api/v1/scenarios/:scenario_id/report` returns **202 Accepted** and enqueues generation.
- Poll `GET /api/v1/scenarios/:scenario_id/report` until `status` is `completed` or `failed`.
- Dev requires background jobs: `FIELDMARK_DEV_JOBS=1 ./bin/dev` or `api/bin/jobs` + `REDIS_URL`.
- `?regenerate=true` on POST replaces a completed report.

## Demo account

- In the farmer app: sign in → **Try demo — no password needed** (`POST /api/v1/auth/demo`)
- API only: `POST /api/v1/auth/demo` with no body (no credentials in the client)
- Seed: `cd api && bin/rails demo:seed` (password from `DEMO_PASSWORD` in `api/.env`, not shown in UI)
- Smoke test: `api/bin/test_api` · full AI: `RUN_AI_SMOKE=1 api/bin/test_api`

## MCP (live API access)

For Cursor and other assistants, prefer the **MCP server** over expanding this file: `tools/fieldmark/dist/mcp-server.js`

Configure in `.cursor/mcp.json` with `FIELDMARK_API_URL` and `FIELDMARK_TOKEN`.

Tools: `fieldmark_health`, `fieldmark_benchmarks`, `fieldmark_farms_*`, `fieldmark_scenarios_*`, `fieldmark_analyst_ask`, `fieldmark_report_generate`, and more. Full setup: http://fieldmark.local/developer/MCP

## Key endpoints

| Method | Path | Notes |
|--------|------|-------|
| GET | `/api/health` | No auth |
| POST | `/api/v1/auth/demo` | Demo JWT |
| GET | `/api/v1/benchmarks` | `region`, `commodity`, `year` |
| GET/POST | `/api/v1/farms` | User-scoped |
| POST | `/api/v1/farms/:id/scenarios/:id/calculate` | Margins |
| POST | `/api/v1/farms/:id/scenarios/:id/compare` | Per-field costs vs MU Extension + anonymized peer cohort |
| POST | `/api/v1/conversations` | AI chat session |
| POST | `/api/v1/scenarios/:id/report` | Async lender report (202) |
| GET | `/api/v1/scenarios/:id/report` | Poll report status |

Regions: `northern`, `central`, `southwest`. Commodities: `corn`, `soybean`, `both`.

## Business model

- **Farmers:** $30/mo Basic, $50/mo Pro (`SubscriptionPlan`)
- **Vendors:** $100/mo directory inclusion + promotional upgrades + rev share on many attributed sales (`VendorListingPlan`, `docs/BUSINESS_MODEL.md`)

## Docs

### Product & code (start here)

- [Judge & AI review guide](docs/JUDGE_REVIEW.md): Problem #1 fit, file map, verification, AI prompts
- [Interactive API docs & playground](http://fieldmark.local/developer): try endpoints in the browser
- [API reference](api/docs/API.md): full request/response documentation
- [Benchmark data lineage](api/docs/BENCHMARK_DATA.md): MU Extension scrape/seed
- [Local domains](docs/LOCAL_DOMAINS.md): `fieldmark.local` setup
- [MCP setup](http://fieldmark.local/developer/MCP): Cursor configuration and tool reference
- [README](README.md): running the stack

### Business & go-to-market (optional)

- [Business model](docs/BUSINESS_MODEL.md): farmer subscriptions + vendor listing, promos, revenue share
- [Marketing plan](docs/MARKETING_PLAN.md): Year 1 distribution, co-op partnerships, March conversion window

## Environment (AI stack)

- `ANTHROPIC_API_KEY` — required for Dale chat and lender reports (Claude via `Ai` / `AiRouter`)
- `PERPLEXITY_API_KEY` — optional; enables live `regional_risk` on farm summary, scenario risk panel, and Dale snapshot (`MarketIntelligenceService`). Omit in CI/tests.

`regional_risk` when live: `live`, `researched_at`, `citations` (array of `{ title, url }`), plus `message`, `source`, `source_url`.

## Optional

- [Forecasting roadmap](docs/FORECASTING_ROADMAP.md): future product direction
- [Agent notes](CLAUDE.md): D.A.L.E. branding and stack summary