AGENTS.md Structures and Nuggets from a Production AI-Ready Repo

1
document-copilot/
2
├── AGENTS.md              # Universal rules (stack, deps, config, code style)
3
├── backend/
4
│   └── AGENTS.md          # Backend-specific (Python, FastAPI, Alembic, tests)
5
└── frontend/
6
    └── AGENTS.md          # Frontend-specific (React, pnpm, Tailwind, shadcn)

1
[tool.uv]
2
add-bounds = "exact"
3
exclude-newer = "7 days"

1
minimum-release-age=10080

1
app/
2
├── api/               # FastAPI routers
3
├── auth/              # JWT verification + user dependency
4
├── chat/              # Turn orchestration, streaming
5
├── assistant/         # PydanticAI agent, deps, outputs, instructions
6
├── retrieval/         # pgvector/full-text queries, RRF fusion
7
├── grounding/         # Citation validation and grounding checks
8
├── database/          # SQLAlchemy models, Supabase client, typed queries
9
└── prompts/           # Prompt/instruction templates

1
# Agent Instructions
2

3
This file is the source of truth for any coding agent (Claude Code, Cursor, Codex, etc.) working in this repo. Read it before touching code.
4

5
## Stack
6

7
- **Backend:** Python + FastAPI
8
- **Frontend:** Vite + React SPA + TypeScript
9
- **Database:** Supabase Postgres (users, chats, source documents, chunks)
10
- **Migrations:** SQLAlchemy models + Alembic from the backend
11
- **Retrieval:** Supabase `pgvector` + Postgres full-text search
12
- **Auth:** Supabase Auth
13
- **Hosting:** Railway (backend service + frontend service)
14
- **LLM + embeddings:** OpenAI
15

16
Stack is locked unless explicitly changed. Don't propose alternatives without a stated reason.
17

18
## Repo layout
19

20
```
21
document-copilot/
22
├── AGENTS.md           # this file
23
├── README.md
24
├── data/               # local corpus + download script (payloads gitignored)
25
├── docs/               # specs, briefs, design notes
26
├── backend/            # FastAPI service (see backend/AGENTS.md)
27
└── frontend/           # React SPA (see frontend/AGENTS.md)
28
```
29

30
## Dependency policy
31

32
**Default: write it yourself. Reach for a library only when the alternative would be non-trivial, error-prone, or reinvention of a standard.** Every dependency is a liability — bundle size, supply-chain risk, future upgrade work.
33

34
OK to depend on:
35

36
- Things that are genuinely hard to get right (HTTP clients, ASGI servers, SQL drivers, parsers, LLM SDKs, ORM, migrations, auth SDKs).
37
- The declared stack (FastAPI, React, Vite, Supabase clients, OpenAI SDK, etc.).
38

39
Not OK:
40

41
- Helper libraries that wrap 5–20 lines of stdlib or platform APIs.
42
- Frameworks where a function would do.
43
- "Nicer API" layers on top of an already-present dependency.
44

45
Before adding a runtime dep, answer in the commit message:
46

47
1. What exactly does it do that we can't write in <30 lines of clear code?
48
2. How often does it get used?
49
3. What's its maintenance / transitive-dep footprint?
50

51
Per-stack specifics live in `backend/AGENTS.md` and `frontend/AGENTS.md`.
52

53
## Configuration
54

55
A single settings module is the source of truth for environment per service (`backend/app/config.py`, `frontend/lib/env.ts`). Do not call `os.getenv` / read `process.env` directly in app code. Do not call `load_dotenv` anywhere. If a third-party SDK reads env vars directly, mirror them in the settings module — don't sprinkle `setdefault` elsewhere.
56

57
Fail fast on startup if required config is missing. No silent fallbacks that hide real config errors.
58

59
## Code style (universal)
60

61
- **Small, obvious functions.** A 15-line function with clear names beats a three-class abstraction.
62
- **No premature abstraction.** Three similar lines is better than a badly-named base class. Extract when there's a third caller, not a hypothetical one.
63
- **No error handling for cases that can't happen.** Trust internal callers and framework guarantees. Validate only at boundaries: HTTP input, external APIs, DB writes, untrusted parsing.
64
- **No backwards-compat shims** unless explicitly asked for.
65
- **No feature flags** added speculatively.
66
- **Comments:** explain *why* when non-obvious, never *what*. Remove stale TODOs.
67
- **Keep files focused.** Prefer small modules.

1
# Backend — agent notes
2

3
This is the FastAPI service for Document Copilot. Read [../AGENTS.md](../AGENTS.md) first — universal building rules live there. This file adds backend-specific conventions.
4

5
## Stack
6

7
- Python 3.12+
8
- FastAPI + uvicorn
9
- Pydantic v2 + pydantic-settings
10
- `httpx` for outbound HTTP
11
- `pytest` for tests
12
- Supabase Python client (DB + auth)
13
- SQLAlchemy models + Alembic migrations for database schema changes
14
- OpenAI SDK for LLM & embeddings
15
- Supabase `pgvector` for semantic search and Postgres full-text search for keyword retrieval. Hybrid search should run vector and full-text queries separately, then fuse ranked results in Python with Reciprocal Rank Fusion.
16
- `structlog` for logging
17
- `uv` for dependency + project management
18

