pcbjam/features/web-init/0001-web-app-spec.md

# 0001 — KiCad-WASM Web App Spec

Status: **Refined spec, ready for `implement plan`**
Branch: `feature/web-init`
Scope of this iteration: **create a project, open a project, upload files, open a file in a WASM tool via URL.**

This document is the agreed design after a clarification pass. Decisions that were
explicitly chosen by the user are marked **[decided]**. Items intentionally pushed to a
later iteration are marked **[later]**. Sensible defaults that were *not* explicitly
discussed are marked **[default]** and are safe to change during planning.

---

## 1. Goal

A single web application that lets a user create/open KiCad projects, upload files into
them, and open a file in the matching WASM tool (pcbnew / eeschema / calculator) by
visiting a URL such as:

```
/p/project5/pcbnew/nyak.kicad_pcb
```

The WASM apps already exist as `<tool>.js` + `<tool>.wasm` pairs (see `output/` and
`tests/apps/kicad/`). They boot into an Emscripten harness and read files from MEMFS.
This web app wraps that: it manages projects + files server-side, and on a tool URL it
boots the right WASM app and feeds it the project's files via `FS.writeFile`, then drives
File→Open on the target file.

Non-goals this iteration: editing/saving back, collaboration, auth/login.

---

## 2. Key decisions (summary table)

| Area | Decision |
|---|---|
| Frontend | React + TypeScript + Vite + shadcn/ui **[decided]** |
| Backend | Fastify + ts-rest + Zod **[decided]** |
| Shared types | `packages/contract` (ts-rest contract + Zod) imported by FE client & BE router **[decided]** |
| Realtime | None now; pick stack that allows Hocuspocus/WSS later, no WS endpoints yet **[decided]** |
| URL semantics | `/p/:project/:tool/*filepath` — `tool` selects the WASM app, `*filepath` is auto-opened **[decided]** |
| Auth/tenancy | No auth now, but data model namespaced by an owner id for later multi-user **[decided]** |
| Metadata store | Postgres now, accessed via Drizzle (drizzle-zod shares schemas) **[decided]** |
| File blob storage | Pluggable `FileStorage` interface; local-disk impl now, S3 later **[decided]** |
| Open behavior | Sync **whole project tree** into MEMFS, then auto-open target **[decided]**; lazy/partial load **[later]** |
| Upload | Individual files (multi), folder (preserve structure), and `.zip` of a project **[decided]** |
| WASM artifact delivery | Served from a **configurable base location** (URL/dir): local Fastify static from `output/` in dev, public S3 URL in prod **[decided]** |
| Save-back / sync | Read-only open now; write interface defined but unused. Save-back + lazy load land together **[later]** |
| Monorepo | pnpm + turbo workspace under `web/` **[decided]** |

---

## 3. Repository / monorepo layout  **[decided: under `web/`]**

```
web/
├── package.json                  # pnpm workspace root
├── pnpm-workspace.yaml
├── turbo.json
├── .env.example
├── docker-compose.yml            # local Postgres (and later: minio for S3 parity)
├── apps/
│   ├── frontend/                 # Vite + React + TS + shadcn
│   └── server/                   # Fastify + ts-rest + Drizzle
└── packages/
    ├── contract/                 # ts-rest contract + Zod schemas (shared)
    ├── storage/                  # FileStorage interface + local-disk impl (+ S3 later)
    └── config/                   # shared tsconfig / eslint / env parsing  [default]
```

Rationale: isolates the JS/TS app from the C++/WASM build repo at root (`kicad/`,
`wxwidgets/`, `scripts/`, `docker/`). The web app consumes WASM artifacts produced by the
existing build, it does not build them.

Root `.gitignore` should ignore `web/**/node_modules`, `web/**/dist`, build caches.

---

## 4. Domain model

### 4.1 Entities (Postgres, via Drizzle)  **[decided: Postgres + Drizzle]**

