gigafibre-fsm/README.md

Gigafibre FSM

Gigafibre FSM is the operations platform for Gigafibre (consumer brand of TARGO Internet), a fiber ISP in Quebec. It replaces a legacy PHP/MariaDB billing system with ERPNext v16 + Vue 3/Quasar apps for ops, dispatch, field service, and customer self-service.

Repository Structure

gigafibre-fsm/
  apps/
    ops/           Targo Ops -- main operations PWA (Vue 3 / Quasar v2)
    field/         Targo Field -- mobile app for technicians
    client/        Gigafibre Portal -- customer self-service
    website/       www.gigafibre.ca -- marketing site (React / Vite / Tailwind)
    portal/        Customer portal deploy configs
  services/
    targo-hub/     Node.js API gateway (ERPNext, GenieACS, Twilio, Traccar)
    modem-bridge/  SNMP/TR-069 bridge for CPE diagnostics
    legacy-db/     Legacy MariaDB read-only access
    docuseal/      Document signing service
  erpnext/         Custom doctype setup scripts (setup_fsm_doctypes.py)
  scripts/
    migration/     51 Python scripts for legacy-to-ERPNext data migration
    bulk_submit.py, fix_ple_*.py/sh -- PostgreSQL patches, bulk ops
  docs/            Architecture, infrastructure, migration, strategy docs
  docker/          Docker compose fragments
  patches/         ERPNext patches

Architecture

           Internet
              |
    96.125.196.67 (Proxmox VM, Ubuntu 24.04, Docker)
              |
        Traefik v2.11 (TLS via Let's Encrypt)
              |
   +----------+----------+----------+----------+----------+
   |          |          |          |          |          |
ERPNext    Ops PWA   Authentik    n8n     Website    Oktopus
erp.       erp.      auth.       n8n.    www.       oss.
gigafibre  gigafibre  targo.ca    giga    giga       giga
.ca        .ca/ops/              fibre   fibre      fibre
                                 .ca     .ca        .ca
              |
         targo-hub (API gateway)
              |
   +----------+----------+----------+
   |          |          |          |
GenieACS   Twilio    Traccar   modem-bridge
(TR-069)   (SMS)     (GPS)     (SNMP/TR-069)

Services & Dependencies

Service	URL	Port	Stack	Purpose
ERPNext	erp.gigafibre.ca	8080	Frappe v16, PostgreSQL	ERP backend, API
Ops PWA	erp.gigafibre.ca/ops/	80	Vue 3, Quasar, Pinia	Staff operations app
targo-hub	internal	3100	Node.js, Express	API gateway to external services
modem-bridge	internal	3200	Node.js	SNMP/TR-069 CPE diagnostics
Authentik	auth.targo.ca / id.gigafibre.ca	9000	Python, PostgreSQL	SSO (staff + customers)
n8n	n8n.gigafibre.ca	5678	Node.js	Workflow automation (SMS, email)
Traefik	--	80/443	Go	Reverse proxy, TLS, forwardAuth
Oktopus	oss.gigafibre.ca	8428	Go	TR-069 CPE management
Website	www.gigafibre.ca	80	React, Vite, Tailwind	Marketing site + address API
Traccar	tracker.targointernet.com	8082	Java	GPS tracking for techs

ERPNext Custom Doctypes

Doctype	ID Pattern	Purpose
Service Location	LOC-#####	Customer premises (address, GPS, OLT port, network config)
Service Equipment	EQP-#####	Deployed hardware (ONT, router, TV box -- serial, MAC, IP)
Service Subscription	SUB-#####	Active service plans (speed, price, billing, RADIUS)
Dispatch Job	DJ-#####	Work orders with equipment, materials, checklist, photos, signature
Dispatch Technician	DT-#####	Tech profiles with GPS (Traccar), skills, color coding
Dispatch Tag	--	Skill/service/region tags with levels (Fibre, TV, Telephonie, etc.)

Key Custom Fields

Doctype	Custom Fields
Customer	legacy_account_id, legacy_customer_id, ppa_enabled, stripe_id
Item	legacy_product_id, download_speed, upload_speed, olt_profile
Subscription	radius_user, radius_pwd, legacy_service_id
Issue	legacy_ticket_id, assigned_staff, issue_type, is_important, service_location

Tech Stack

Frontend: Vue 3, Quasar v2, Pinia, Vite, Mapbox GL JS Backend: ERPNext v16 / Frappe (Python), PostgreSQL, Node.js (targo-hub) Infra: Docker, Traefik v2.11, Authentik SSO, Proxmox Integrations: Twilio (SMS), Mailjet (email), Stripe (payments), Traccar (GPS), GenieACS (TR-069), Gemini 2.5 Flash via targo-hub (vision/OCR — see docs/features/vision-ocr.md)

Data Volumes (migrated from legacy)

Entity	Volume
Customers	6,667 (active + terminated)
Subscriptions	21,876 (with RADIUS credentials)
Sales Invoices	115,000+
Payments	99,000+ (with invoice references)
Tickets (Issues)	242,000+ (parent/child hierarchy)
Ticket Messages	784,000+
Devices	7,600+ (ONT, router, TV box)
Service Locations	~17,000

Development

# Ops app
cd apps/ops && npm install && npx quasar dev

# Website
cd apps/website && npm install && npm run dev

# targo-hub
cd services/targo-hub && npm install && npm run dev

# Deploy ops to production
cd apps/ops && bash deploy.sh

Auth Pattern

Authentik SSO protects staff apps via Traefik forwardAuth. The ops app reads X-Authentik-Email from the proxied request header. All ERPNext API calls from targo-hub and the ops nginx proxy use Authorization: token <ERP_SERVICE_TOKEN> (Bearer token from server .env). Customer-facing SSO is at id.gigafibre.ca, federated from auth.targo.ca.

Documentation

Start at docs/README.md — it indexes every doc with a "I want to…" intent table. Quick map:

Area	Entry point
Plan & live module URLs	docs/roadmap.md
System architecture (services, Docker, SSO)	docs/architecture/overview.md
ERPNext data model + customer flows	docs/architecture/data-model.md
Frontend patterns (Vue/Quasar/Pinia)	docs/architecture/app-design.md
Billing, Stripe, invoices	docs/features/billing-payments.md
CPE / modems / ONTs / TR-069	docs/features/cpe-management.md
Scanner / OCR / Gemini pipeline	docs/features/vision-ocr.md
Agent flows (Flow Template)	docs/features/flow-editor.md
Wizard SKU vs legacy audit	docs/reference/erpnext-item-diff.md
Historical snapshots & migration logs	docs/archive/