# Foundation

## Summary

The foundation is the empty but working skeleton every later spec builds on. It sets up a pnpm workspace with three packages: generated TypeScript for our lexicons, a Hono server, and a Vite React web app. It adds environment config, a Kysely database layer that runs on SQLite or Postgres, a migration runner, and a test setup that exercises both databases. When it is done, `pnpm dev` starts the server and web app, the web page shows the server's health, and `pnpm test` passes on both databases. No chat features exist yet.

## Motivation

Every phase 1 spec needs the same plumbing: config, a database, a server, a web app, and tests. Settling it once keeps later specs about features rather than setup. The foundation also locks in the rules that are painful to retrofit: all lexicon NSIDs come from one generated module, all branding comes from config, the database code stays portable across SQLite and Postgres, and the atproto alpha packages install reproducibly.

## Design

### Workspace layout

```
package.json            root scripts, pnpm overrides, packageManager, engines
pnpm-workspace.yaml     packages/*, apps/*, plugins/*
tsconfig.base.json      shared strict compiler options
vitest.config.ts        one Vitest run across all packages
.nvmrc                  24
.env.example            the environment settings, with development defaults
lexicons/               lexicon JSON (exists today)
packages/lexicons/      @scn-chat/lexicons: generated schemas and types
apps/server/            @scn-chat/server: Hono API server
apps/web/               @scn-chat/web: Vite React app
```

All packages are ESM (`"type": "module"`) with TypeScript `strict` on. Workspace packages export their TypeScript source directly (`"exports": "./src/index.ts"`), so nothing needs a build step.

The server runs TypeScript natively with Node's built-in type stripping, in development and production, with no compile step and no runner like tsx. That requires Node 22.18 or newer, and the project targets Node 24, the current LTS. The shared tsconfig sets `erasableSyntaxOnly`, `verbatimModuleSyntax`, and `allowImportingTsExtensions`, so the compiler rejects syntax Node cannot strip, such as enums and namespaces. Relative imports use `.ts` extensions. `tsc --noEmit` does type checking. Vite handles TypeScript for the web app.

The plugin API package and the `plugins/` directory are created by the plugins spec.

### atproto alpha packages

Every `@atproto/*` package with an alpha release is pinned to one exact alpha version through `pnpm.overrides` in the root `package.json`. A range like `^0.0.0-spaces-alpha-*` also matches the broken `0.0.0` releases, so ranges are never used. The lockfile is committed. Upgrading the alpha means changing one version string for every override at once.

### Lexicon package

`packages/lexicons` holds TypeScript generated from `lexicons/` by the `lex build` command from `@atproto/lex`, the same tool bulletin uses. Its schemas come from `@atproto/lex-schema`. The package's index is the one module the rest of the code uses for NSIDs, record types, and record validation. No other code writes an NSID as a string.

- `pnpm codegen` regenerates it with `--clear`, `--index-file`, and `--import-ext .ts`.
- The generated files are committed, so reviewers see schema changes in diffs and nothing needs generating after a clone.
- Upstream lexicons that later specs need, such as `com.atproto.space.*`, are vendored into `lexicons/upstream/` when that spec needs them, with a note recording the source commit, as bulletin does.

### Config

Settings live in one of two places, never both:

- **The environment**, loaded from `.env` by Node's built-in `process.loadEnvFile` when the file exists, holds the secrets and the settings the server needs before its database is open. `.env.example` lists them.
- **The app database** holds every setting an admin changes while the server runs, edited in the admin area. The admin specs describe them.

`apps/server/src/config.ts` validates the environment with a zod schema once at startup and exports a typed, frozen config object. An invalid or missing required value stops the server with a message naming every variable at fault.

| Variable | Default | Purpose |
|---|---|---|
| `NODE_ENV` | `development` | `development`, `test`, or `production`. |
| `DATABASE_URL` | `sqlite:./data/scn-chat.sqlite` | `sqlite:<path>` or `postgres://...`. |
| `PUBLIC_URL` | `http://127.0.0.1:3000` | The URL people reach the app at. |
| `PORT` | `3000` | |
| `DATA_DIR` | `./data` | |
| `LOG_LEVEL` | `info` | |

