gigafibre-fsm/docs/ROADMAP.md

Gigafibre FSM — Roadmap

See STATUS_2026-04-18.md for a full state snapshot and HANDOFF.md for the reader's guide.

Phase 1 — Foundation (Done, March 2026)

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

Phase 2 — Ops App (Done, March 2026)

• Unified ops PWA (erp.gigafibre.ca/ops/)
• Client list/detail with inline editing (Odoo-style)
• Dispatch module + ticket management
• Equipment tracking with OLT/SNMP diagnostics
• SMS/Email notifications (Twilio + Mailjet)
• 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.
• Field tech mobile (/j/, unified into ops app — see Phase 2.7)
• Authentik federation (staff → client SSO)
• Modem-bridge (Playwright headless for TP-Link ONU diagnostics)
• WiFi diagnostic panel (mesh topology, client signal, packet loss)

Phase 2.5 — Remote Architecture Transition (Current Focus)

• Deprecate local frappe_docker development dependencies
• 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)

• DocuSeal container at sign.gigafibre.ca (Docker + Mailjet SMTP)
• Hub routes: /accept/generate, /accept/docuseal-webhook, /accept/confirm
• Quotation custom fields: custom_docuseal_signing_url, custom_docuseal_envelope_id, custom_quote_type
• Billing Frequency Custom Field on Item + Quotation/Sales Invoice/Sales Order Item (fetch_from item_code)
• Print Format "Soumission TARGO" with split Recurring / One-time sections and QR → signing URL
• 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 for the scan pipeline this depends on.

Phase 1 — scan + device (Shipped 2026-04-22, commit e50ea88)

• Invoice OCR on Gemini 2.5 Flash via hub /vision/invoice — ops VM no longer needs a GPU
• Ollama proxy blocks removed from ops + field nginx configs
• Offline store (apps/ops/src/stores/offline.js) — mutation queue + vision queue, time-driven retries, idb-keyval persistence
• Unified scanner composable (useScanner.js) with Mode A (barcodes, 8s timeout + queue) and Mode B (equipment label, sync)
• TechScanPage at /j/scan — camera, 3-tier lookup (serial → barcode → MAC), auto-link to Dispatch Job context, create/link dialogs
• TechDevicePage at /j/device/:serial — 7 cards surfacing full ERPNext relationship graph (Equipment, Customer, Location, Subscription, Issues, Dispatch Jobs, OLT)
• 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