Here’s a concrete, **handoff-ready plan** you can give to another AI to implement a first version (v1) of a **Spelljammer Ship Tracker** with **multi-ship CRUD, constrained editing, SQLite persistence, and <1s live updates**.

---

## 0) Product goal (v1)

A small phone-friendly web app where your group can:

* Create/select/delete ships (delete requires confirm modal)
* View & edit **core ship stats** + **current weapons on the ship**
* See changes propagate to all connected clients within ~1s
* Persist “real data” server-side in **SQLite** (ship data + weapons + optional reference content)
* Show a **read-only Rules/Reference** screen for battle lookups

No authentication. Anyone can edit anything.

---

## 1) Recommended stack (simple + robust)

**Option A (recommended): Node.js + Fastify + Socket.IO + SQLite (better-sqlite3) + React (Vite)**

* Fast to implement, great websocket support, easy Docker build.
* Socket.IO simplifies reconnects & room-based updates (per ship).
* better-sqlite3 is reliable and fast for low-concurrency apps.

**Option B:** Node.js + Express + ws + SQLite
(also fine, but more manual reconnection & rooms logic)

Either way: **single Docker Compose** with one container; SQLite is a mounted file.

---

## 2) Architecture

### Backend

* REST API for CRUD and initial state fetch.
* WebSocket (Socket.IO) for real-time updates:

  * Clients join a “ship room” when viewing a ship.
  * When any field changes, server:

    1. validates & persists to SQLite
    2. broadcasts an update event to that room

### Frontend

Phone-first layout, 3–4 screens:

1. **Ship List** (create/select/delete)
2. **Ship Dashboard** (core stats + weapons list)
3. **Edit Weapon** (or inline editing)
4. **Rules/Reference** (read-only)

Use constrained controls:

* numeric steppers/sliders for numbers
* dropdowns for enums (size category, maneuverability class, etc.)
* toggles for booleans
* “Add weapon” form with select + numeric inputs

---

## 3) Data model (SQLite)

Implement migrations on startup.

### Tables

**ships**

* `id` TEXT (uuid, PK)
* `name` TEXT (unique-ish, not required but recommended)
* Core stats (examples; adjust to your desired fields):

  * `hull_current` INTEGER NOT NULL
  * `hull_max` INTEGER NOT NULL
  * `armor_current` INTEGER NOT NULL
  * `armor_max` INTEGER NOT NULL
  * `ac` INTEGER NOT NULL
  * `con_save` INTEGER NULL  (or `con_score`)
  * `speed` INTEGER NULL
  * `maneuver_class` TEXT NULL  (enum: A/B/C/D/E/F/S per your rules)
  * `size_category` TEXT NULL
* `notes` TEXT NULL
* `updated_at` INTEGER (unix ms)

**weapons**

* `id` TEXT (uuid, PK)
* `ship_id` TEXT (FK -> ships.id, indexed)
* `name` TEXT NOT NULL
* `type` TEXT NULL (optional enum: siege/arcane/etc.)
* `attack_mod` INTEGER NULL
* `damage` TEXT NULL (freeform like “3d10”)
* `range` TEXT NULL
* `ammo_current` INTEGER NULL
* `ammo_max` INTEGER NULL
* `status` TEXT NULL (enum: ok/damaged/disabled)
* `notes` TEXT NULL
* `sort_order` INTEGER NOT NULL default 0
* `updated_at` INTEGER

**rules_pages** (optional; for read-only reference)

* `id` TEXT PK (e.g., “battle”, “ship-stats”)
* `title` TEXT
* `content_markdown` TEXT
* `updated_at` INTEGER

> Keep rules content as markdown stored in DB **or** ship it as static markdown files in the frontend. For v1, static markdown is simplest.

---

## 4) API design (REST)

### Ships

* `GET /api/ships` → list ships `{id, name, updated_at}`
* `POST /api/ships` → create `{name, initialStats...}` → returns full ship
* `GET /api/ships/:id` → full ship + weapons
* `PATCH /api/ships/:id` → update core stats (validated + constrained)
* `DELETE /api/ships/:id` → delete ship + weapons

### Weapons

* `POST /api/ships/:id/weapons` → add weapon
* `PATCH /api/weapons/:weaponId` → update weapon fields
* `DELETE /api/weapons/:weaponId` → delete weapon

Validation rules (server-enforced):

* current values must be `0 <= current <= max`
* max values must be `>= 0`
* enums must be in allowed set
* name length limits

---

## 5) WebSocket events (Socket.IO)

### Client → Server

* `ship:join` `{shipId}`
* `ship:leave` `{shipId}`
* `ship:update` `{shipId, patch}`  // core stats patch
* `weapon:create` `{shipId, weapon}`
* `weapon:update` `{weaponId, patch}`
* `weapon:delete` `{weaponId}`

