# {{Starter Name}} — Spec

*Plain-language spec for {{Starter Name}}. Authoritative — the code matches what's described here.*

> This is the ForStarters.io specification template. The format is permanently
> public at https://forstarters.io/methodology and adopted by every starter in
> the catalog. Adapt for your own project, your team, your domain.

---

## One-liner

{{One sentence. What this is, plainly. No marketing copy.}}

---

## The problem

{{Two to four sentences. The user pain this addresses. Status quo and its costs.
Why building on a starter helps instead of starting from a blank repo.}}

---

## The product

{{What the starter delivers — functional features and the engineering shape they imply.}}

### In the box

- {{Feature 1 — concrete, observable, demonstrable.}}
- {{Feature 2 — same.}}
- {{Feature 3 — same.}}
- {{Add or remove as the surface area demands.}}

### What it's not

- {{Out-of-scope feature 1 — named explicitly so the boundary is visible.}}
- {{Out-of-scope feature 2.}}
- {{Out-of-scope feature 3.}}

---

## Who it's for

{{Primary user / job-to-be-done. One paragraph. Specific persona, not "everyone."}}

**Probably not for:** {{Adjacent audiences that look related but aren't. State the
mismatch in one sentence each.}}

---

## Stack

Base stack (shared across the catalog):

- `typescript` — strict mode; no `any` without justification; no `@ts-ignore` without a linked issue.
- `@tanstack/react-router` + `@tanstack/react-query` — routing and server state.
- `tailwindcss` — styling.
- `msw` — mock API layer; designed to be replaced with your real backend.
- `vitest` + `@playwright/test` — unit and end-to-end testing.

Per-starter additions:

- `{{lib-1}}` — {{why this is here, what it gives you}}.
- `{{lib-2}}` — {{same}}.
- {{Add as needed; remove what doesn't apply.}}

---

## Architecture decisions

{{Material decisions with their rationale. Each is a short paragraph or bullet —
what was chosen, what was considered, why the chosen path won.}}

- **{{Decision name}}** — {{What was chosen}} (alternative: {{what was rejected, why}}).
- **{{Decision name}}** — {{...}}
- **{{Decision name}}** — {{...}}

---

## Data model

{{Core entities and their relationships, when applicable. Use a table for
quick scanning; expand in prose only where the relationship is non-obvious.}}

| Entity | Purpose | Key relationships |
|---|---|---|
| `{{entity}}` | {{purpose}} | {{relationships}} |
| `{{entity}}` | {{...}} | {{...}} |

---

## External dependencies

{{Services this starter depends on at runtime. Name the failure mode so
subscribers know what degrades when each is down.}}

| Service | Used for | Failure mode |
|---|---|---|
| {{Service}} | {{what it provides}} | {{how the app degrades when it's unreachable}} |

---

## Six-pillar audit

Audit pass: {{YYYY-MM-DD}} · Re-runs on every shipping release and on every
material dependency advisory.

| Pillar | Score | Note |
|---|---|---|
| i. security | {{0–100 or `—`}} | {{1-line evidence}} |
| ii. reliability | {{...}} | {{...}} |
| iii. observability | {{...}} | {{...}} |
| iv. performance | {{...}} | {{...}} |
| v. accessibility | {{...}} | {{...}} |
| vi. testability | {{...}} | {{...}} |

Scoring rubric, per-pillar criteria, and the ship bar are at
https://forstarters.io/methodology.

---

## What you'll still need to build

{{The work the starter doesn't do for you — listed so the buyer can size what's
left. This section is mandatory. An empty list is a smell.}}

- {{Gap 1 — e.g., "Replace MSW handlers with your real backend."}}
- {{Gap 2 — e.g., "Decide on file storage if you want attachments."}}
- {{Gap 3 — ...}}

---

## Open questions

{{Decisions still open. Named so subscribers know what's settled and what
isn't. Each entry should have a "lean" — your current thinking — even if it
hasn't been ratified yet.}}

- {{Question}} — Lean: {{current thinking and why}}.
- {{Question}} — Lean: {{...}}.

---

## Roadmap

| Version | Date | Summary |
|---|---|---|
| v {{version}} | {{YYYY-MM-DD}} | {{1-line summary}} |
| v {{version}} | {{YYYY-MM-DD}} | {{...}} |

---

*Adapted from the ForStarters.io specification template —
https://forstarters.io/methodology.*