e50ea88c08
- Invoice OCR migrated from Ollama (GPU-bound, local) to Gemini 2.5 Flash via new targo-hub /vision/invoice endpoint with responseSchema enforcement. Ops VM no longer needs a GPU. - Ops /j/* now has full camera scanner (TechScanPage) ported from apps/field with 8s timeout + offline queue + auto-link to Dispatch Job context on serial/barcode/MAC 3-tier lookup. - New TechDevicePage reached via /j/device/:serial showing every ERPNext entity related to a scanned device: Service Equipment, Customer, Service Location, active Subscription, open Issues, upcoming Dispatch Jobs, OLT info. - New docs/VISION_AND_OCR.md (full pipeline + §10 relationship graph + §8.1 secrets/rotation policy). Cross-linked from ARCHITECTURE, ROADMAP, HANDOFF, README. - Nginx /ollama/ proxy blocks removed from both ops + field. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
139 lines
6.1 KiB
Markdown
139 lines
6.1 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), Gemini 2.5 Flash via targo-hub (vision/OCR — see [docs/VISION_AND_OCR.md](docs/VISION_AND_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
|
|
|
|
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 |
|