# Gigafibre FSM — Architecture

## Overview

Field Service Management platform for Gigafibre ISP.
Inspired by Odoo OCA Field Service, Salesforce Field Service, and Zuper.

## Data Model

```
Customer (ERPNext native)
  └─ Service Location (LOC-#####)
       ├─ Address + GPS coordinates
       ├─ Connection type (FTTH/FTTB/Cable/DSL)
       ├─ OLT port, VLAN, network config
       ├─ Access notes (door code, dog, etc.)
       │
       ├─ Service Equipment (EQP-#####)
       │    ├─ Type: ONT / Modem / Router / TV Box / IP Phone
       │    ├─ Serial number + MAC address
       │    ├─ Status: inventory → active → defective → returned
       │    ├─ Network config (IP, firmware, credentials)
       │    ├─ Move history (Equipment Move Log)
       │    └─ Linked to Subscription
       │
       └─ Service Subscription (SUB-#####)
            ├─ Category: Internet / IPTV / VoIP / Bundle
            ├─ Plan: Fibre 50, Fibre 100, IPTV Essentiel...
            ├─ Speed up/down, monthly price, billing cycle
            ├─ Contract duration, promo end date
            └─ Status: pending → active → suspended → cancelled

Dispatch Job (existing, extended)
  ├─ Customer + Service Location links
  ├─ Job type: Installation / Repair / Maintenance / Removal
  ├─ Source: Helpdesk Issue or direct creation
  ├─ Assigned tech + assistants
  ├─ Schedule: date, time, duration, route order
  ├─ Equipment Items (installed/removed/replaced)
  ├─ Materials Used (from inventory)
  ├─ Checklist (configurable per job type)
  ├─ Time tracking (actual start/end, travel time)
  ├─ Photos + Customer signature
  └─ GPS position (via Traccar WebSocket)
```

## Tech Stack

| Component | Technology | Location |
|-----------|-----------|----------|
| ERP Backend | ERPNext v16 (Frappe) | erp.gigafibre.ca |
| Dispatch PWA | Vue 3 / Quasar / Pinia | dispatch.gigafibre.ca |
| GPS Tracking | Traccar (WebSocket + REST) | tracker.targointernet.com |
| Maps & Routes | Mapbox GL JS + Directions API | Client-side |
| Auth / SSO | Authentik (forwardAuth) | auth.targo.ca |
| Reverse Proxy | Traefik v2.11 | Port 80/443 |
| Workflows | n8n | n8n.gigafibre.ca |
| Admin Hub | Custom Node.js | hub.gigafibre.ca |

## Authentication Flow

```
User → dispatch.gigafibre.ca
  → Traefik (authentik@file middleware)
  → Authentik forwardAuth check
  → Valid session? → App loads
  → No session? → Redirect auth.targo.ca → Login → Callback → App

API calls: /api/* → ERPNext (service token, no CORS)
GPS data: /traccar/* → Traccar proxy (Basic auth)
```

## ERPNext Doctypes (module: Dispatch)

### Core
| Doctype | Autoname | Purpose |
|---------|----------|---------|
| Dispatch Technician | field:technician_id | Tech profile + GPS link |
| Dispatch Job | field:ticket_id | Work orders |
| Dispatch Tag | field:name | Job categorization |

### FSM Extension
| Doctype | Autoname | Purpose |
|---------|----------|---------|
| Service Location | LOC-.##### | Customer premises |
| Service Equipment | EQP-.##### | Deployed hardware |
| Service Subscription | SUB-.##### | Active service plans |
| Checklist Template | field:template_name | Reusable checklists |

### Child Tables
| Doctype | Parent |
|---------|--------|
| Equipment Move Log | Service Equipment |
| Job Equipment Item | Dispatch Job |
| Job Material Used | Dispatch Job |
| Job Checklist Item | Dispatch Job |
| Job Photo | Dispatch Job |
| Checklist Template Item | Checklist Template |
| Dispatch Job Assistant | Dispatch Job |
| Dispatch Tag Link | Dispatch Job / Technician |

## Workflows

### Helpdesk → Dispatch
1. Issue created (ERPNext HD) with type "Field Service"
2. Server script creates Dispatch Job, links back to Issue
3. Dispatcher assigns tech via PWA timeline
4. Tech completes job → Issue auto-resolved

### Equipment Lifecycle
1. Equipment purchased → status "En inventaire"
2. Installation job → status "Actif", linked to location + subscription
3. Repair/replacement → move log entry, status update
4. Return → status "Retourné", unlinked from location

### Subscription Lifecycle
1. Customer signs up → Subscription "En attente"
2. Installation job completed → Subscription "Actif"
3. Non-payment → Subscription "Suspendu"
4. Cancellation → removal job → equipment returned → Subscription "Annulé"

## Comparison with Industry Tools

| Feature | Gigafibre FSM | Odoo FS | Zuper | Salesforce FS |
|---------|---------------|---------|-------|---------------|
| Drag-drop dispatch | Yes (custom PWA) | Yes | Yes | Yes |
| GPS real-time | Yes (Traccar WS) | Limited | Yes | Yes |
| Route optimization | Yes (Mapbox) | Basic | Yes | Advanced |
| Equipment tracking | Yes (serial+MAC) | Yes | Yes | Yes |
| Barcode scanning | Planned | Yes | Yes | Yes |
| Offline mobile | Planned (PWA) | Limited | Yes | Yes |
| Subscriptions | Yes (custom) | Yes (native) | Yes | Yes |
| Helpdesk integration | Yes (ERPNext Issue) | Yes | Yes (Zendesk) | Yes (native) |
| Self-hosted | Yes | Yes | No | No |
| Cost | Free (OSS) | Free (CE) | ~$50/user/mo | ~$200/user/mo |
