gigafibre-fsm/docs/architecture/data-model.md

Gigafibre FSM — Data Structures & Customer Flows

A unified document defining the ERPNext data structure and the "Lead to Live" customer flow architecture.

1. ERPNext Data Schema

All operational data revolves around the Customer, connected closely to their physical service location and the equipment provided.

┌───────────────────────────────────────────────────────────┐
│                        Customer                           │
│  customer_group (Résidentiel/Comm.), legacy_customer_id   │
└──────────┬─────────────────────────┬──────────────────────┘
           │                         │
           ▼                         ▼
┌─────────────────────┐   ┌─────────────────────────┐
│  Service Location   │   │    Sales Invoice         │
│  (delivery address) │   │    Payment Entry         │
│  connection/olt_port│   └─────────────────────────┘
└──────┬──────────────┘
       │
       ├──────────────────────────────────┐
       ▼                                  ▼
┌──────────────────┐            ┌──────────────────────┐
│ Service          │            │ Service Equipment    │
│ Subscription     │            │  (ONT/Routeur/TV)    │
│  (Internet/TV)   │            │  mac/serial/wifi/sip │
└──────────────────┘            └──────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────────────┐
│                Dispatch Job                      │
│  (Tech installs equipment at Service Location)   │
│  Status: Scheduled → In Progress → Completed     │
└──────────────────────────────────────────────────┘

---

2. The Customer Journey (Lead to Live)

This flow replaces the legacy PHP quote builder. It operates atomically to ensure equipment and ports are correctly reserved.

Step 1: Address Qualification

• Website hits /api/address.
• Queries the fiber_availability table (coupled with pg_trgm fuzzy matching against RQA databases).
• Identifies the specific fibre_id and checks port availability in real time.

Step 2: Plan & Price Selection

• Prices dynamically populate based on the zone_tarifaire tied to the OLT Port.

Step 3: Payment Intent (Stripe)

• Stripe Elements capture CC info for a SetupIntent.
• We do not charge the card until the Dispatch Job is confirmed by the technician.

Step 4: Atomic Order Creation

Through targo-hub or n8n, a successful sign-up generates exactly:

1. Customer (Jane Doe)
2. Service Location (Address, linked to OLT Port)
3. Service Subscription (Internet Plan, TV Package)
4. Service Equipment (Empty templates waiting for tech to scan serials)
5. Dispatch Job (Triggered for Installation, waiting for tech assignment)

Step 5: Hardware Auto-Provisioning

1. When the order is generated, custom fields on Service Equipment (like custom_wifi_ssid and custom_sip_username) are prefilled in ERPNext.
2. The technician arrives, installs the TP-Link ONT, and scans its serial/MAC.
3. The ONT boots up and hits the TR-369 server (Oktopus).
4. targo-hub acts as the TR-069 proxy, matching the MAC to ERPNext, reading the custom provisioning profile, and automatically injecting the WiFi and SIP credentials onto the modem.

---

3. Ops App "Client 360" View

The ClientDetailPage in the Ops App acts as a unified console pulling from these relationships.

It displays:

• Standard Frappe Customer metadata + Custom Flags (PPA Enabled).
• A map and grid of the Service Location.
• Live diagnostic queries to targo-hub providing real-time data on the linked Service Equipment.
• The historical thread of Issue and Dispatch Job events.
• Inline Odoo-style editing for rapid support.