gigafibre-fsm/README.md

Gigafibre FSM

Complete operations platform for Gigafibre (consumer brand of TARGO Internet), a fiber ISP in Quebec. Replaces a legacy PHP/MariaDB billing system with ERPNext v16 + custom Vue.js (Quasar) apps.

What This Repo Contains

Directory	Description
apps/ops/	Targo Ops — main operations PWA (Vue 3 / Quasar v2)
apps/field/	Targo Field — mobile app for technicians (barcode, diagnostics, offline)
apps/client/	Gigafibre Portal — customer self-service portal
apps/website/	www.gigafibre.ca — marketing site (React / Vite / Tailwind)
apps/dispatch/	Legacy dispatch app (replaced by apps/ops/ dispatch module)
apps/portal/	Customer portal deploy configs
erpnext/	ERPNext custom doctype setup scripts
scripts/migration/	51 Python scripts for legacy-to-ERPNext data migration
scripts/	Utility scripts (bulk submit, PostgreSQL fixes)
docs/	Architecture, infrastructure, migration plan, changelog

Architecture

96.125.196.67 (Proxmox VM, Ubuntu 24.04)
  |
  Traefik v2.11 (TLS via Let's Encrypt)
  |
  +-- erp.gigafibre.ca           ERPNext v16.10.1 (PostgreSQL, 9 containers)
  +-- erp.gigafibre.ca/ops/      Ops PWA (Quasar/Vue3, Authentik SSO)
  +-- id.gigafibre.ca            Authentik SSO (customer-facing)
  +-- auth.targo.ca              Authentik SSO (staff, federated to id.gigafibre.ca)
  +-- n8n.gigafibre.ca           n8n workflow automation
  +-- git.targo.ca               Gitea
  +-- www.gigafibre.ca           Marketing site + address API
  +-- oss.gigafibre.ca           Oktopus CE (TR-069 CPE management)
  +-- tracker.targointernet.com  Traccar GPS tracking

Features

Ops App (apps/ops/)

• Client Management — customer list with search by name, account ID, legacy ID. Inline editing (double-click any field to edit, saves to ERPNext in background)
• Client Detail — full customer view with contact, billing KPIs, service locations, subscriptions, equipment, tickets, invoices, payments, notes
• Inline Editing — Odoo-style double-click-to-edit on all fields (locations, equipment, tickets, invoices). Uses InlineField component + useInlineEdit composable
• Dispatch Timeline — drag-drop job scheduling with Mapbox map, GPS tracking (Traccar), technician management, tag/skill system
• Ticket Management — list with inline status/priority editing, detail modal with reply thread
• Equipment Tracking — serial/MAC, status lifecycle, OLT info, per-location grouping
• SMS/Email Notifications — send from contact card via n8n webhooks (Twilio SMS, Mailjet email)
• Invoice OCR — scan paper bills using Ollama Vision (llama3.2-vision)
• PWA — installable, offline-capable with Workbox

Legacy Migration (completed)

Migrated from a 15-year-old PHP/MariaDB billing system:

Data	Volume	Status
Customers	6,667 (active + terminated)	Migrated
Contacts + Addresses	~6,600 each	Migrated
Service Locations	~17,000	Migrated
Subscriptions	21,876 (with RADIUS credentials)	Migrated
Items (products/plans)	833	Migrated
Sales Invoices	115,000+	Migrated
Payments	99,000+	Migrated with invoice references
Tickets (Issues)	242,000+ (parent/child hierarchy)	Migrated
Ticket Messages (Communications)	784,000+	Migrated
Customer Memos (Comments)	29,000+	Migrated with real dates
Employees	45 ERPNext Users from legacy staff	Migrated

Bugs Fixed From Legacy System

• Date corruption — Unix timestamps stored as strings; fixed during import with timezone-aware conversion
• Invoice outstanding amounts — payment_item references broken in legacy; reconciled during migration
• Customer links — orphan records (invoices/payments without valid customer); rebuilt relationships
• Subscription details — missing service_location links, incorrect billing frequencies; corrected via analysis scripts
• Reversal transactions — credit notes improperly recorded; mapped to ERPNext return invoices
• Annual billing dates — yearly subscriptions had wrong period boundaries; recalculated
• Duplicate customer IDs — legacy allowed duplicate customer_id; resolved with rename script
• Staff/ticket ownership — legacy used numeric IDs for assignment; mapped to ERPNext User emails

ERPNext Adjustments for Import

• Direct PostgreSQL inserts — Frappe ORM too slow for 100K+ records; used psycopg2 with proper tabXxx schema
• Scheduler paused — disabled auto-invoicing during import to prevent 21K subscriptions from generating invoices
• Custom fields on Customer — legacy_account_id, legacy_customer_id, ppa_enabled, stripe_id, date fields
• Custom fields on Item — legacy_product_id, download/upload speeds, quotas, OLT profiles
• Custom fields on Subscription — radius_user, radius_pwd, legacy_service_id
• Custom fields on Issue — legacy_ticket_id, assigned_staff, opened_by_staff, issue_type, is_important, service_location
• PostgreSQL GROUP BY patch — ERPNext v16 generates MySQL-style queries; patched number_card.py and PLE reports
• Subscription API unlock — removed read_only and set_only_once restrictions on Subscription fields for REST API updates
• Portal auth bridge — server script for legacy MD5 password migration to PBKDF2

ERPNext Custom Doctypes

Field Service Management

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 cycle, RADIUS)

