# 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](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

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](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/) |
