# EA App — Product Roadmap

**Method:** final product first, worked backwards to today. Each version is a usable
product on its own; no version requires throwing away a previous one. This file is the
living planning doc — brainstorm in the *Open questions* sections, record choices in the
*Decision log*, and check each build session against the current version's scope.

Companion docs: `EA_Part1_SYSTEM.md` (study-system spec, esp. §6 webapp spec),
`deploy/DREAMHOST_NOTES.md` (live server setup),
`EA Part 1 Game and Question banks/README.md` (bank format + authoring workflow).

---

## The two load-bearing architecture rules (apply to every version)

1. **Content is data; apps are thin readers.** Question banks, topic modules, guides,
   crosswalk — all structured files in this repo. No app embeds content it could read.
   (Trap Hunt and the study-app violate this by baking data in at build time — accepted
   for the games, not for the V1+ study system.)
2. **The annual tax-year refresh is the product.** EA prep expires every exam window.
   Everything that makes re-verification cheap (year-sensitivity tags, `validate.js`,
   the §5 content factory, IRS-only citations) is the moat and must never be shortcut.

---

## V3 — The product: "EA Exam Academy" (multi-user, paid)

The Stars & Rights product shape (like usct/canada citizenship prep) applied to the EA
exam. Part 1 first; Parts 2–3 reuse the entire engine with new content.

- Accounts (JWT), Stripe subscription, server-side progress + SRS state (sync across
  devices), admin content dashboard. Same stack already running at api.starsandrights.com
  (Node/Express + MySQL) — a port of an owned pattern, not new invention.
- The games (Trap Hunt, 1040 City) stay free as acquisition/marketing hooks; the study
  system + full sims + SRS become the paid tier.
- Annual "TY20XX edition" refresh as the subscription justification.
- **Precondition:** Shakil has passed Part 1 using V2 (the product's proof point), and V2
  usage has shown what's actually worth paying for.

### Open questions (V3)
- Pricing: one-time vs. subscription vs. exam-window pass?
- Free tier boundary: how many free questions/day before paywall?
- Part 2/3 content: author again via the §5 factory, or partner/license?
- Separate API subdomain (api-ea.starsandrights.com) or extend an existing backend?

---

## V2 — The complete single-user study system

`EA_Part1_SYSTEM.md` §6 fully built + content complete. This is what gets Shakil through
the exam; a beta tester could use it as-is. Everything localStorage; no backend.

**Engine (builds on V1):**
- Flashcard SRS — SM-2-style intervals over every `05_flashcards.csv` (and optionally the
  field guides' Figure Vault); due-card queue as the daily warm-up.
- **Weighted full-length simulations** — 85 questions drawn to the real 14/17/17/15/11/11
  domain blueprint, 1.5 min/question timer, Prometric-style review screen.
- Confidence heatmap dashboard — per-section confidence from `meta.yaml` × domain weight,
  answering "which heavy domain is weakest?"
- Trap-library viewer + search across notes/glossary.
- Media embed per topic (visuals exist; NotebookLM audio when produced).

**Content (authored on the Cowork side, in the §3 sprint sequence):**
- Topic modules for Domains 2–6 (only `d1-foundation` exists today).
- Question bank grown to the 600 target (D1 99 · D2 120 · D3 120 · D4 184 · D5 78),
  ~25% in case chains.

### Open questions (V2)
- SRS scheduling: pure SM-2, or simplified 3-bucket (again/good/easy)?
- Should sim results feed topic `confidence` in meta.yaml automatically, or stay separate?
- Timer behavior: hard cutoff like Prometric, or soft pacing indicator?
- Do the games' scores feed the same progress store?

---

## V1 — Unify what exists (SHIPPING NOW — first cut 2026-07-02)

Today's three apps are silos with baked-in copies of the data and no shared memory.
V1 adds `/app` — the thin no-build reader the spec §6 calls for — against the data that
already exists, plus shared local progress.

**Scope of the first cut (what ships today):**
1. **Practice engine** — loads every `bank-*.json` live (via a server-generated
   manifest), filter by domain and/or trap species, pick a count, answer with instant
   explanation + IRS ref, case-chain setups shown for case questions, session results
   broken down by trap and domain. Soft pace indicator vs. 1.5 min/question.
2. **Topic browser** — lists `content/**` modules from `meta.yaml`, renders `01_notes.md`,
   shows `02_visual.svg`, drills that topic's `03_questions.json` (module format
   normalized to the bank format), flips through `05_flashcards.csv` as simple cards.
3. **Progress (local)** — one localStorage store: per-question seen/correct history
   (keyed by permanent question id → future SRS-ready), accuracy by domain and by trap,
   per-topic drill scores. This store's shape is the contract V3's backend will sync.
4. **Manifest generation** — `deploy/post-pull.sh` regenerates `app/manifest.json`
   (bank file list + topic module list) after every cron pull, so new bank batches and
   new topic modules appear in the app with zero app-code changes.

**Deliberately NOT in V1:** SRS scheduling, weighted full sims, confidence heatmap,
search, trap-library viewer, accounts. (All V2.)

### Open questions (V1 — brainstorm here)
- Navigation: is domain+trap filtering enough, or add district/building (city map) level?
- Should wrong answers auto-queue into a "retry pile" (poor-man's SRS) before real SRS?
- Flashcards: keep the plain flipper, or hide until V2's SRS so there's one card habit?
- Mobile: V1 is responsive-basic; does phone study matter enough to polish now?

---

## V0 — Foundation (DONE 2026-07-02)

- Repo cloned as web root at https://ea.starsandrights.com (Apache, HTTPS, DreamHost).
- Branded landing hub linking Study App, Trap Hunt, 1040 City; short URLs
  `/study` `/traphunt` `/city`; `/.git` + `/deploy` blocked.
- Auto-deploy: cron `git pull --ff-only` every 5 min (push → live ≤5 min).
- Server can push (write deploy key) so app work done on the VPS is versioned.

---

## Data contracts (what V1 depends on; don't break silently)

| Data | Shape | Consumed by |
|---|---|---|
| `bank-*.json` | `schema.json` (draft-07): `q`, `options[]`, `answer` = index, `explain`, `ref`, `trap`, `domain`, `caseId` → `cases[]` | Practice engine, Trap Hunt |
| `content/*/*/03_questions.json` | `stem`, `options{A..D}`, `answer` = letter, `rationale`, `distractors{}` | Topic drills (normalized in app.js) |
| `content/*/*/meta.yaml` | `section_id, title, domain, phase, tax_year, status, confidence, assets{}` | Topic browser |
| `05_flashcards.csv` | `front,back,tags` | Card flipper (V1), SRS (V2) |
| Question `id` | **Permanent — never reuse a deleted id** | Progress store keys on it |
| `app/manifest.json` | Generated by `deploy/post-pull.sh`; **gitignored**, exists only on the server | app.js bootstrap |

---

## Decision log

| Date | Decision | Why |
|---|---|---|
| 2026-07-02 | Serve from DreamHost Apache working tree; cron pull (not GitHub Action) | Zero secrets/attack surface; 5-min latency acceptable |
| 2026-07-02 | New files committed to repo (write deploy key) | Versioned + matches DEPLOYMENT_PLAN §4 split |
| 2026-07-02 | V1 = thin reader over live data files; games stay as-is | Bank is the asset; readers stay replaceable |
| 2026-07-02 | Manifest generated server-side post-pull, not committed | Keeps no-build promise; new content auto-appears |
| 2026-07-02 | Progress store keyed by permanent question ids | Forward-compatible with V2 SRS and V3 account sync |