gigafibre-fsm/docs/PLATFORM_GUIDE.md

TARGO / Gigafibre — OPS Platform Guide

What this is. A single reference to the logic behind every major feature of the OPS platform, the operating conditions we deliberately built into each one to fit how a Québec fibre ISP actually runs, and the gotchas that cost us real time. If you were rebuilding this from scratch, this is the document that would save you months.

Audience. Us (operators + future maintainers) and anyone evaluating "could we build our own ISP ops stack."

Last synthesized: 2026-06-13. Treat file:line references as directional — verify against current code.

---

0. TL;DR — the five things that explain everything

1. F is the source of truth for billing. ERPNext is an operational mirror. Almost every design decision flows from this. We never write billing to F; we sync F → ERPNext one-way; we never auto-act on a divergence that is just "the mirror hasn't caught up."
2. The legacy box (F) is fragile and must be treated like unexploded ordnance. One SSH at a time, read-only, query only indexed columns, never the account_id join. A bad query freezes live billing.
3. Two apps, one hub. A Quasar SPA (apps/ops, staff desktop) + a field-tech mobile view, both talking to a single hand-rolled Node service (services/targo-hub) that fans out to F, ERPNext, Gmail, Twilio, SNMP, n8n, Stripe, GenieACS, OR-Tools, etc. The hub is the integration brain.
4. Status is derived, never imported. A customer is never flipped "inactive" from F. Cancellation happens at the service level. Active/inactive truth = F account.status, read on demand — not a synced flag.
5. Everything real-time is SSE. No websockets for app state (only Twilio media). The hub publishes topics; the SPA subscribes. If a badge/panel is "dead," suspect the single mount point, not the data.

---

1. The core model: F → ERPNext one-way mirror

   ┌─────────────────────┐        one-way, preview-first        ┌──────────────────────┐
   │   F  (gestionclient)│  ───────────────────────────────▶    │   ERPNext v16 (PG)   │
   │  PHP + MariaDB      │   clients · adresses · services ·     │  operational mirror  │
   │  10.100.80.100      │   factures · paiements · tickets      │  + OPS-only doctypes │
   │  AUTHORITATIVE       │                                       │  scheduler PAUSED    │
   │  for billing         │   writes back ONLY via PHP bridge     │  mute_emails ON      │
   └─────────────────────┘   (X-Ops-Token), never direct SQL     └──────────────────────┘

• Why a mirror at all. F bills correctly but is a closed legacy PHP app with no API, no modern UX, no dispatch/CRM/automation surface. ERPNext gives us a queryable data model + a place to bolt on dispatch, inbox, campaigns, portals, AI — without touching the billing engine.
• Identifiers that glue the two worlds (memorize these):
  • Customer.legacy_account_id = F account.id
  • Service Subscription.legacy_service_id = F service.id — and the SUB doc name embeds it: SUB-0000056285 → F service 56285. (We almost lost this correlation; keep it.)
  • Service Location.legacy_delivery_id = F delivery.id
• F account.status is the authority for "is this client active": 1=Actif, 2=Suspendu, 3/4/5=Résilié. mapAccount derives disabled = [1,2].includes(status) ? 0 : 1.
• Sync direction & safety. lib/legacy-sync.js is preview/read-only by default; applying a change requires an explicit confirm string (SAFE-ADD); payment mirroring requires F-WINS. The heavy invoice/service creation runs in host cron /opt/targo-sync/run.sh (hourly), not in the hub. The hub's DAG (lib/sync-orchestrator.js) documents/validates order (clients→adresses→services; factures→paiements; tickets separate) and exposes /sync/status.

Operating condition (the big one): A divergence is not an action. "F inactive / ERPNext active" for ~2,500 rows is noise (the mirror lag + derived flags), not churn to execute. Reconciliation dashboards must split actionable (email/phone/name) from derived/non-actionable (disabled, is_suspended). See §3.7 and §4.

