# Gigafibre FSM — Roadmap

> See [STATUS_2026-04-18.md](STATUS_2026-04-18.md) for a full state snapshot and [HANDOFF.md](HANDOFF.md) for the reader's guide.


## Phase 1 — Foundation (Done, March 2026)
- [x] ERPNext v16 + PostgreSQL
- [x] Custom FSM doctypes (Service Location, Equipment, Subscription)
- [x] Dispatch doctypes (Job, Technician, Tag with skill levels)
- [x] Dispatch PWA with timeline, drag-drop, Mapbox map
- [x] GPS tracking (Traccar hybrid REST + WebSocket)
- [x] Authentik SSO (forwardAuth)
- [x] ERPNext API proxy (nginx same-origin)
- [x] Legacy migration (6,667 customers, 21K subs, 115K invoices, 242K tickets)

## Phase 2 — Ops App (Done, March 2026)
- [x] Unified ops PWA (erp.gigafibre.ca/ops/)
- [x] Client list/detail with inline editing (Odoo-style)
- [x] Dispatch module + ticket management
- [x] Equipment tracking with OLT/SNMP diagnostics
- [x] SMS/Email notifications (Twilio + Mailjet)
- [x] Invoice OCR — originally Ollama Vision, migrated to Gemini 2.5 Flash via targo-hub (2026-04-22, no GPU on ops VM). See [VISION_AND_OCR.md](VISION_AND_OCR.md).
- [x] Field tech mobile (/j/, unified into ops app — see Phase 2.7)
- [x] Authentik federation (staff → client SSO)
- [x] Modem-bridge (Playwright headless for TP-Link ONU diagnostics)
- [x] WiFi diagnostic panel (mesh topology, client signal, packet loss)

## Phase 2.5 — Remote Architecture Transition (Current Focus)
- [x] Deprecate local `frappe_docker` development dependencies
- [x] Consolidate architecture and ecosystem documentation
- [ ] Decouple API/Auth (Token-based auth instead of session for frontend apps)
- [ ] Set up dev proxy (Vite) to bridge local env to remote ERPNext API (bypassing CORS)
- [ ] Establish secure PostgreSQL tunnel for `infra-map-vue` development
- [ ] **Sandboxed outbound comms** (required before any scheduler/webhook/Twilio/Mailjet E2E test) — prevents test runs from reaching real customers while legacy still bills
- [ ] Subscription → Sales Invoice scheduler: keep `pause_scheduler=1` until cutover event. Legacy PHP is authoritative until then.

## Phase 2.6 — Quotation + DocuSeal (Shipped 2026-04-18)
- [x] DocuSeal container at sign.gigafibre.ca (Docker + Mailjet SMTP)
- [x] Hub routes: `/accept/generate`, `/accept/docuseal-webhook`, `/accept/confirm`
- [x] Quotation custom fields: `custom_docuseal_signing_url`, `custom_docuseal_envelope_id`, `custom_quote_type`
- [x] Billing Frequency Custom Field on Item + Quotation/Sales Invoice/Sales Order Item (fetch_from item_code)
- [x] Print Format "Soumission TARGO" with split Recurring / One-time sections and QR → signing URL
- [x] Wizard flow: ProjectWizard → `/accept/generate` → DocuSeal submission → signed webhook → `acceptQuotation()`
- [ ] Register DocuSeal webhook in UI (Settings → Webhooks, `form.completed` → hub endpoint) — **manual**
- [ ] First end-to-end signed acceptance on a real customer quote

## Phase 2.7 — Field ↔ Ops unification at /j (In Progress, started 2026-04-22)

Collapse `apps/field` into `apps/ops/src/modules/tech` so there is one
PWA, one deploy, one auth surface. See [VISION_AND_OCR.md](VISION_AND_OCR.md)
for the scan pipeline this depends on.

**Phase 1 — scan + device (Shipped 2026-04-22, commit `e50ea88`)**
- [x] Invoice OCR on Gemini 2.5 Flash via hub `/vision/invoice` — ops VM no longer needs a GPU
- [x] Ollama proxy blocks removed from ops + field nginx configs
- [x] Offline store (`apps/ops/src/stores/offline.js`) — mutation queue + vision queue, time-driven retries, idb-keyval persistence
- [x] Unified scanner composable (`useScanner.js`) with Mode A (barcodes, 8s timeout + queue) and Mode B (equipment label, sync)
- [x] TechScanPage at `/j/scan` — camera, 3-tier lookup (serial → barcode → MAC), auto-link to Dispatch Job context, create/link dialogs
- [x] TechDevicePage at `/j/device/:serial` — 7 cards surfacing full ERPNext relationship graph (Equipment, Customer, Location, Subscription, Issues, Dispatch Jobs, OLT)
- [x] Documentation: `docs/VISION_AND_OCR.md` (pipeline, §10 relationship graph, §8.1 secrets/rotation)

**Phase 2 — PWA hardening**
- [ ] Quasar service worker runtime caching scoped to `/j/*` (stale-while-revalidate for reads, network-first for mutations)
- [ ] Precache the tech route manifest so a cold install with no signal still boots `/j/`

**Phase 4 — Auth unification**
- [ ] Collapse logout URL to `id.gigafibre.ca` (currently ops points to `auth.targo.ca`)
- [ ] Decide whether `/j/*` stays behind Authentik forwardAuth or moves to magic-link only

**Phase 5 — Magic-link tech access**
- [ ] Traefik skip Authentik on `/j/{jwt-token}` route
- [ ] targo-hub `/otp/tech-link` — mint short-lived JWT bound to technician + job
- [ ] JWT validation in TechTasksPage → populate tech context without an SSO session
- [ ] SMS delivery of the link (reuse existing Twilio path)

**Phase 6 — Flow runtime integration**
- [ ] Wire `flow-runtime` to persist pending steps through `offline.queue` so a tech mid-flow survives a dead zone
- [ ] Surface queued flow state in TechTasksPage ("3 actions en attente de sync")

**Phase 7 — Remove apps/field**
- [ ] `git rm -r apps/field` once `/j/*` has parity and has run in production for ≥2 weeks
- [ ] Remove field build + deploy from CI
- [ ] Redirect `*.field.gigafibre.ca` (if any) → `erp.gigafibre.ca/ops/#/j/`
- [ ] Update `docs/ARCHITECTURE.md` service table (drop field row)

## Phase 3 — Workflows & Automation (In Progress)
- [ ] Tag technicians with skills (46 techs to tag)
- [ ] Wire auto-dispatch (cost-optimization matching)
- [ ] Issue → Dispatch Job creation
- [ ] Job completion → equipment status + close ticket
- [ ] Equipment swap → inventory log
- [ ] n8n escalation workflows
- [ ] Twilio 10DLC production upgrade
- [ ] SLA tracking

## Phase 4 — Customer Portal
- [ ] Self-service app (invoices, tickets, equipment)
- [ ] Stripe payments
- [ ] Online appointment booking
- [ ] Real-time tech tracking SMS
- [ ] Legacy password migration (MD5 → PBKDF2)
- [ ] QR code modem → subscriber dashboard

## Phase 5 — Advanced Features
- [ ] Van stock inventory per tech
- [ ] Revenue analytics (MRR, churn, ARPU)
- [ ] Proactive monitoring (auto-ticketing)
- [ ] Online checkout (e-commerce signup)
- [ ] Marketing segmentation + campaigns
- [ ] Tech performance dashboards
- [ ] Preventive maintenance scheduling