docs: ADRs 0011-0013 for Sprint 1 stack, user store, and Docker boundary
Mirror to GitHub / mirror (push) Canceled after 0s

This commit is contained in:
SinachPat
2026-08-15 20:07:44 +01:00
parent a037b882e9
commit 97f31315bd
4 changed files with 81 additions and 0 deletions
@@ -0,0 +1,26 @@
# 11. Fastify is the API server; React + Vite is the web shell
- **Status:** Accepted
- **Date:** 2026-08-15
## Context
IMPLEMENTATION §1 names "Express/Fastify" for the backend and "React + TypeScript" for the frontend. Sprint 1 required committing to one server framework before the first route and test.
## Decision
Use **Fastify** for `api/`, and **React 19 + Vite + vitest + @testing-library/react** for `web/`.
### Options considered
- Express (matches the plan's pseudocode).
- Fastify (chosen).
### Rejected
- Express — the plan allows either; Fastify ships built-in JSON-schema validation, native async handlers, and first-class TypeScript, which removes glue the plan would otherwise write by hand.
## Consequences
- Route handlers return via Fastify's `reply` object and validate payloads schema-first (the signup route enforces email format and password length).
- Future routes should keep using Fastify schema validation at the boundary rather than hand-rolled checks.
@@ -0,0 +1,26 @@
# 12. In-memory user store behind a UserStore interface; Postgres deferred
- **Status:** Accepted
- **Date:** 2026-08-15
## Context
IMPLEMENTATION §1 names PostgreSQL for Wursor's own data. Sprint 1's first slice needed working sign-up/auth without standing up a database, migrations, or a connection pool on day one.
## Decision
Define a `UserStore` interface and ship `InMemoryUserStore` behind it. Passwords are hashed with `node:crypto` scrypt; session tokens are `crypto.randomBytes(32)` hex.
### Options considered
- Stand up Postgres now.
- In-memory store behind an interface (chosen).
### Rejected
- Postgres now — adds infrastructure friction to the first slice for no behavioral gain; the interface confines the swap to `services/user-store.ts`.
## Consequences
- Auth data is not durable until Postgres lands; restarting the API clears users and sessions.
- The Postgres swap is a drop-in replacement of `InMemoryUserStore` implementing the same `UserStore` contract.
@@ -0,0 +1,26 @@
# 13. Sandbox orchestration mocks the Docker boundary; real daemon client deferred
- **Status:** Accepted
- **Date:** 2026-08-15
## Context
The development machine has no Docker daemon (the Phase 0 spikes already hit this). Sprint 1 still had to build and test the sandbox services: DB subset, media proxy, manifest delta, GC, and orchestration.
## Decision
Implement the pure-logic sandbox services (`subset`, `media-proxy`, `manifest`, `gc`) and test them directly. Define a `DockerClient` interface and a `SandboxManager` orchestrator that depends on it, tested with a fake client. Defer the real Docker daemon HTTP client.
### Options considered
- Block on a Docker host.
- Mock at the boundary (chosen).
### Rejected
- Block on Docker — IMPLEMENTATION §7 already specifies "mocks at boundaries"; blocking would stall the slice for a reason that doesn't change the logic.
## Consequences
- `subset` and `media-proxy` logic is promoted from the golden harness (`e2e/golden/src/`) into `api/src/sandbox/`.
- The Docker wire-up (`DockerClient` daemon implementation, `image-manager`, `warm-pool`) is an explicit Sprint 1 follow-up and remains unverified until a Docker host exists.
+3
View File
@@ -24,6 +24,9 @@ Each ADR is a single file following the [Nygard format](https://cognitect.com/bl
| [0008](0008-empty-packages-not-stubs.md) | Workspace ships empty packages, not placeholder source | Accepted |
| [0009](0009-repo-rename.md) | Repository renamed originmain → wursor | Accepted |
| [0010](0010-openrouter-live-golden.md) | Golden harness scores live runs through a provider-agnostic LLM client (OpenRouter first) | Accepted |
| [0011](0011-fastify-react-stack.md) | Fastify is the API server; React + Vite is the web shell | Accepted |
| [0012](0012-in-memory-user-store.md) | In-memory user store behind a UserStore interface; Postgres deferred | Accepted |
| [0013](0013-docker-boundary-mock.md) | Sandbox orchestration mocks the Docker boundary; real daemon client deferred | Accepted |
## How to add one