louispaulb 41d9b5f316 feat: flow editor, Gemini QR scanner with offline queue, dispatch planning v2

Major additions accumulated over 9 days — single commit per request.

Flow editor (new):
- Generic visual editor for step trees, usable by project wizard + agent flows
- PROJECT_KINDS / AGENT_KINDS catalogs decouple UI from domain
- Drag-and-drop reorder via vuedraggable with scope isolation per peer group
- Chain-aware depends_on rewrite on reorder (sequential only — DAGs preserved)
- Variable picker with per-applies_to catalog (Customer / Quotation /
  Service Contract / Issue / Subscription), insert + copy-clipboard modes
- trigger_condition helper with domain-specific JSONLogic examples
- Global FlowEditorDialog mounted once in MainLayout, Odoo inline pattern
- Server: targo-hub flow-runtime.js, flow-api.js, flow-templates.js
- ERPNext: Flow Template/Run doctypes, scheduler, 5 seeded system templates
- depends_on chips resolve to step labels instead of opaque "s4" ids

QR/OCR scanner (field app):
- Camera capture → Gemini Vision via targo-hub with 8s timeout
- IndexedDB offline queue retries photos when signal returns
- Watcher merges late-arriving scan results into the live UI

Dispatch:
- Planning mode (draft → publish) with offer pool for unassigned jobs
- Shared presets, recurrence selector, suggested-slots dialog
- PublishScheduleModal, unassign confirmation

Ops app:
- ClientDetailPage composables extraction (useClientData, useDeviceStatus,
  useWifiDiagnostic, useModemDiagnostic)
- Project wizard: shared detail sections, wizard catalog/publish composables
- Address pricing composable + pricing-mock data
- Settings redesign hosting flow templates

Targo-hub:
- Contract acceptance (JWT residential + DocuSeal commercial tracks)
- Referral system
- Modem-bridge diagnostic normalizer
- Device extractors consolidated

Migration scripts:
- Invoice/quote print format setup, Jinja rendering
- Additional import + fix scripts (reversals, dates, customers, payments)

Docs:
- Consolidated: old scattered MDs → HANDOFF, ARCHITECTURE, DATA_AND_FLOWS,
  FLOW_EDITOR_ARCHITECTURE, BILLING_AND_PAYMENTS, CPE_MANAGEMENT,
  APP_DESIGN_GUIDELINES
- Archived legacy wizard PHP for reference
- STATUS snapshots for 2026-04-18/19

Cleanup:
- Removed ~40 generated PDFs/HTMLs (invoice_preview*, rendered_jinja*)
- .gitignore now covers invoice preview output + nested .DS_Store

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-22 10:44:17 -04:00

4.8 KiB

Raw Blame History

Gigafibre FSM — Ecosystem Architecture

Unified reference document for infrastructure, platform strategy, and application architecture on the remote Docker environment.

1. Executive Summary & Platform Strategy

Gigafibre FSM represents the complete operations platform for Gigafibre, shifting from a polling-based legacy PHP system to a modern, real-time push ecosystem (Vue 3, Node.js, ERPNext, TR-369).

The strategy pivots around a unified core platform running entirely on a remote Proxmox VM (96.125.196.67):

ERPNext v16 as the undisputed Source of Truth (CRM, billing, ticketing).
Targo Ops PWA as the single pane of glass for internal teams.
Targo Hub as the real-time API gateway (SMS, SSE, AI, TR-069 proxy).
Client.gigafibre.ca for customer self-service.

Legacy Retirement Plan (April-May 2026):

Retire dispatch-app — Functionality now in Ops + lightweight mobile tech page (/t/{token}).
Retire apps/field — Redundant to the mobile tech page workflow.
Retire auth.targo.ca — Fully migrated to id.gigafibre.ca Authentik.

2. Infrastructure & Docker Networks

All services are containerized and housed on a single Proxmox VM (96.125.196.67), managed via Traefik.

Internet
  │
