From ec385c99d01b174c9b88078d0672ff70e9e404ba Mon Sep 17 00:00:00 2001
From: louispaulb <louis.targo@gmail.com>
Date: Tue, 24 Mar 2026 14:10:06 -0400
Subject: [PATCH] =?UTF-8?q?Add=20ARCHITECTURE.md=20=E2=80=94=20full=20proj?=
 =?UTF-8?q?ect=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers: stack, directory structure, routes, ERPNext doctypes,
PostgreSQL extensions, features, component communication,
planned modules, and deploy instructions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ARCHITECTURE.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 ARCHITECTURE.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..bb19f6d
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,161 @@
+# OSS/BSS Field Dispatch — Architecture
+
+## Overview
+
+Field service dispatch & scheduling PWA integrated with ERPNext (Frappe) on PostgreSQL.
+Manages technicians, work orders, route optimization, and team scheduling.
+
+## Stack
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| **Frontend** | Vue 3 + Quasar (PWA) | `<script setup>`, Composition API, custom dark UI |
+| **State** | Pinia | Single `dispatch` store |
+| **Backend** | ERPNext / Frappe | REST API, Server Scripts, Doctypes |
+| **Database** | PostgreSQL | Native (no MariaDB), `pg_trgm` + `unaccent` for address search |
+| **Maps** | Mapbox GL JS | Route directions, optimization API, dark style |
+| **Deploy** | Docker | Frappe containers, PWA served as static assets |
+| **Git** | Gitea | `git.targo.ca/louis/OSS-BSS-Field-Dispatch` |
+
+## Directory Structure
+
+```
+src/
+├── api/                              # ERPNext REST calls
+│   ├── dispatch.js                   # Jobs, techs, tags CRUD + createTag
+│   ├── auth.js                       # Login, CSRF token
+│   ├── service-request.js            # Open service requests
+│   ├── booking.js                    # Booking API
+│   ├── contractor.js                 # Contractor API
+│   └── settings.js                   # Dispatch Settings (single doctype)
+│
+├── components/                       # Reusable UI widgets
+│   └── TagInput.vue                  # Auto-suggest tag input with inline creation
+│
+├── composables/                      # Shared logic (no UI)
+│   ├── useHelpers.js                 # Pure utils: dates, formatting, icons, colors
+│   ├── useScheduler.js               # Timeline algorithm: pinned anchors + auto-flow
+│   ├── useMap.js                     # Mapbox: init, markers, routes, geo-fix, drag
+│   ├── useBottomPanel.js             # Unassigned list: grouping, multi-select, criteria
+│   └── useUndo.js                    # Undo stack (30 actions max)
+│
+├── modules/
+│   └── dispatch/
+│       └── components/               # Dispatch-specific components
+│           ├── TimelineRow.vue       # Single tech row with job blocks
+│           ├── BottomPanel.vue       # Unassigned jobs table (date-grouped)
+│           ├── JobEditModal.vue      # Edit job modal (double-click)
+│           └── WoCreateModal.vue     # Create work order modal
+│
+├── pages/                            # Route-level pages
+│   ├── DispatchV2Page.vue            # Main dispatch board (active)
+│   ├── DispatchPage.vue              # Legacy v1 (deprecated)
+│   ├── MobilePage.vue                # Mobile tech view
+│   ├── AdminPage.vue                 # Admin settings
+│   ├── BookingPage.vue               # Customer booking
+│   ├── TechBidPage.vue              # Tech bidding
+│   └── ContractorPage.vue           # Contractor view
+│
+├── stores/
+│   ├── dispatch.js                   # Jobs, technicians, tags state
+│   └── auth.js                       # Auth state
+│
+├── config/
+│   └── erpnext.js                    # MAPBOX_TOKEN, TECH_COLORS, BASE_URL
+│
+└── router/index.js                   # Vue Router (hash mode)
+```
+
+## Routes
+
+| Path | Page | Description |
+|------|------|-------------|
+| `/#/dispatch2` | DispatchV2Page | **Main app** — scheduling board |
+| `/#/` | DispatchPage | Legacy v1 |
+| `/#/mobile` | MobilePage | Mobile tech interface |
+| `/#/admin` | AdminPage | Settings |
+| `/#/booking` | BookingPage | Customer booking |
+| `/#/bid` | TechBidPage | Tech bidding |
+| `/#/contractor` | ContractorPage | Contractor portal |
+
+## ERPNext Doctypes
+
+| Doctype | Type | Fields |
+|---------|------|--------|
+| **Dispatch Job** | Document | subject, address, lat/lng, priority, duration_h, status, assigned_tech, scheduled_date, start_time, end_date, note |
+| **Dispatch Technician** | Document | technician_id, full_name, status, user, lat/lng |
+| **Dispatch Tag** | Document | label, color, category (Skill/Service/Region/Equipment/Custom) |
+| **Dispatch Job Assistant** | Child Table (of Job) | tech_id, tech_name, duration_h, note, pinned |
+| **Dispatch Tag Link** | Child Table | tag (Link → Dispatch Tag) |
+| **Dispatch Settings** | Single | API keys, Mapbox token |
+
+## PostgreSQL Extensions
+
+| Extension | Usage |
+|-----------|-------|
+| `pg_trgm` | Trigram fuzzy search on `rqa_addresses.search_text` |
+| `unaccent` | Accent-insensitive search (riviere = rivière) |
+
+**Address table:** `rqa_addresses` — 5.2M Quebec civic addresses with pre-computed `search_text` column, GIN trigram index.
+
+## Key Features
+
+### Scheduling
+- **Day view**: Timeline with pinned time anchors + auto-flow for unpinned jobs
+- **Week view**: Calendar grid with job chips, lasso multi-select
+- **Month view**: Overview with tech avatars per day
+- **Travel time**: Mapbox Directions API, displayed between job blocks
+
+### Dispatch
+- **Auto-distribute**: Ordered criteria (urgency → load balance → proximity → skills)
+- **Multi-drag**: Select multiple jobs in bottom panel, drag to tech or batch-assign
+- **Route optimization**: Nearest-neighbor + Mapbox Optimization API (TSP)
+
+### Job Management
+- **Assistants**: Multi-tech jobs with floating/pinned modes
+- **Tags/Skills**: Auto-suggest input with inline tag creation
+- **Address autocomplete**: Server Script → PostgreSQL with pg_trgm
+- **Undo**: Ctrl+Z for assign/unassign/optimize/distribute (30-deep stack)
+
+### UI
+- **Sidebar**: Icon strip with flyout panels on hover
+- **Single click**: Right panel with job details
+- **Double click**: Edit modal (title, address, note, duration, priority, tags)
+- **Context menu**: Right-click on jobs and techs
+- **Lasso**: Rectangle selection in day and week views
+- **Map**: Mapbox dark style, route visualization, geo-fix by click
+
+## Component Communication
+
+```
+DispatchV2Page (orchestrator)
+  │
+  ├── provide/inject ──→ shared state (store, colors, functions)
+  │
+  ├── TimelineRow ←──── events (job-click, drag, resize, ctx)
+  ├── BottomPanel ←──── events (select, batch-assign, drag)
+  ├── JobEditModal ←─── v-model + confirm event
+  ├── WoCreateModal ←── v-model + confirm event
+  └── TagInput ←──────── v-model + create event
+```
+
+## Planned Modules
+
+| Module | Directory | Status |
+|--------|-----------|--------|
+| Dispatch | `modules/dispatch/` | Active |
+| Timesheet | `modules/timesheet/` | Planned |
+| HRMS | `modules/hrms/` | Planned |
+| ERP | `modules/erp/` | Planned |
+| OSS/BSS | `modules/oss-bss/` | Planned |
+
+## Deploy
+
+```bash
+# Build + deploy to ERPNext Docker
+./deploy.sh
+
+# Dev server (hot reload, proxies API to ERPNext)
+npx @quasar/cli dev -m pwa
+# → http://localhost:9000/#/dispatch2
+```