# Gigafibre FSM — Documentation

> **Start here.** Everything you need to understand the system is one or two
> clicks away. Pick the row that matches why you're here.

---

## Quick nav by intent

| I want to… | Open |
|---|---|
| **See the plan** — what's shipped, what's queued, with clickable links to every live module | [roadmap.md](roadmap.md) |
| **Understand the system end-to-end** — services, containers, networks, SSO, Traefik routes | [architecture/overview.md](architecture/overview.md) |
| **Build a new feature** — UI patterns, folder layout, router conventions, Pinia, feature-sliced design | [architecture/app-design.md](architecture/app-design.md) |
| **Touch ERPNext data** — doctypes, customer → subscription → equipment → invoice, "Lead to Live" flow | [architecture/data-model.md](architecture/data-model.md) |
| **Work on billing, Stripe, payments** — subscription lifecycle, invoice OCR, payment reconciliation, PPA | [features/billing-payments.md](features/billing-payments.md) |
| **Touch CPE / modems / ONTs** — GenieACS, Oktopus, TR-069 → TR-369 migration, TP-Link XX230v diagnostics | [features/cpe-management.md](features/cpe-management.md) |
| **Build or debug the scanner / OCR** — Gemini vision pipeline, barcode/equipment/invoice endpoints, offline queue, AI_API_KEY rotation | [features/vision-ocr.md](features/vision-ocr.md) |
| **Work on agent flows / automation** — Flow Template model, trigger wiring, step editor, runtime contract | [features/flow-editor.md](features/flow-editor.md) |
| **Audit the wizard's SKU mapping vs legacy** | [reference/erpnext-item-diff.md](reference/erpnext-item-diff.md) |
| **Inspect the legacy PHP wizard** | [reference/legacy-wizard/](reference/legacy-wizard/) |
| **Read a historical status snapshot** | [archive/status-snapshots/](archive/status-snapshots/) |

---

## Folder map

```text
docs/
├── README.md                    ← you are here
├── roadmap.md                   ← phase tracker + live module URLs
├── architecture/                ← the system itself
│   ├── overview.md              (services, Docker, Traefik, SSO, retirement plan)
│   ├── data-model.md            (ERPNext doctypes + "Lead to Live")
│   └── app-design.md            (Vue/Quasar patterns, feature-sliced layout)
├── features/                    ← one doc per business capability
│   ├── billing-payments.md      (Stripe, invoices, subscriptions, PPA)
│   ├── cpe-management.md        (GenieACS, Oktopus, XX230v)
│   ├── vision-ocr.md            (Gemini, scan pipeline, offline queue, keys)
│   └── flow-editor.md           (Flow Template, triggers, runtime)
├── reference/                   ← lookup material
│   ├── erpnext-item-diff.md     (new SKUs vs legacy gestionclient)
│   └── legacy-wizard/           (read-only snapshot of the PHP wizard)
├── assets/                      ← PPTX decks, screenshots, generated diagrams
└── archive/                     ← frozen docs, do not edit
    ├── HANDOFF-2026-04-18.md
    ├── MIGRATION.md
    ├── LEGACY-ACCOUNTING-ANALYSIS.md
    └── status-snapshots/        (dated session reports)
```

---

## Conventions

- **Edit in place.** Don't copy-paste a section into a new file — link to it instead.
- **Dated snapshots go to `archive/status-snapshots/`.** Don't create `STATUS_YYYY-MM-DD.md` at the root anymore.
- **Code comments that reference a doc** use the full repo-relative path, e.g.
  `// See docs/features/vision-ocr.md §10` — so `grep docs/` still surfaces them if we reorganize again.
- **The root `README.md`** (one level up) is the repo introduction for
  non-technical readers; `docs/README.md` (this file) is the engineering index.

---

## What changed on 2026-04-22

The docs were flattened out of a single folder into `architecture/`,
`features/`, `reference/`, `archive/`. Every file move used `git mv` so
`git log --follow` still works. The old paths
(`docs/ARCHITECTURE.md`, `docs/VISION_AND_OCR.md`, etc.) no longer exist — if
you land on one of those links from an external bookmark, use the table above
to find the new location.

The only place old names still appear is inside
`archive/HANDOFF-2026-04-18.md` and `archive/status-snapshots/*.md`, where the
links are intentionally preserved as a frozen historical record.