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.
156 lines
7.7 KiB
Markdown
156 lines
7.7 KiB
Markdown
# 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 DocuSeal
|
|
erp. erp. auth. n8n. www. docs.
|
|
gigafibre gigafibre targo.ca giga giga gigafibre
|
|
.ca .ca/ops/ id.giga fibre fibre .ca
|
|
fibre.ca .ca .ca
|
|
|
|
|
targo-hub (API gateway, msg.gigafibre.ca)
|
|
|
|
|
+----------+----------+----------+----------+
|
|
| | | | |
|
|
GenieACS Twilio Mailjet Stripe Traccar
|
|
(TR-069) (SMS) (email) ($) (GPS)
|
|
|
|
|
modem-bridge (SNMP / TR-069 deep-dive for TP-Link)
|
|
```
|
|
|
|
## Services & Dependencies
|
|
|
|
| Service | URL | Stack | Purpose |
|
|
|---------|-----|-------|---------|
|
|
| ERPNext | erp.gigafibre.ca | Frappe v16, PostgreSQL | ERP / billing / ticketing — Source of Truth |
|
|
| Ops SPA | erp.gigafibre.ca/ops/ | Vue 3, Quasar v2, Pinia | Internal operations app (dispatch, clients, settings) |
|
|
| targo-hub | msg.gigafibre.ca | Node.js 20, Express | API gateway: SMS, SSE, AI, OAuth admin, Stripe webhooks, Traccar proxy |
|
|
| modem-bridge | internal | Node.js, Playwright | TR-181 deep-dive for TP-Link XX230v / Deco mesh |
|
|
| Authentik (staff) | auth.targo.ca | Python, PostgreSQL | SSO for ops + n8n + Gitea + ERPNext OAuth provider |
|
|
| Authentik (clients) | id.gigafibre.ca | Python, PostgreSQL | SSO for customer-facing portals |
|
|
| n8n | n8n.gigafibre.ca | Node.js | Workflow automation (campaigns, SMS, email) |
|
|
| Traefik | — | Go | Reverse proxy, TLS, forwardAuth middleware |
|
|
| Website | www.gigafibre.ca | React, Vite, Tailwind | Marketing site + address API |
|
|
| DocuSeal | docs.gigafibre.ca | Ruby on Rails | Contract e-signature |
|
|
| GenieACS | (external) | Node.js, MongoDB | TR-069 ACS for ONT/router fleet |
|
|
| Traccar | (external) | 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](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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
Two parallel Authentik instances — **not** a migration in progress:
|
|
- **`auth.targo.ca`** — staff-facing. Protects `/ops/`, n8n, Gitea, the hub admin endpoints. Also acts as the OAuth provider for ERPNext sign-in. Lives on the prod box at `/opt/authentik` (managed by Targo's IT team).
|
|
- **`id.gigafibre.ca`** — customer-facing. Protects the client portal. Lives at `/opt/authentik-client` on the prod box.
|
|
|
|
Staff apps go through Traefik `forwardAuth` → Authentik outpost → cookie. The ops SPA reads `X-Authentik-Email` from the proxied header to identify the user, then maps Authentik groups to the in-app capability set (`useUserGroups.js`). All ERPNext API calls from targo-hub use `Authorization: token <ERP_SERVICE_TOKEN>` (Bearer from `.env`).
|
|
|
|
New users are added via **ops Settings → Utilisateurs → "Inviter"** which hits `POST /auth/users` on the hub. The hub creates the Authentik user, sets a temporary password, emails it via Mailjet, and creates the matching ERPNext System User in one round-trip. See [docs/SETUP.md](docs/SETUP.md) §6.
|
|
|
|
## Documentation
|
|
|
|
Start at **[docs/README.md](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](docs/roadmap.md) |
|
|
| System architecture (services, Docker, SSO) | [docs/architecture/overview.md](docs/architecture/overview.md) |
|
|
| ERPNext data model + customer flows | [docs/architecture/data-model.md](docs/architecture/data-model.md) |
|
|
| Frontend patterns (Vue/Quasar/Pinia) | [docs/architecture/app-design.md](docs/architecture/app-design.md) |
|
|
| Billing, Stripe, invoices | [docs/features/billing-payments.md](docs/features/billing-payments.md) |
|
|
| CPE / modems / ONTs / TR-069 | [docs/features/cpe-management.md](docs/features/cpe-management.md) |
|
|
| Scanner / OCR / Gemini pipeline | [docs/features/vision-ocr.md](docs/features/vision-ocr.md) |
|
|
| Agent flows (Flow Template) | [docs/features/flow-editor.md](docs/features/flow-editor.md) |
|
|
| Wizard SKU vs legacy audit | [docs/reference/erpnext-item-diff.md](docs/reference/erpnext-item-diff.md) |
|
|
| Historical snapshots & migration logs | [docs/archive/](docs/archive/) |
|