### Server → Client (broadcast to ship room)

* `ship:state` `{ship, weapons}` // on join, or after major changes
* `ship:patched` `{shipId, patch, updated_at}`
* `weapon:created` `{shipId, weapon}`
* `weapon:patched` `{shipId, weaponId, patch, updated_at}`
* `weapon:deleted` `{shipId, weaponId}`

Implementation approach:

* On any mutation, server writes to DB then emits event.
* On join, server emits current `ship:state`.
* Clients apply patches locally; on reconnect, re-join and refresh state.

Conflict model:

* **Last write wins** is fine (your requirement). Keep it simple.

---

## 6) Frontend UI details (phone-first)

### Screen 1: Ship List

* List cards: name + “last updated”
* Buttons:

  * “Create ship” (modal with name + optional initial stats)
  * Tap card to open
  * Delete icon → confirm modal (“Delete ship X?”)

### Screen 2: Ship Dashboard

Sections:

1. **Vitals**

   * Hull: current/max (stepper)
   * Armor: current/max
   * AC (stepper)
2. **Mobility**

   * Speed (stepper)
   * Maneuver class (dropdown)
   * Size category (dropdown)
3. **Weapons**

   * List weapons with quick fields (ammo, status)
   * Tap weapon to open “Weapon details”
   * “Add weapon” button
4. **Notes**

   * Multi-line text

Include a top bar:

* Ship name
* “Rules” link/button
* “Back to ships”

### Screen 3: Weapon Details (or modal)

Constrained inputs for ammo/status/attack_mod.
Freeform for damage/range/notes.

### Screen 4: Rules/Reference

* Static markdown viewer with headings + quick links
* Optional “search within rules” (client-side filter)

---

## 7) Persistence + backups

* SQLite file at `/data/spelljammer.sqlite`
* Docker volume mount that path.
* Optional: periodic backup script/cron outside app (copy DB file nightly).

---

## 8) Docker Compose (single service)

* Build a single image that serves both:

  * backend API + websockets
  * frontend static files
* Expose one port (e.g., 3000) to Caddy reverse proxy.

Example structure (for the implementing AI):

* `/server` Fastify app
* `/web` React app build output served by server (or Caddy, but keep simple)

---

## 9) Implementation steps (what the AI should do in order)

1. Create repo scaffold with `/server` and `/web`
2. Implement SQLite schema + migrations
3. Implement REST endpoints + validation
4. Add Socket.IO with rooms:

   * join/leave
   * mutation events that persist + broadcast
5. Build React UI:

   * routing for screens
   * state store (zustand or simple context)
   * socket connection + reconnection handling
6. Wire CRUD flows:

   * list → select → join room → render state
   * edit fields → emit update → optimistic UI
7. Add delete confirmation modal
8. Add rules markdown page (static)
9. Dockerize + compose + test behind Caddy

---

## 10) Acceptance criteria checklist

* ✅ Create ship, appears in list, persists after restart
* ✅ Select ship, see dashboard with core stats + weapons
* ✅ Delete ship requires confirm, removes weapons too
* ✅ All edits propagate to another browser within <1s
* ✅ App is usable on phone (single column layout, large touch targets)
* ✅ SQLite file persists via mounted volume
* ✅ WebSocket reconnect works (refresh state on reconnect)
* ✅ No auth, no user accounts

---

## 11) “Reference guide” integration (v1)

Since you want read-only rules “for during battle”:
Start with a **curated markdown** page that copies only the snippets you frequently need (e.g., maneuverability classes, hull/armor notes, weapon usage, combat steps). You can refine later.

(If you want, I can extract a concise “Battle Reference” page from your PDF and format it as markdown for the AI to drop into `/web/src/rules/battle.md`.)

---

## 12) v1 Implementation Status

**Status: v1 COMPLETE** (implemented 2026-02-19)

All 14 commits have been implemented:

1. ✅ Project scaffold (Fastify + Vite + TypeScript)
2. ✅ SQLite connection + migration system
3. ✅ Ship REST API with Zod validation
4. ✅ Weapon REST API with validation
5. ✅ Socket.IO with rooms + real-time events
6. ✅ React routing + layout (mobile-first dark theme)
7. ✅ Zustand stores + Socket.IO client
8. ✅ Ship List page with create modal
9. ✅ Ship Dashboard (vitals + mobility)
10. ✅ Weapons section (add/edit/detail modals + notes)
11. ✅ Delete confirmation polish
12. ✅ Rules/Reference page (collapsible battle reference)
13. ✅ Dockerfile + docker-compose
14. ✅ README with testing + deployment docs

See `README.md` for full setup, testing, and deployment instructions.