# API architecture (classical Next)

This app exposes **one** HTTP server: **Next.js** (standalone output in Docker).

## Data layer (no ORM)

- **PostgreSQL** via **`pg`** only — `src/lib/db.ts` (`query`, `queryOne`).
- **Migrations** — raw SQL in `db/migrations/` and `db/schema.sql`.
- Do **not** add Prisma, Drizzle ORM, TypeORM, or similar as the primary data access layer.

## Hosting & network (yes)

- **AWS** — e.g. Lightsail; Docker on the host is the expected shape unless we document otherwise.
- **Tailscale** — primary access path for the team; see `docs/TAILSCALE-PRODUCTION.md` (identity headers, optional whois proxy, `tailscale serve`).

## Where handlers live

| Area | Path |
|------|------|
| Route handlers | `src/app/api/**/route.ts` |
| Infra REST (v1) | `src/app/api/v1/**` |
| Gateway merge (MCP, chat, votes, …) | `src/app/api/mcp`, `chat`, `votes`, … |
| Shared logic | `src/lib/` |
| Edge / global | `src/middleware.ts` |

## What we avoid

- A second Node HTTP server in-process for the same routes.
- Splitting “API” into another deployable without a strong reason.

## Monorepo (future)

If the repo grows, introduce **workspaces** (`packages/*`) for shared types and clients; keep **all** user-facing HTTP in this Next app’s `app/api` tree.