0f8d2b0565
Mass refresh — the docs were last touched 2026-04-22, two weeks behind
shipped reality. This commit updates 9 files to reflect current truth.
WHAT CHANGED IN THE PRODUCT (since 22 Apr) THAT THE DOCS NOW REFLECT:
• Oktopus CE / TR-369 stack decommissioned (containers + volumes +
images all removed; broker had filled /dev/sdb with 75 GB of debug
logs and took ERPNext down for 4 days). Hub gates the integration
behind OKTOPUS_DISABLED=1 — modules retained, no-op'd at runtime.
• dispatch.gigafibre.ca (legacy PHP SPA) replaced by an nginx 301
redirect to /ops/#/dispatch.
• Top toolbar of the dispatch module: collapsed to single-color
Lucide icons + ⋯ overflow menu + "Vue principale ▾" + "[👥 N ▾]"
resource type chip (defaults to techs, materials in the dropdown
only when relevant).
• Tech home base / departure point: editable per-tech via 📍 button,
address geocode (Nominatim) or click-on-map picker, right-click
on tech pin opens the same actions. Map defaults centered on
Gigafibre HQ (1867 chemin de la Rivière, Sainte-Clotilde) instead
of downtown Montreal.
• POST /auth/users invite flow on the hub: creates the Authentik
user, sets a temp password, mails it via Mailjet (Authentik's
own recovery flow isn't configured), creates the matching ERPNext
System User. Surfaced in ops Settings → Utilisateurs → Inviter.
• Two Authentik instances clarified as parallel-and-permanent (not
a migration): auth.targo.ca for staff, id.gigafibre.ca for clients.
FILES TOUCHED:
README.md — service table refreshed, arch diagram redrawn (no
Oktopus row), auth section explains the invite flow + two
parallel instances.
docs/architecture/overview.md — new "Decommissioned" section,
correct retirement status for dispatch-app + apps/field, two
Authentik instances explicitly distinguished, dev-gotchas list
rewritten (drops MongoDB AVX, adds log-rotation hard-learned
lesson, adds note about Authentik recovery flow).
docs/architecture/data-model.md — Step 5 hardware provisioning
now describes the GenieACS path (TR-069 Inform → preset push)
instead of the dead TR-369 path.
docs/architecture/module-interactions.md — oktopus.js and
oktopus-mqtt.js entries marked as gated, provision.js note
updated, GenieACS row in external-integrations updated, MQTT
row removed from real-time channels, interaction matrix loses
the Oktopus column and gains an Authentik admin REST cell.
docs/features/dispatch.md — Top bar section completely rewritten
to match the current chrome (left/center/right regions,
single-color Lucide, dropdowns); new Tech home base section
documenting the 📍 + map-pick + right-click flows; retirement
note now reads as a status, not a plan.
docs/features/cpe-management.md — full rewrite. Oktopus migration
plan replaced by a "decommissioned" note + the existing GenieACS
+ modem-bridge architecture as the steady state. TP-Link XX230v
deep-dive sections preserved (still accurate).
docs/README.md, docs/features/README.md, docs/roadmap.md —
intent-table descriptions and live-URLs table corrected.
The docs/archive/ snapshots (2026-04-18, 2026-04-19) are untouched —
they're historical and should remain that way.
12 KiB
12 KiB
Gigafibre FSM — Roadmap
Live phase tracker. For onboarding or architecture context see README.md. Historical status snapshots live under archive/status-snapshots/.
Last refreshed: 2026-04-22
Modules in production — quick links
Everything in this table is reachable from a browser today (Authentik SSO for staff surfaces, Stripe Checkout for customer ones).
Ops app — https://erp.gigafibre.ca/ops/
| Module | URL | Purpose |
|---|---|---|
| Dashboard | /ops/#/ | Home |
| Clients | /ops/#/clients | Customer list + detail |
| Dispatch | /ops/#/dispatch | Timeline, drag-drop, map |
| Tickets | /ops/#/tickets | Issue management |
| Équipe | /ops/#/equipe | Technician directory |
| Rapports | /ops/#/rapports | Revenu / Ventes / Taxes / AR |
| OCR | /ops/#/ocr | Invoice OCR (Gemini) |
| Téléphonie | /ops/#/telephony | PBX + SIP |
| Agent flows | /ops/#/agent-flows | Flow editor |
| Réseau | /ops/#/network | GenieACS / OLT / TR-069 |
| Settings | /ops/#/settings | Config |
Tech mobile (same app, mobile layout) — /j/*
| Page | URL | Purpose |
|---|---|---|
| Tasks | /ops/#/j | Tech's assigned jobs |
| Scan | /ops/#/j/scan | Camera scanner, auto-link |
| Device | /ops/#/j/device/:serial |
Equipment detail + relationships |
| Diagnostic | /ops/#/j/diagnostic | ONT/OLT/SNMP probe |
Customer portal — https://portal.gigafibre.ca
| Page | URL | Purpose |
|---|---|---|
| Dashboard | / | Balance + quick actions |
| Account | /#/me | Profile + cards (Stripe Billing Portal) |
| Invoices | /#/invoices | History + pay (Stripe Checkout + Klarna) |
| Tickets | /#/tickets | Open tickets |
| Messages | /#/messages | SMS / email thread with support |
| Catalog | /#/catalog | Add-on purchases |
Admin surfaces (non-ops)
| Service | URL | Stack |
|---|---|---|
| ERPNext | erp.gigafibre.ca | Frappe v16 / PostgreSQL |
| Authentik SSO (staff) | auth.targo.ca | OAuth provider for ERPNext + ForwardAuth for ops/n8n/Gitea |
| Authentik SSO (clients) | id.gigafibre.ca | Customer portal — separate instance, not federated |
| DocuSeal | sign.gigafibre.ca | Contract signing |
| n8n | n8n.gigafibre.ca | Workflow automation |
| GenieACS | internal 10.5.2.115:7557 |
TR-069 NBI — sole CPE controller (Oktopus decommissioned May 2026) |
| Traccar | tracker.targointernet.com | GPS tracking |
| Website | www.gigafibre.ca | Marketing + address lookup |
Phase 1 — Foundation (Done, March 2026)
- ERPNext v16 + PostgreSQL
- Custom FSM doctypes (Service Location, Equipment, Subscription) → see architecture/data-model.md
- Dispatch doctypes (Job, Technician, Tag with skill levels)
- Dispatch PWA with timeline, drag-drop, Mapbox map → /ops/#/dispatch
- 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 → /ops/#/clients
- Dispatch module + ticket management → /ops/#/dispatch, /ops/#/tickets
- Equipment tracking with OLT/SNMP diagnostics → /ops/#/network
- SMS/Email notifications (Twilio + Mailjet)
- Invoice OCR — migrated from Ollama Vision to Gemini 2.5 Flash via targo-hub (2026-04-22, no GPU on ops VM). See features/vision-ocr.md → /ops/#/ocr
- Field tech mobile → /ops/#/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 (In Progress)
- Deprecate local
frappe_dockerdevelopment dependencies - Consolidate architecture and ecosystem documentation (this reorg, 2026-04-22)
- 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-vuedevelopment - 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=1until cutover event. Legacy PHP is authoritative until then.
Phase 2.6 — Quotation + DocuSeal (Shipped 2026-04-18)
- DocuSeal container → sign.gigafibre.ca
- 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 features/vision-ocr.md
for the scan pipeline this depends on.
Step 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 → /ops/#/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: features/vision-ocr.md (pipeline, §10 relationship graph, §8.1 secrets/rotation)
Step 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/
Step 3 — Auth unification
- Collapse logout URL to
id.gigafibre.ca(currently ops points toauth.targo.ca) - Decide whether
/j/*stays behind Authentik forwardAuth or moves to magic-link only
Step 4 — 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)
Step 5 — Flow runtime integration
- Wire
flow-runtimeto persist pending steps throughoffline.queueso a tech mid-flow survives a dead zone - Surface queued flow state in TechTasksPage ("3 actions en attente de sync")
Step 6 — Remove apps/field
git rm -r apps/fieldonce/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 architecture/overview.md service table (drop field row)
Phase 3 — Workflows & Automation (In Progress)
- Tag technicians with skills (46 techs to tag) → /ops/#/equipe
- Wire auto-dispatch (cost-optimization matching)
- Issue → Dispatch Job creation (triggered from /ops/#/tickets)
- Job completion → equipment status + close ticket
- Equipment swap → inventory log
- Flow editor (v1 shipped) → /ops/#/agent-flows — see features/flow-editor.md
- n8n escalation workflows → n8n.gigafibre.ca
- Twilio 10DLC production upgrade
- SLA tracking
Phase 4 — Customer Portal (Largely Shipped)
Portal Vue SPA lives at portal.gigafibre.ca.
All 16 /payments/* hub endpoints ship; see
features/billing-payments.md for the full flow.
- Self-service app → portal.gigafibre.ca (13 pages: Dashboard, Invoices, Account, Tickets, Messages, Catalog, Cart, …)
- Stripe payments → pay-balance, pay-invoice, save-card, Billing Portal, refund, PPA auto-pay cron (daily 06:00 EST). Klarna BNPL supported on invoice payments.
- Webhook handler with signature verification (5-min tolerance) →
/webhook/stripe - Payment links via SMS + email (
/payments/send-link) - Magic-link redirect after Stripe return (
/payments/return→ portal) - Passwordless portal login (
POST /portal/request-link, email/SMS, 3/15min rate-limited, anti-enumeration) — ERPNext/loginretired onclient.gigafibre.ca(Traefik redirect →/#/login). MD5 migration moot. - Online appointment booking
- Real-time tech tracking SMS
- QR code on modem → subscriber dashboard (
msg.gigafibre.ca/q/{mac})
Phase 5 — Advanced Features
- Van stock inventory per tech
- Revenue analytics (MRR, churn, ARPU) → extend /ops/#/rapports
- Proactive monitoring (auto-ticketing)
- Online checkout (e-commerce signup via www.gigafibre.ca)
- Marketing segmentation + campaigns
- Tech performance dashboards
- Preventive maintenance scheduling