19
## Dependency policy
20

21
See universal policy in [../AGENTS.md](../AGENTS.md). Backend-specific:
22

23
- **Prefer stdlib:** `pathlib`, `datetime`, `uuid`, `enum`, `dataclasses`, `asyncio`, `collections`, `itertools`, `json`, `urllib`.
24
- **Not OK without justification:** `python-dateutil`, `toolz`, `funcy`, `more-itertools`, small JSON/string micro-libs, "ergonomic" wrappers on top of declared SDKs.
25
- Dev deps (test/lint/build) have a looser bar but still pick widely-used, low-footprint tools (`pytest`, `ruff`, `httpx`).
26

27
## Layout (to be created during build)
28

29
```
30
backend/
31
├── alembic/
32
│   ├── env.py           # Imports app database metadata for autogenerate
33
│   └── versions/        # Reviewed migration files
34
├── alembic.ini
35
├── app/
36
│   ├── main.py          # FastAPI entrypoint
37
│   ├── config.py        # Pydantic settings — single source of truth for env
38
│   ├── api/             # FastAPI routers (chat, ingest, auth)
39
│   ├── auth/            # Supabase JWT verification + current user dependency
40
│   ├── chat/            # turn orchestration, AI SDK message conversion, streaming
41
│   ├── assistant/       # PydanticAI agent, deps, outputs, instructions
42
│   ├── retrieval/       # pgvector/full-text queries, RRF fusion, source passage lookup
43
│   ├── grounding/       # citation validation and answer grounding checks
44
│   ├── database/        # SQLAlchemy models, Supabase client wrapper, typed query helpers
45
│   └── prompts/         # prompt/instruction templates if not colocated with assistant
46
├── ingest/              # one-off ingestion scripts (Markdown extraction, chunking, embedding, Supabase writes)
47
├── tests/
48
└── pyproject.toml
49
```
50

51
## Code style (backend-specific)
52

53
- **Type hints on public functions and module-level things.** Don't annotate every local.
54
- **Async by default in request-path code.** Don't run blocking I/O on the event loop. Tempfile + small synchronous file reads are OK (they're fast); network calls must be async.
55
- **Use `async def` for all route handlers** and any I/O service function.
56
- **Validate at boundaries only.** HTTP input is validated by Pydantic models. External API responses are validated when parsed. Internal callers are trusted.
57

58
## Configuration
59

60
- `app.config.settings` is the single source of truth. Import settings where needed; never call `os.getenv` in app code, never call `load_dotenv`.
61
- If a third-party SDK reads `os.environ` directly, add the mirror in `config.py` — don't sprinkle `setdefault` elsewhere.
62
- Fail fast on startup when required env vars are missing.
63

64
## Database migrations
65

66
- Alembic is the source of truth for schema changes. Do not change production tables manually in the Supabase dashboard.
67
- SQLAlchemy models describe normal tables and columns. Alembic autogenerate creates candidate migrations, but every generated migration must be reviewed before applying.
68
- Supabase/Postgres-specific features belong in explicit migration operations: `create extension vector`, generated `tsvector` columns, HNSW/GIN indexes, RLS enablement, and RLS policies.
69
- Alembic must use the direct/session database connection, not the Supabase transaction pooler URL.
70
- Run migrations from `backend/` with `uv run alembic upgrade head`.
71

72
## Tests
73

74
- **Prefer unit over integration.** Mock at the service boundary.
75
- Fast suite (`pytest -m "not integration"`) must stay green and hit no network / no DB.
76
- Integration tests go behind `@pytest.mark.integration` and may require live OpenAI / Supabase credentials.
77
- Tests live next to what they test (`retrieval/retriever.py` → `tests/retrieval/test_retriever.py`).
78
- Required test coverage: ingestion logic, retrieval, citation extraction, grounding enforcement.
79

80
## Anti-patterns (rejected)
81

82
- `os.getenv` / `load_dotenv` in modules.
83
- Wrapping FastAPI responses in custom envelope classes.
84
- Over-catching `Exception` just to log and re-raise; let it propagate.
85
- Shared state through globals instead of FastAPI `app.state` or DI.
86
- Silent fallbacks that hide real config errors.
87
- Mocking the LLM in unit tests without also testing the grounding contract — the prompt is the product.

1
# Frontend — agent notes
2

3
This is the React SPA for Document Copilot. Read [../AGENTS.md](../AGENTS.md) first — universal building rules live there. This file adds frontend-specific conventions.
4

5
## Stack
6