96.125.196.67 (Proxmox VM, Ubuntu 24.04)
  │
  ├─ Traefik v2.11 (:80/:443, Let's Encrypt, ForwardAuth)
  │
  ├─ Authentik SSO (id.gigafibre.ca) → Secures /ops/ and client portal
  │
  ├─ ERPNext v16.10.1 (erp.gigafibre.ca) → 9 containers (db, redis, workers)
  │
  ├─ Targo Ops App (erp.gigafibre.ca/ops/) → Served via nginx:alpine
  │
  ├─ n8n (n8n.gigafibre.ca) → Auto-login proxy wired to Authentik headers
  │
  ├─ Oktopus CE (oss.gigafibre.ca) → TR-369 CPE management
  │
  └─ WWW / Frontend (www.gigafibre.ca) → React marketing site

DNS Configuration (Cloudflare):

Domain gigafibre.ca is strictly DNS-only (no Cloudflare proxy) to allow Traefik Let's Encrypt generation.
Email via Mailjet + Google Workspace records configured on root.

Docker Networks:

proxy: Public-facing network connected to Traefik.
erpnext_erpnext: Internal network for Frappe, Postgres, Redis, and targo-hub routing.

3. Core Services

ERPNext (The Backend)

Database: PostgreSQL (erpnext-db-1).
Extensions: Custom doctypes for Dispatch Job, Technician, Tag, Service Location, Service Equipment, Subscription.
API Token Auth: targo-hub and the Ops PWA interact with Frappe via a highly-privileged service token (Authorization: token ...).

Targo-Hub (API Gateway)

Stack: Node.js 20 (msg.gigafibre.ca:3300).
Purpose: Acts as the middleman for all heavy or real-time workflows out of ERPNext's scope.
Key Abilities:
- Real-time Server-Sent Events (SSE) for timeline/chat updates.
- Twilio SMS / Voice (IVR) routing.
- Modem polling (GenieACS, OLT SNMP proxy).
- Webhooks handling (Stripe payments, Uptime-Kuma, 3CX).

Modem-Bridge

Stack: Playwright/Chromium (:3301 internal).
Purpose: Allows reading encrypted TR-181 parameters from TP-Link XX230v modems by leveraging the modem's native JS cryptography. Exposes a simple JSON REST API locally to targo-hub.

4. Security & Authentication Flow

User → app.gigafibre.ca
  → Traefik checks session via ForwardAuth middleware
  → Flow routed to Authentik (id.gigafibre.ca)
  → Authorized? Request forwarded to native container with 'X-Authentik-Email' header

ForwardAuth (authentik-client@file): Currently protects erp.gigafibre.ca/ops/, n8n, and hub.
API Security: Frontends use the Authentik session proxy; Backend services/scripts use the Authorization: token headers directly hitting Frappe's /api/method.

5. Network Intelligence & CPE Flow

Device Diagnostics (targo-hub → GenieACS / OLT) When a CSR clicks "Diagnostiquer" in the Ops app:

Ops app asks /devices/lookup?serial=X.
targo-hub polls GenieACS NBI.
If deep data is needed, targo-hub queries modem-bridge (for TP-Link) or the OLT SNMP directly.
Returns consolidated interface, mesh, wifi, and opticalStatus array to the UI.

Future: QR Code Flow

Tech applies QR sticker to modem (msg.gigafibre.ca/q/{mac}).
Client scans QR → targo-hub identifies customer via MAC matching in ERPNext.
Triggers SMS OTP → Client views diagnostic portal.

6. Development Gotchas

Traefik v3 is incompatible with Docker 29 due to API changes. Stay on v2.11.
MongoDB 5+ (Oktopus) requires AVX extensions. Proxmox CPU must be set to host.
Never click "Generate Keys" for the Administrator user in ERPNext or it breaks the targo-hub API token.
Traccar API supports only one deviceId per request. Use parallel polling.

4.8 KiB Raw Blame History