Later specs add their own variables to the same schema and to `.env.example`. An empty value counts as unset.

### Database

`apps/server/src/db/` creates a Kysely instance from `DATABASE_URL`:

- `sqlite:` uses `better-sqlite3` with `SqliteDialect`, with WAL mode and foreign keys turned on.
- `postgres://` uses `pg` with `PostgresDialect`.

The database types live in one `Database` interface that later specs extend.

Migrations are TypeScript files in `apps/server/src/db/migrations/`, registered in an explicit ordered map and run by Kysely's `Migrator`. The server runs pending migrations on startup, and `pnpm migrate` runs them on their own. The foundation ships the runner with no tables. Each later spec adds its own migrations.

Migrations and queries stay within what both databases support. Timestamps are ISO 8601 text. JSON, including stored lexicon records, is text. Any dialect-specific SQL has to live behind a helper with a test on both databases.

### Server

`apps/server` uses `hono` with `@hono/node-server`. `createApp(deps)` builds the Hono app from a config and a database, so tests can create an app without opening a port. The entry point creates the config, database, and logger, runs migrations, and starts listening.

- `GET /api/health` returns `{ "status": "ok", "appName": "..." }` after a trivial database query succeeds. It returns 503 with `{ "status": "error" }` when the query fails, and logs the error.
- Every route under `/api` is private to our web app. None of it is a public API.
- In production the server also serves the built web app from `apps/web/dist`, with an `index.html` fallback for client-side routes. In development Vite serves the web app and proxies `/api` to the server. `index.html` carries an `__APP_NAME__` placeholder in its title and `application-name` meta tag, filled with the configured app name by the server in production and by a Vite plugin, which asks the server, in development. The web app reads the name from the meta tag.
- Logging uses pino, with request logging through a small Hono middleware.

### Error responses

API errors are JSON with an `error` code and, usually, a `message` the web app shows as is.

- Errors the server expects, such as invalid input or an expired session, have their own status and message.
- A failed call to the user's PDS is passed on. A missing OAuth scope (`InsufficientScope` or `ScopeMissingError`) becomes 403 `ScopeMissing`, telling the user to sign out and back in. Any other PDS error response becomes 502 `PdsError` with the PDS's code and redacted message, and an unreachable PDS becomes 502 `PdsUnreachable`.
- Anything else is 500 `InternalServerError`, with a short random reference in the message and in the log line, so a report can be matched to the log. The error's details stay in the log, except in development, where the redacted message is appended.

The web app logs every failed API call except a 401 to the browser console, with its status, URL, and message.

### Web app

`apps/web` is a Vite React app with no router, state library, or CSS framework. The single `App` component fetches `/api/health` and shows the app name and whether the server is reachable. There is no styling beyond browser defaults.

### Tests

Vitest runs every package from the root config. Tests live in a `tests/` directory in each package that mirrors its `src/`.

- Database tests run against both SQLite and Postgres through a shared helper. SQLite uses an in-memory `better-sqlite3` database. Postgres uses PGlite, an in-process build of Postgres, through `kysely-pglite-dialect`, so no Docker or database server is needed.
- Web tests use jsdom and Testing Library.
- The lexicon package has tests that every lexicon document validates against the alpha lexicon schema, and that the generated code is current with the JSON.

### Scripts

| Root script | Does |
|---|---|
| `pnpm dev` | Runs the server with `node --watch` and the Vite dev server together |
| `pnpm build` | Builds the web app |
| `pnpm start` | Runs the server in production mode, serving the built web app |
| `pnpm test` | Runs all tests once |
| `pnpm typecheck` | Type checks every package |
| `pnpm lint` | Lints and checks formatting with Biome |
| `pnpm format` | Formats with Biome |
| `pnpm check` | Runs lint, typecheck, and test, for any CI system |
| `pnpm codegen` | Regenerates the lexicon package |
| `pnpm migrate` | Runs pending migrations |