7
- **Plain React SPA** (Vite + TypeScript, strict). **Not Next.js** — do not suggest Next, SSR, server components, or file-based routing.
8
- **Tailwind CSS** for styling. No CSS modules, styled-components, Emotion, or `.module.css` files for component styles. Global theme tokens live in `src/index.css`.
9
- **shadcn/ui** for UI primitives. Add components with `pnpm dlx shadcn@latest add <name>` — don't hand-roll what shadcn already ships.
10
- **React Router** for routing.
11
- **`@supabase/supabase-js`** for auth (email only — no Google sign-in, no SSO providers).
12

13
## Package manager
14

15
**`pnpm` only.** Do not use `npm install` or `yarn add`. The lockfile is `pnpm-lock.yaml`. If you see `package-lock.json` or `yarn.lock` appear, that's a bug — delete it.
16

17
**Minimum release age: 7 days.** Configured via `.npmrc` (`minimum-release-age=10080` minutes). pnpm will refuse to install any package version published less than 7 days ago. This defends against typosquat / compromised-release attacks where a malicious version of a popular package goes live and gets pulled within hours.
18

19
If a fresh package is genuinely required (e.g. urgent security fix in a dep we already use), override per-install and justify in the commit message — don't lower the global threshold.
20

21
## Dependency policy
22

23
See universal policy in [../AGENTS.md](../AGENTS.md). Frontend-specific:
24

25
- **HTTP:** use the native `fetch` API through a thin client in `src/lib/http.ts` and the `api` singleton in `src/lib/api.ts`. **No axios, ky, got, superagent, redaxios.**
26
- **Dates:** use native `Date` and `Intl.DateTimeFormat`. No moment, dayjs, date-fns unless genuinely needed.
27
- **Utilities:** use native `Array` / `Object` / `Map` methods. No lodash, ramda.
28
- **State:** `useState` / `useReducer` / `useContext` first. Only reach for external state libraries when the pain is real.
29
- **Forms:** native `<form>` + `FormData` first.
30
- **Validation:** only add a schema library when we actually need runtime validation at boundaries.
31
- **UI components:** shadcn primitives via `pnpm dlx shadcn@latest add <name>`. Don't hand-roll what shadcn already ships.
32

33
Before adding a package, check:
34

35
1. Is there a native browser or TS/JS API that does this?
36
2. Does shadcn/ui already cover it?
37
3. Is it small, well-maintained, and worth the maintenance cost?
38

39
If yes to (3), add it — but flag the decision in the commit message.
40

41
## Layout (to be created during build)
42

43
```
44
frontend/
45
├── src/
46
│   ├── components/        # App components. shadcn primitives under components/ui/
47
│   ├── lib/               # Framework-agnostic helpers (http, api, auth, supabase, env)
48
│   ├── pages/             # Route-level components
49
│   ├── App.tsx            # Router
50
│   ├── main.tsx
51
│   └── index.css          # Tailwind directives + global theme tokens
52
├── index.html
53
├── vite.config.ts
54
├── tsconfig.json
55
└── package.json
56
```
57

58
Keep imports consistent with the `@/*` alias (e.g. `@/lib/api`, `@/components/ui/button`).
59

60
## Code style (frontend-specific)
61

62
- **TypeScript strict.** No `any` unless there's no alternative; prefer `unknown` and narrow.
63
- **Small, composable functions and components** over clever abstractions. Three similar lines > a premature generic.
64
- **One component = one file.** Components stay small enough to fit on one screen.
65
- **Tailwind classes inline.** No CSS modules, styled-components, Emotion, or `.module.css` for component styles. Global tokens live in `src/index.css`.
66

67
## Configuration
68

69
- All env reads go through a single `src/lib/env.ts` module that validates required vars at boot. Never read `import.meta.env.X` directly in components.
70
- Env vars are prefixed `VITE_` (Vite convention). Anything not prefixed is not exposed to the client.
71

72
## Backend integration
73

74
- Talks to a separate Python backend over JSON. URL comes from `VITE_API_BASE_URL`.
75
- Always use `api.get/post/put/patch/delete` from `@/lib/api` — it handles base URL, JSON, Supabase bearer token, timeouts, and typed `ApiError`s (including the `isNetworkError` flag that distinguishes CORS/network from HTTP errors).
76
- Auth is Supabase email. The bearer token is injected automatically via the `api` client; never thread tokens through component props.
77

78
## Testing
79

80
**No frontend tests.** Do not write `*.test.ts` / `*.test.tsx` files or introduce a test runner. We verify the frontend manually in the browser plus `pnpm tsc --noEmit` and `pnpm lint`. If you find yourself reaching for vitest, Playwright, or Cypress — stop. That's not what this project does. Correctness for shared logic comes from keeping it simple and well-typed, not from a test suite.
81

82
## Anti-patterns (rejected)
83

84
- Reading `import.meta.env.X` directly outside `lib/env.ts`.
85
- Importing an HTTP library when `fetch` would do.
86
- Mixing client state libraries (Zustand + Jotai + Redux) for one project.
87
- `any` annotations to silence the type-checker.
88
- Custom CSS files / styled-components alongside Tailwind.
89
- Re-implementing a shadcn primitive by hand.
90
- Reaching for Next.js, SSR, or any framework that requires a Node server in front of the SPA.