```
owner            -- namespace for "no auth now, multi-user later"
  id             uuid pk
  slug           text unique         -- e.g. "default" now; becomes real users later
  created_at     timestamptz

project
  id             uuid pk
  owner_id       uuid fk -> owner.id
  slug           text                -- URL segment, unique within owner (e.g. "project5")
  name           text                -- human display name
  created_at     timestamptz
  updated_at     timestamptz
  unique(owner_id, slug)

project_file                          -- index of files; bytes live in FileStorage
  id             uuid pk
  project_id     uuid fk -> project.id
  path           text                -- POSIX-relative within project, e.g. "pcbnew/nyak.kicad_pcb"
  size           bigint
  content_type   text
  storage_key    text                -- opaque key handed to FileStorage
  created_at     timestamptz
  updated_at     timestamptz
  unique(project_id, path)
```

- **Owner namespace [decided]**: every project belongs to an `owner`. This iteration uses a
  single seeded owner (`slug = "default"`); the URL omits owner (`/p/:project/...`) and the
  server resolves it to the default owner. Adding real auth later = populate `owner` per
  user and prefix routes, **no schema migration needed**.
- `project_file.path` is the canonical project-relative path. The `storage_key` decouples
  the logical path from however the blob backend names things (so renames/S3 layout are free).

drizzle-zod derives Zod schemas from these tables; those Zod schemas feed the ts-rest
contract so DB ↔ API ↔ client share one source of truth.

### 4.2 What "project" means at the byte level

A project is a directory tree of files (`.kicad_pro`, `.kicad_pcb`, `.kicad_sch`,
`fp-lib-table`, `sym-lib-table`, footprint/symbol lib dirs, etc.). `project_file` rows
enumerate the tree; bytes live behind `FileStorage`.

---

## 5. Storage abstraction  **[decided: pluggable, local now, S3 later]**

`packages/storage` exposes a single interface. The whole iteration is **read-heavy**; write
methods exist so save-back **[later]** needs no redesign.

```ts
export interface FileStorage {
  // read path
  exists(key: string): Promise<boolean>;
  read(key: string): Promise<Uint8Array>;
  createReadStream(key: string): NodeJS.ReadableStream;   // for large files
  stat(key: string): Promise<{ size: number; contentType?: string }>;
  list(prefix: string): Promise<string[]>;                // keys under a prefix

  // write path (used now only by upload; save-back is [later])
  write(key: string, data: Uint8Array | NodeJS.ReadableStream, opts?: { contentType?: string }): Promise<void>;
  delete(key: string): Promise<void>;
}
```

Implementations:
- `LocalDiskStorage` **[now]** — rooted at a configurable dir (`STORAGE_ROOT`), `key` maps
  to a path under it. Streams to/from disk.
- `S3Storage` **[later]** — same interface over an S3-compatible bucket. `docker-compose`
  can run MinIO for local S3 parity when we get there.

Storage key scheme **[default]**: `owners/<owner_id>/projects/<project_id>/<project_file.path>`.
Opaque to callers — only `FileStorage` interprets it.

---

## 6. WASM artifact delivery  **[decided: configurable base location]**

The big artifacts (`pcbnew.wasm` ~350 MB, `eeschema.wasm` ~180 MB, `calculator.wasm`,
their `.js` glue, `wx.js`, `images.tar.gz`) are **app binaries, not user data** — kept
separate from `FileStorage`.

- The frontend resolves every artifact URL from a single configurable base:
  `WASM_ASSET_BASE_URL` **[decided requirement]**.
  - **dev**: points at the Fastify server, which serves the artifacts statically from a
    configurable dir (default `../../output` relative to the server, i.e. repo `output/`).
  - **prod**: points at a public S3/CDN URL. No code change — just env.
- An artifact URL is composed as `${WASM_ASSET_BASE_URL}/${tool}.js` (and the glue then
  fetches the sibling `.wasm` / `worker.js` / `images.tar.gz` from the same base). The
  Emscripten `locateFile` hook must be wired to this base so `.wasm`/`.worker.js` resolve
  correctly regardless of origin.