---

2. System topology

Layer	What	Where / how
Staff SPA	apps/ops — Vue 3 + Quasar, hash-router. Desktop ops console.	Built quasar build → scp dist/spa/* → 96.125.196.67:/opt/ops-app/. Behind Authentik SSO.
Field-tech view	apps/ops routes under /j (TechLayout) + a hub-served SPA /t/<token>.	Delivered to techs by SMS magic-link (JWT). PWA-ish, offline store + camera scan.
Integration hub	services/targo-hub — Node 20, hand-rolled http.createServer (no Express). ~70 lib/*.js modules, ~28k lines.	Container targo-hub, port 3300 not published (test via docker exec -i targo-hub node). Lib bind-mounted /opt/targo-hub/lib; deploy = scp lib + docker restart.
Billing truth	F = gestionclient PHP/MariaDB	10.100.80.100, reached via a local legacy-db mirror + the PHP write bridge ops_reassign.php.
Operational store	ERPNext v16 on PostgreSQL	erp.gigafibre.ca (96.125.196.67). REST via token auth + Host header. Scheduler paused, mute_emails on.
Address DB	Québec rqa_addresses (5.24M) + fiber_availability	Local Postgres (the ERPNext PG), shared pool owned by lib/address-db.js.
Realtime	SSE pub/sub (lib/sse.js)	SPA subscribes /sse?topics=.... Only Twilio Media Streams use WebSocket.

Auth tiers (enforced by one gate at the top of server.js):

1. Public allowlist (/health, /g/, /c/, /book, /field, /diag/, /webhook/*, checkout/portal/magic-link, /conversations/email-ingest|channel-ingest…).
2. Customer self-service — the token in the URL is the secret (signed JWT diag links, web-chat client routes, payment links).
3. Staff/admin — Authorization: Bearer HUB_SERVICE_TOKEN, injected server-side by the ops nginx /hub/ proxy (same-origin). Cross-origin apps with no token can only reach public routes.
   • HUB_GATE modes: enforce (401) | report (log-only) | off. ALWAYS_ENFORCE list (/devices, /email-queue, /campaigns, /giftbit) is locked regardless.
   • Per-handler extra secrets: X-Mail-Token (n8n ingest), HUB_INTERNAL_TOKEN (/broadcast), signed query token (iCal), X-Ops-Token (PHP write bridge).

Gotcha (auth): use a same-origin proxy that injects the Bearer token, NOT Traefik forward-auth alone — cross-origin + SSE breaks under forward-auth. Several routes were historically left open (/devices, /conversations, /olt, /admin/pollers); the gate + ALWAYS_ENFORCE closed the worst.

---

3. Feature catalog

Each entry: What · Logic · Operating conditions (the invariants we built to fit ops) · Gotchas.

3.1 Clients — the 360° file (/clients, /clients/:id)

• What. Searchable customer list + a single page that aggregates subscriptions, services, equipment, tickets, invoices, payments, notes, and live modem status for one customer.
• Logic. ClientDetailPage.vue (1,725 lines) orchestrates ~8 composables (useClientData, useSubscriptionActions, useEquipmentActions, usePaymentActions, useDeviceStatus, useSubscriptionGroups, …). Data is ERPNext doctypes (Customer, Service Location, Service Subscription, Subscription Plan, Item) joined by the legacy_* keys.
• Operating conditions.
  • Effective service price is not a column. F's service table has no price → price = hijack ? hijack_price : product.price (+ hijack_desc). status=1 = active; date_suspended when status=1 is just history — ignore it.
  • A customer is never set inactive. Out-of-zone movers stay visible (cross-sell candidates). disabled/is_suspended are derived from subscriptions, never synced from F.
  • Recurring monthly total can never be negative. The page shows a red guard if it is, and each subscription row carries an F#id / "added in OPS" badge so we can trace a bad rebate to its origin.
• Gotchas.
  • erp.list blocks some fields on ERPNext v16 ("Field not permitted in query"); lib/erp.js auto-retries by dropping them. The real per-service price field is monthly_price, not actual_price.
  • This page is the #4 largest file — a refactor candidate, but it's load-bearing; split by section, don't rewrite.

3.2 Communications — unified inbox (/communications)

• What. One place for all customer conversations (SMS + email + web-chat) and open tickets, organized two ways: a department board ("Par département") and a sales pipeline ("Pipeline ventes").
• Logic.
  • useConversations.js is a module-level singleton holding conversations, discussions, panelOpen, activeCount, queue/claim/assign, SSE wiring. Backend: lib/conversation.js (+ lib/ticket-collab.js for the ERPNext-Issue side).
  • Inbound mail/SMS/3CX/Facebook are ingested via /conversations/email-ingest & /channel-ingest (n8n, X-Mail-Token). Replies go out via Gmail (gmail.js) or Twilio.
  • DepartmentBoard.vue groups discussions by queue (= department) with drag-to-reassign (assignQueue), click-to-open, and per-column compose. PipelineBoard.vue is the leads kanban.
  • AI triage (inbox-triage.js): classifies inbound mail (known customer? type? suggest a ticket?).
  • Outbox / undo-send (outbox.js): multi-recipient queue notifications are held N seconds and cancellable from an ops panel; single-recipient agent replies bypass the buffer.
  • Category taxonomy is single-source (lib/categories.js): the 4 queues, the request TYPES, type→queue (QUEUE_OF) and type→ticket-category (CAT) live in ONE module, required by both conversation.js and inbox-triage.js. They had drifted (telephonie/television existed in the queue map but not the triage types). Contract: the AI prompt enumerates TYPES by hand — extend both.
  • Sender identity = the real From (display name), then a customer matched by email, then the raw address — never the AI's content-guessed name. And a thread is never grouped by one of our own domains (support@targo.ca, *@targointernet.com): re-ingested outbound would otherwise collapse unrelated threads into one. Per-agent reply stats come from stamping msg.agent on outbound replies.
• Operating conditions.
  • Departments = the four queues Facturations, Service à la clientèle, Supports, Technicien (+ "Non assigné"). The board reuses the existing queue labels — departments are queues.
  • Queue/notification lists must stay small. A queue notification once emailed the entire team and re-ingested our own notifications into the inbox (a feedback loop). Fix: empty queue_members + an ingestGuard that drops own-notifications / internal mail / ticket-replies.
  • AI auto-reply only answers customer-initiated threads — never our own "planned maintenance"/dunning notifications, never a bare "ok/merci" ack (isAck), and yields if a human replied today.
  • Sales pipeline coexists with the department board (2 tabs) — we did not replace it, because the Sales-sync project still needs the leads stages.
• Gotchas.
  • ConversationPanel.vue is the single mount point for the whole comms subsystem. Its onMounted runs the global init (fetchList+fetchTickets+SSE); the drawer (panelOpen), the badge (activeCount), and the "Nouveau texto/courriel" dialog all live inside it. If its setup() throws, everything comms dies (no badge, panel won't open, compose won't open) while the rest of the app keeps working. That exact symptom pattern = a ConversationPanel mount failure — not the cache.
  • The throw we actually hit: a top-level watch(coordToken, …) placed before const coordToken = computed() → TDZ ReferenceError. Rule: in <script setup>, any top-level watch()/eager call must come after the const it references. The Quasar build does not catch this (runtime error).
  • /email-queue (EmailQueuePage) is the ERPNext muted outbound queue (a technical inspector), not the Gmail conversation email. Don't confuse them.

3.3 Tickets & collaboration (/tickets, /collab/*)

• What. ERPNext Issue list + a "collab" layer: customer search (phone/civic/name fuzzy), service+modem status, live modem checks, create-ticket-from-conversation, comments/@mentions.
• Logic. ticket-collab.js exposes /collab/service-status (service + modem in one call), /collab/dostuff (live modem status by hitting F's own n8n webhook n8napi.targo.ca/webhook/dostuff), the negative-billing & terminated-active reports, WAN-rate, and /collab/diag-link.
• Operating conditions.
  • A ticket created from a conversation keeps the conversation (≠ archive).
  • "Do Stuff" live check is tech=3 only (tech=2 is our own poller); ~27 s latency.
• Gotchas. service-status keys ONUs by the same TPLG serial format as ERPNext (MAC fallback); rxPowerOnu is RAW (not dBm), rxPowerOlt is dBm×10. ERPNext TPLG serials ≠ GenieACS real serials.

3.4 Workforce — Dispatch + Planification + RDV + Copilot

This is the largest, most interconnected domain. The strategic move was convergence: Dispatch and Planification share a single write path and a single resource rail.

• Dispatch (/dispatch, DispatchPage.vue 2,162 lines): drag-and-drop tech scheduling on a Mapbox-backed board — routing, auto-distribute, Uber-style job offers (useJobOffers: broadcast/ accept/decline, rush pricing), GPS, undo. Backend lib/dispatch.js scores techs by proximity/cost/skills.
• Planification (/planification, 3,524 lines — the largest file): roster/shift grid driven by an OR-Tools solver (roster-solver:8090) via lib/roster.js, over ERPNext doctypes (Dispatch Technician, Shift Template/Requirement/Assignment, Tech Availability).
• RDV (/rdv): customer-appointment booking — roster-aware slots, 3 ranked offers + "fit", hold, confirm, reschedule-notify. Public booking served at /book.
• Copilot (/copilote): conversational ops assistant (Gemini function-calling) with write actions (reassign/SMS/escalate) + voice.
• Historique (/historique, HistoriquePage.vue): 3 tabs — Tournées par technicien (a day's jobs per tech, all statuses incl. Completed/Cancelled), Classement techniciens (jobs completed), and Classement Inbox (replies + threads handled per agent). It exists because the Dispatch board filters to open/assigned/in_progress, so once a job is completed/cancelled (or its ticket closed/reassigned) it vanished — "where did the tech go?". Read-only hub endpoints /dispatch/history, /dispatch/leaderboard, /conversations/leaderboard; agent reply stats rely on msg.agent stamping (accrue from 2026-06-14).
• Operating conditions.
  • One write path. Job→tech assignment goes through features/workforce/useAssignment (the "hub"), shared by both the Dispatch board and the Planification grid — so the two views can't drift.
  • One resource rail. features/workforce/useResources is the single techs+subgroups+search/score source.
  • Tags = skill levels; jobs carry a minimum required. Dispatch logic cost-optimizes: cheapest tech that still clears the job's minimum skill tags.
  • A tech on pause turns their dispatch tickets red (roster ↔ dispatch coupling).
  • Booking offers obey a policy (min lead time, hour window, max/day, buffer, blackouts).
• Gotchas.
  • In lib/roster.js, erp.list must be sequential, not Promise.all (ERPNext chokes), use http.request (not a global fetch), and watch Pydantic None on the solver side + anti-over-staffing.
  • The legacy osTicket → Dispatch Job bridge is opt-in (LEGACY_DISPATCH_SYNC=on), idempotent via legacy_ticket_id, and recreating the container ≠ restarting it for env to take effect.

3.5 Field-tech mobile app (/j/*, TechLayout; hub /t/<token>, /field)

• What. A phone-first app techs reach via SMS magic-link: today's jobs, job detail + status updates, camera serial scan, device lookup, modem/Wi-Fi diagnostics, offline queue.
• Logic. Routes under /j with a magic-link catch-all /j/:token. useScanner (camera → Gemini Vision OCR), useOfflineStore (Pinia, queue writes when offline), useModemDiagnostic/useWifiDiagnostic (signal thresholds → verdicts). The hub also serves a server-rendered SPA at /t/<token>.
• Operating conditions. Auth = the JWT in the link is the credential (no SSO on a tech's phone). Devices are linked to addresses, not customers — preserve manage-IP/credentials/parent hierarchy.
• Gotchas. This is the part most people get wrong on mobile elsewhere in the app — see §5: the tech view is mobile-designed; the staff console pages are not (that's the redesign work).

3.6 Network, devices, OLT, diagnostics (/network, /olt, /devices)

• What. Topology/dependency map, health, OLT signal stats, poller admin, AI log RCA.
• Logic.
  • devices.js caches GenieACS devices (poller sweeps ~6,000 ONTs / 5 min).
  • olt-snmp.js polls TP-Link (ent. 11863) and Raisecom (ent. 8886) GPON OLTs over SNMP every 5 min — ONU table walk, signal/power/serial. WAN throughput (Mbps) is live SNMP, not Elasticsearch.
  • network-intel.js feeds InfluxDB + Grafana logs to Gemini for root-cause analysis.
  • outage-monitor.js turns Uptime-Kuma webhooks into synthesized alerts.
• Operating conditions. WAN live-rate graph works on Raisecom OLTs (tech-2) only; tech-3 shows "indisponible". The OLT keys ONUs by the same TPLG format as ERPNext (direct match).
• Gotchas. SNMP Counter64 arrives as an 8-byte Buffer — read it with readBigUInt64BE, or you get ~0/null. WAN octet OIDs (Raisecom): rx=…2.4.1.5.{oltId}.40, tx=…3.{oltId}.40, oltId = slot*1e7 + port*1e5 + ontid, .40 = the internet VLAN.

3.7 Billing sync & financial reports (/sync-legacy, /rapports/*)

• What. The F→ERPNext sync dashboard + reports: revenue by account, detailed sales, TPS/TVQ taxes, AR aging, "Internet cher" (overpaying addresses + competition), negative recurring bills, and terminated accounts with active services.
• Logic. Reports hit ERPNext (lib/reports.js) or the legacy MariaDB (lib/legacy-reports.js). Payment reconciliation (lib/legacy-payments.js) mirrors Payment Entries into ERPNext idempotently (PE-{id}), guarded by confirm:'F-WINS', and computes a billing-coherence status.
• Operating conditions.
  • Recurring monthly bill is never negative. When it was, the root cause was a status-mapping bug (status=1 + date_suspended>0 wrongly mapped to "Suspended"), corrected to status=1 ⇒ Actif in both the Python cron and the JS. (177 subscriptions corrected.) Report: /rapports/factures-negatives.
  • Terminating a customer does NOT cascade to deactivate their services. Some terminated accounts keep legitimately-active services (employees with comped internet). Cancellation is per-service. The account "Résilié" status is informational (a cleanup-report column), never an automatic action. Report: /rapports/resilies-actifs (~2,724 terminated accounts / 3,966 active services).
  • Before ERPNext ever emits real billing, validate balance against F first. (Scheduler stays paused until cutover.)
• Gotchas.
  • Never join delivery.account_id in F — it's unindexed → full scan → freezes live billing. Query by delivery_id (indexed). Drive delivery_ids from ERPNext PG, then query F by those.
  • ERPNext v16 on Postgres has real bugs (GROUP BY/HAVING/boolean/double-quote/ORDER BY NULL) — patches are baked into the image; custom-field columns sometimes need an ALTER via the pool.

3.8 Address intelligence (/conformite-adresses, /serviceability)

• What. Address search/autocomplete, conformity/normalization review (incl. camping sites), and per-address competitor lookup.
• Logic. address-db.js owns the shared PG pool over rqa_addresses (5.24M) + fiber_availability, with a phased trigram query. serviceability.js hits Québec IHV ArcGIS open data (providers by address, incl. Cogeco) with a Referer: quebec.ca header — this replaced a reCAPTCHA-blocked checker.
• Operating conditions. Future targeting is by service availability at an address / a specific active service, at the service/address level — not the customer level.
• Gotchas. Trigram word_similarity with <% has a perf cliff — phase the query. The whole address DB is local now (no Supabase cloud).

3.9 Campaigns — gift cards (/campaigns/*)

• What. Email gift-card campaigns: 2 CSVs → match to ERPNext Customer → Mailjet blast of personalized FR/EN emails carrying a Giftbit shortlink → live SSE progress; reminder campaign for non-clickers; Unlayer template editor + AI FR↔EN translate.
• Logic. campaigns.js (2,389 lines): CSV parse/match, MJML compile, Mailjet send + Event webhook, the gift redirect wrapper /g/ (own expiry + reuse). giftbit.js is the gift-card API client.
• Operating conditions. Email routing is FR/EN by Customer.language. The gift /g/ wrapper gives us our own expiry/reuse control on top of Giftbit.
• Gotchas. A real incident: a /campaigns endpoint was public without auth → "card already used" / "$0.03 balance" (cards drained). Locked by token. Giftbit defaults to TESTBED (no real cards) until a separate prod token is wired. Map-CSV customer matching only resolves ~25% — still a production blocker.

3.10 Customer-facing (portal, checkout, contracts, diag, store)

• What. Passwordless customer portal, public checkout/catalog/order, contract acceptance, a self-service live diagnostic page, a hardware store (staging), self-signup (staging).
• Logic. portal-auth.js (email/phone → 24h JWT), checkout.js, contracts.js (residential JWT + commercial DocuSeal), client-diag.js (/diag/<jwt> shows what works, no internal data), payments.js (Stripe + webhook + daily PPA cron 06:00 EST).
• Operating conditions.
  • Legacy passwords are unsalted MD5 → force reset via email/SMS OTP, never trust them.
  • The /diag page must never leak internal data.
  • Contract acceptance is two-track: residential = JWT (promotion framing), commercial = DocuSeal.
  • CRTC 2026-43 (in force 2026-06-12): install is billable (exception), termination fees forbidden without a subsidized device; the residential "promotion spread/clawback" framing is now non-compliant.
• Gotchas. Invoice PDFs carry a QR code to the Stripe/portal payment link.

3.11 Telephony & voice agent (/telephony, /voice/*)

• What. 3CX telephony admin + a WebRTC softphone in the SPA (usePhone, SIP.js over WSS) + an AI voice agent over Twilio Media Streams ↔ Gemini Live.
• Logic. pbx.js polls the 3CX call log + handles call-event webhooks; voice-agent.js does mulaw↔PCM transcoding and bridges Twilio audio to Gemini Live.
• Gotchas. Voice agent is the only WebSocket consumer (/voice/ws). Inbound /voice/* is public.

3.12 Admin / RBAC / settings (/settings, /equipe, /agent-flows)

• What. Users, permission matrix, user groups, legacy-sync controls, AI agent flow/prompt editor.
• Logic. RBAC in lib/auth.js (capabilities like view_clients, assign_jobs, …) over Authentik; the SPA gates nav items and features by capability (usePermissions). Nav is data-driven from src/config/nav.js (each item has a requires).
• Operating conditions. SSO is Authentik (auth.targo.ca) — which is also why the staff app cannot be loaded headlessly for verification (see §4).

---

4. Cross-cutting gotchas — "if you build another software, know these"

These are the lessons that generalize beyond TARGO.

Legacy / data integrity

• Treat the authoritative legacy system as read-only and fragile. One connection at a time, only indexed queries, never the expensive join. A reporting query must never be able to freeze billing.
• Keep the foreign keys. Embedding legacy_service_id in the mirror's record name saved us; losing a correlation key is expensive to rebuild.
• A mirror lag is not a business event. Separate "the mirror disagrees" from "the customer changed." Auto-acting on the former manufactures fake churn.
• Derive status, don't sync it. disabled/is_suspended should be computed from services, never flipped from the source — and cancellation belongs at the service level, not the account level (employees with comped service prove the account-level cascade wrong).
• An invariant deserves a guard and a report. "Recurring bill ≥ 0" got both a fiche-level red warning and a /rapports/factures-negatives sweep. The report found the systemic mapping bug the guard couldn't.

ERPNext v16 on PostgreSQL specifically

• It ships SQL that assumes MySQL (GROUP BY/HAVING/boolean/double-quotes/ORDER BY NULL). Patch in-image and make patches idempotent. get_list silently rejects some fields → wrap with a field-drop-retry.
• Keep the scheduler paused and mute_emails on until you actually own billing.

Realtime / frontend architecture

• Find your single points of failure. One component (ConversationPanel) owning the init + the drawer + the badge + the compose dialog means one setup() throw blacks out an entire subsystem while the rest of the app looks fine. Either spread the init or know the symptom signature cold.
• TDZ in <script setup> — a top-level watch(x)/eager call before const x = … throws at runtime and the build won't catch it. Order matters; computeds/functions are lazy, watches are not.
• You can't verify an SSO-gated SPA headlessly. Plan for it: deterministic fixes + asking for the browser console error are faster than fighting the auth wall. Don't blame the cache before ruling out a mount throw.
• Cache after deploy. Hashed assets persist; serve index.html no-cache so redeploys take effect without a manual hard-refresh.

Integration plumbing

• SNMP Counter64 = 8-byte Buffer → readBigUInt64BE. Vendor enterprise OIDs differ (TP-Link vs Raisecom).
• Auth via same-origin token-injecting proxy, not forward-auth alone (cross-origin + SSE break).
• Sequential, not parallel for fragile upstreams (erp.list in the roster); Promise.all can DoS them.
• Opt-in schedulers + idempotency keys for anything that writes (the osTicket bridge); and remember recreate ≠ restart for env changes.
• Lock every public endpoint that can spend money (the Giftbit incident). Default-deny + an ALWAYS_ENFORCE list for the routes that should never see anonymous traffic.

Ops/SSH hygiene

• macOS has no timeout/sudo to the legacy box; use su -s /bin/bash www-data -c … and ssh -o BatchMode=yes -o ServerAliveInterval=…. Back up before editing (*.bak-YYYYMMDD).

---

5. Mobile & code health (pointer)

The current state, the clean mobile-first design system, the per-page responsive strategy, and the prioritized code-optimization backlog (helper consolidation, <StatusBadge>/<StatCard>, token unification --sb-*→--ops-*, mega-component splits) live in a companion doc:

→ docs/UI_AND_OPTIMIZATION.md

One-line summary: the shell is responsive (drawer breakpoint 1024 + mobile header), but no content page is (zero q-table grid mode, fixed-width dialogs/columns, $q.screen used in 2 files). The fix is a small set of responsive primitives applied page-by-page, plus finishing the stalled helper consolidation (useFormatters reaches 17 files, useStatusClasses only 4, while ~25 pages carry private copies).

---

6. Glossary

Term	Meaning
F	gestionclient — the legacy PHP/MariaDB billing system. Authoritative for billing.
hub	services/targo-hub — the Node integration service (port 3300).
OPS	the Quasar staff SPA (apps/ops, /opt/ops-app).
SUB-000…	Service Subscription doc; the trailing number = F service.id.
hijack	per-service price override in F (hijack_price, hijack_desc).
queue / file	inbox label = department (Facturations, Service à la clientèle, Supports, Technicien).
dostuff	F's n8n webhook for live modem status (tech=3).
RQA	the local Québec address database (rqa_addresses).
PPA	pre-authorized payment (daily Stripe cron).
TPLG serial	ERPNext-side ONU serial format; ≠ GenieACS real serial (MAC fallback).