41d9b5f316
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>
139 lines
6.0 KiB
Markdown
139 lines
6.0 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 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), Ollama (OCR)
|
|
|
|
## 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
|
|
|
|
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
|
|
|
|
| Document | Content |
|
|
|----------|---------|
|
|
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Ecosystem overview, remote Docker infrastructure, platform strategy |
|
|
| [DATA_AND_FLOWS.md](docs/DATA_AND_FLOWS.md) | ERPNext data models, atomic order creation, customer flows |
|
|
| [CPE_MANAGEMENT.md](docs/CPE_MANAGEMENT.md) | Hardware management, XX230v diagnostics, TR-069/TR-369 |
|
|
| [APP_DESIGN_GUIDELINES.md](docs/APP_DESIGN_GUIDELINES.md) | Frontend framework architecture rules, UI/UX Wizard guidelines |
|
|
| [ROADMAP.md](docs/ROADMAP.md) | Implementation phases and current remote transition tasks |
|
|
| [archive/](docs/archive/) | Completed legacy migration analyses and accounting audits |
|