Dispatch

Doctype	Purpose
Dispatch Job	Work orders with equipment, materials, checklist, photos, signature
Dispatch Technician	Tech profiles with GPS link (Traccar), skills, color coding
Dispatch Tag	Categorization with skill levels (Fibre, TV, Telephonie, etc.)
Dispatch Tag Link	Child table linking tags to jobs/techs with level + required flag

Child Tables

Equipment Move Log, Job Equipment Item, Job Material Used, Job Checklist Item, Job Photo, Dispatch Job Assistant, Checklist Template + Items

Quick Start

Development

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

# Website
cd apps/website
npm install
npm run dev

Deploy Ops to Production

cd apps/ops
bash deploy.sh          # builds PWA + deploys to server via SSH

Run Migration Scripts

# Scripts run inside the ERPNext backend container
docker cp scripts/migration/migrate_all.py frappe_docker-backend-1:/tmp/
docker exec frappe_docker-backend-1 bench --site erp.gigafibre.ca execute /tmp/migrate_all.main

Setup FSM Doctypes

docker cp erpnext/setup_fsm_doctypes.py frappe_docker-backend-1:/home/frappe/frappe-bench/apps/frappe/frappe/
docker exec frappe_docker-backend-1 bench --site erp.gigafibre.ca execute frappe.setup_fsm_doctypes.create_all

Documentation

Document	Content
ARCHITECTURE.md	Data model, tech stack, authentication flow, doctype reference
INFRASTRUCTURE.md	Server, DNS, Traefik, Authentik, Docker, n8n, gotchas
MIGRATION-PLAN.md	Legacy system portrait, mapping, phases, risks
CHANGELOG.md	Detailed migration log with volumes and methods
ROADMAP.md	5-phase implementation plan
MIGRATION_MAP.md	Field-level mapping legacy tables to ERPNext
COMPETITIVE-ANALYSIS.md	Comparison with Gaiia, Odoo, Zuper, Salesforce, ServiceTitan

Infrastructure

Service	URL	Technology
ERP	erp.gigafibre.ca	ERPNext v16.10.1 (Frappe, PostgreSQL)
Ops	erp.gigafibre.ca/ops/	Quasar v2 PWA
SSO (staff)	auth.targo.ca	Authentik
SSO (customers)	id.gigafibre.ca	Authentik (federated from auth.targo.ca)
Workflows	n8n.gigafibre.ca	n8n
Git	git.targo.ca	Gitea
GPS	tracker.targointernet.com	Traccar
Website	www.gigafibre.ca	React / Vite / Tailwind
CPE Mgmt	oss.gigafibre.ca	Oktopus CE (TR-069)
DNS	Cloudflare	gigafibre.ca (DNS-only, Traefik handles TLS)
Email	Mailjet	noreply@targo.ca
SMS	Twilio	+1 438 231-3838

Tech Stack

Layer	Technology
Backend	ERPNext v16 / Frappe (Python) on PostgreSQL
Frontend (ops)	Vue 3, Quasar v2, Pinia, Vite
Frontend (website)	React, Vite, Tailwind, shadcn/ui
Maps	Mapbox GL JS + Directions API
GPS	Traccar (REST + WebSocket)
Auth	Authentik SSO (forwardAuth via Traefik)
Proxy	Traefik v2.11 (Let's Encrypt)
Automation	n8n webhooks
SMS	Twilio (via n8n)
Email	Mailjet (via n8n)
OCR	Ollama (llama3.2-vision)
Hosting	Proxmox VM, Ubuntu 24.04, Docker