### Linting and continuous integration

Biome handles both linting and formatting, configured in one `biome.json` at the root. No CI configuration is committed, so the project is not tied to one host. Any CI system runs `pnpm install --frozen-lockfile` and then `pnpm check`.

## Scope Boundaries

- No authentication, sessions, or OAuth. That is the auth spec.
- No database tables. Each later spec adds its own.
- No plugin interfaces or plugin package. That is the plugins spec.
- No atproto network calls and no vendored upstream lexicons yet.
- No CI configuration for any particular host.
- No UI beyond the health status page.

## Edge Cases and Decisions

- Deployment is a single `Dockerfile` on `node:24-slim` and a `docker-compose.yml`, described in `docs/deployment.md`. The image installs dependencies, builds the web app, and runs `pnpm start`. `.env` is mounted from the host, data lives in a `/data` volume with absolute `DATA_DIR` and `DATABASE_URL`, since `pnpm start` runs from `apps/server` and relative paths would land there, and the port is published on `127.0.0.1` for a reverse proxy that terminates TLS.
- The server runs TypeScript through Node's native type stripping instead of compiling to JavaScript. If the generated lexicon code turns out to use syntax Node cannot strip, the fallback is running the server through `tsx`.
- Node refuses to strip types for files under `node_modules`. Workspace packages work because pnpm symlinks them there and Node resolves symlinks to their real paths by default. Never run with `--preserve-symlinks`.
- SQLite uses `better-sqlite3`, not Node's built-in `node:sqlite`, because Kysely's SQLite dialect targets the `better-sqlite3` API. It ships prebuilt binaries for common platforms.
- Generated lexicon code is committed, with a test that fails when it is stale.
- Migrations run on server startup. Kysely's migrator takes a lock, so several instances starting together on Postgres do not run a migration twice.
- Kysely 0.29 exports the migrator from `kysely/migration`, not the main entry.
- TypeScript 7, the native compiler, handles the project, including the generated lexicon code.
- Timestamps and JSON are stored as text on both databases, trading Postgres-native types for portability. Search and other features that need native types add them behind dialect helpers.
- The health status page was the foundation's placeholder. The web-ui spec replaces it with the real app, so its test moved there.
- Settings started out in a `config.yml` file. They moved to the environment and the admin area, as the admin-settings spec describes, so admins can change them without editing files or restarting.

## Acceptance Criteria

- [ ] An unexpected error returns 500 with a reference that matches its log line, and its details only in development.
- [ ] A PDS scope error returns 403 `ScopeMissing` asking the user to sign in again, and other PDS errors return 502 with the PDS's code.
- [ ] `pnpm install` on a clean clone succeeds with the committed lockfile, and resolves no `@atproto/*` package to a plain `0.0.0` release.
- [ ] Config parsing returns typed values from the environment, and fails naming each variable that is missing or invalid.
- [ ] Empty values in `.env` count as unset.
- [ ] `DATABASE_URL` with `sqlite:` produces a working SQLite database, and with `postgres://` produces a working Postgres database.
- [ ] An unsupported `DATABASE_URL` scheme fails at startup with a clear message.
- [ ] The migrator applies pending migrations in order on both databases, and running it again applies nothing.
- [ ] `GET /api/health` returns 200 with the app name when the database is reachable.
- [ ] `GET /api/health` returns 503 when the database query fails.
- [ ] In production mode, the server serves the built web app and falls back to `index.html` for unknown non-API paths. Unknown `/api` paths return 404.
- [ ] The web app renders the app name and the server's health status, and shows an unreachable state when the health request fails.
- [ ] Every lexicon document validates against the alpha lexicon schema.
- [ ] The generated lexicon code matches a fresh `pnpm codegen` run.
- [ ] `pnpm check` passes on a clean clone.