- **Cross-origin caveat [important]**: KiCad WASM uses threads (`.worker.js` present),
  which needs `SharedArrayBuffer` → the **document** must be served with
  `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`.
  When artifacts come from a different origin (S3/CDN), they must be served with
  `Cross-Origin-Resource-Policy: cross-origin` (or CORS) so they load under COEP. The
  Fastify static route sets COOP/COEP/CORP in dev; the prod bucket/CDN must set CORP/CORS.
  Verify against the existing harness behavior in `tests/apps/kicad/`.

Artifacts are **not committed to git** (they're build outputs). The build pipeline
(`docker/build.sh` → `output/`) remains the source.

---

## 7. URL & routing  **[decided]**

Frontend routes (client-side router) **[default: react-router]**:

| Route | View |
|---|---|
| `/` | Project list + "Create project" |
| `/p/:project` | Project detail: file tree, upload, "open in tool" actions |
| `/p/:project/:tool/*filepath` | **Tool view**: boots `:tool` WASM app, auto-opens `*filepath` |

- `:tool` ∈ `{ pcbnew, eeschema, calculator }` — selects the WASM app **[decided]**.
  (`calculator` takes no file; opening it ignores `*filepath`.)
- `*filepath` is the project-relative path of the file to auto-open
  (e.g. `pcbnew/nyak.kicad_pcb`). It must match a `project_file.path` row.
- `:project` is the project **slug** within the default owner.
- Owner is implicit (default owner) now; route gains an owner segment when auth lands
  **[later]** — `/p/:project/...` is forward-compatible.

Tool→file-extension mapping (for validation / "open with" UI) **[default]**:
`.kicad_pcb → pcbnew`, `.kicad_sch → eeschema`. Mismatches surface a warning but the
explicit `:tool` segment wins (per the decided semantics).

---

## 8. API (ts-rest contract in `packages/contract`)  **[decided: ts-rest + Zod]**

All endpoints under `/api`. Contract is the single typed source; Fastify router
implements it, frontend uses the generated ts-rest react-query client **[default]**.

```
GET    /api/projects                       -> Project[]
POST   /api/projects                       { name, slug? } -> Project          # create [scope]
GET    /api/projects/:project              -> Project + file tree              # open  [scope]
DELETE /api/projects/:project              -> 204                              # [default, nice-to-have]

GET    /api/projects/:project/files                  -> ProjectFile[]
GET    /api/projects/:project/files/*path            -> file bytes (streamed)  # used to fill MEMFS
POST   /api/projects/:project/files                  (multipart) -> ProjectFile[]   # upload [scope]
POST   /api/projects/:project/files/zip              (multipart zip) -> ProjectFile[] # upload-zip [scope]
# write/rename/delete of individual files: interface ready, [later] for save-back
```

Upload handling **[decided: files + folder + zip]**:
- **Individual files (multi)**: multipart; each part carries its target project-relative
  path. Streamed to `FileStorage`, one `project_file` row each.
- **Folder (preserve structure)**: frontend uses `webkitdirectory`; relative paths derived
  from `file.webkitRelativePath` and sent as the per-file path. Server preserves the tree.
- **Zip**: server unpacks (streaming unzip) into the project tree, creating `project_file`
  rows per entry. Reject path traversal (`../`) and absolute paths.

Validation: Zod schemas (shared) validate bodies/params; Fastify JSON-schema serialization
for responses. Errors via a consistent ts-rest error shape **[default]**.

---

## 9. Open-a-file flow (the core of the iteration)

Visiting `/p/:project/:tool/*filepath`:

1. Frontend fetches the project's file tree: `GET /api/projects/:project/files`.
2. Frontend loads the WASM glue for `:tool` from `WASM_ASSET_BASE_URL` and instantiates the
   Emscripten module into a canvas-bearing harness (reuse the proven shell from
   `tests/apps/kicad/pcbnew.html` — `createCanvas`, `images.tar.gz` prefetch+write,
   `locateFile`, status/progress UI), ported into a React component.
3. **Sync whole project tree into MEMFS** **[decided]**: for every `project_file`, fetch its
   bytes (`GET .../files/*path`) and `FS.mkdirTree` + `FS.writeFile` at the project root
   inside MEMFS (mirroring `tests/kicad/utils/fs-inject.ts`). Files land at the path KiCad
   expects (e.g. under the default projects dir, confirmed by `load-pcb-probe.spec.ts`:
   `/home/kicad/documents/kicad/9.99/projects/...`). The exact MEMFS mount point for an
   arbitrary user project is an **open implementation detail** — see §11.
4. Drive File→Open on `*filepath` using the existing element-tracker / menu-driving
   helpers (`tests/e2e/utils/element-tracker.ts`, `tests/kicad/load-pcb.spec.ts`). This UI
   automation already works for the demo boards and is the reference implementation.
5. Render. Read-only — no write-back **[decided]**.

> **[later]** Lazy/partial loading: instead of syncing the whole tree up front, intercept
> MEMFS reads and fetch siblings on demand. This lands **together with save-back/sync**, as
> a single coherent iteration (both need MEMFS↔storage plumbing). Not now.

---

## 10. Frontend detail  **[shadcn decided; rest default]**

- Vite + React + TS, shadcn/ui components, Tailwind.
- Pages: project list (cards + create dialog), project detail (file tree + upload
  dropzone + per-file "open in pcbnew/eeschema" buttons), tool view (full-viewport WASM
  canvas + status overlay).
- Data layer: ts-rest react-query client generated from the contract.
- Upload UX: drag-drop dropzone supporting multi-file, folder (`webkitdirectory`), and
  `.zip`; progress per file; streamed to backend.
- The WASM tool view is a dedicated component that owns the Emscripten lifecycle and tears
  it down on unmount (WebGL context, MEMFS) to allow switching tools/projects.

---

## 11. Open questions for `implement plan` (not blocking this spec)

1. **MEMFS mount point for arbitrary projects.** Demos rely on KiCad's default projects
   path. For a user project we must decide where in MEMFS the tree is written and whether
   pcbnew/eeschema need it under their expected projects dir, or whether File→Open can
   target an arbitrary MEMFS path. Resolve by probing (extend `load-pcb-probe`).
2. **Driving File→Open generically.** Current helpers are tuned to the demo dialog flow
   (filelist bbox click + filename input + Enter). Confirm it generalizes to arbitrary
   paths, or expose a cleaner embind "open file" entry point in the WASM layer.
3. **eeschema/calculator open flows.** Mirror the pcbnew flow; verify eeschema's File→Open
   and that calculator (no file) just boots.
4. **Large-tree sync performance.** Whole-tree sync of a big project over many HTTP
   requests may be slow; consider a single tar/zip stream endpoint to fill MEMFS in one
   shot (still "sync whole tree", just one request). Decide in planning.
5. **COOP/COEP in prod** with cross-origin S3 artifacts — validate header matrix.
6. **Project slug generation/collision** rules; reserved tool names as slugs.

---

## 12. Out of scope this iteration (explicit)

- Auth / login / real multi-user (data model is ready; UI/enforcement is **[later]**).
- WebSocket / realtime / Hocuspocus collaboration (stack chosen to allow it; none built).
- Saving or syncing edits back to storage (**[later]**, paired with lazy load).
- S3 storage implementation (interface ready; **[later]**).
- Editing project files in the browser outside the WASM tools.

---

## 13. Definition of done (this iteration)

- `pnpm install && docker-compose up -d && pnpm dev` in `web/` brings up Postgres,
  Fastify (`/api` + WASM static), and the Vite frontend.
- Create a project from the UI; it appears in the list and in Postgres.
- Open the project; upload files via multi-select, folder, and zip — files appear in the
  tree and in `FileStorage` + `project_file`.
- Navigate to `/p/<slug>/pcbnew/<path>.kicad_pcb`; the board renders read-only, equivalent
  to the existing `tests/kicad/load-pcb` result, sourcing files from project storage.
- Same for an eeschema `.kicad_sch` file.
- Swapping `WASM_ASSET_BASE_URL` between local `output/` and a remote URL requires no code
  change.