gigafibre-fsm/docs/architecture/app-design.md

Gigafibre FSM — App Design & UX Guidelines

This document defines the engineering patterns and UI/UX standards for developing frontend applications within the Gigafibre ecosystem (Ops App, Mobile Tech App, Client Portal).

Adhering to these guidelines ensures scalability, maintainability, and highly efficient AI-assisted development by keeping architectural context constrained.

---

1. Modular Architecture (Feature-Sliced Design)

To avoid a monolithic src/ folder that overwhelms developers and LLMs, organize code by feature rather than strictly by technical type.

Do Not Do This (Technical Grouping):

src/
  components/ (contains dispatch, inventory, and customer mixed together)
  store/ (one massive pinia store for everything)
  api/ (one 2000-line api.js file)

Do This (Feature Grouping):

src/
  features/
    dispatch/
      components/
      store.ts
      api.ts
      types.ts
    equipment/
      components/

Why? When executing a task inside a specific domain, only the pertinent features/{feature}/ directory needs to be referenced, drastically reducing cross-pollution and token usage.

---

2. Component & API Standardization (Vue / Quasar)

Architecture

• Composition API: Use Vue 3 <script setup> syntax universally. Avoid Options API.
• Component Size Limit: Keep .vue files small. If a component exceeds 250 lines, it must be split down.
• Smart vs Dumb:
  • Smart Components (Pages): Connect to Pinia, fetch data from API, hold domain state.
  • Dumb Components (UI): Accept props, emit events. Do not independently fetch data.

API Abstraction

Never make raw axios.get or authFetch calls directly inside a .vue component. All interactions with the targo-hub or ERPNext backend must go through a dedicated service file (e.g., features/dispatch/api.ts).

State Management (Pinia)

• One Pinia store per domain.
• Do not store UI state in Pinia (e.g., isSidebarOpen). Use local ref() inside the component. Pinia is solely for caching fetched ERPNext data.

---

3. Tech Mobile App — Wizard UX

Technicians in the field are wearing gloves, dealing with glare, and often lack cellular signal. Complex, scrolling forms are forbidden.

Core Mobile Principles

1. Minimal inputs per screen: Max 2-3 fields per step.
2. Carousel/swipe navigation: Horizontal navigation instead of vertical scrolling.
3. Big touch targets: Buttons minimum 48px height, inputs 56px+.
4. Auto-advance: When a user taps a selection card, immediately slide to the next step.
5. Offline-first: All completed Wizards must queue locally via IndexedDB if the device lacks internet access, syncing silently once connectivity is restored.

The Component: WizardCarousel.vue

All tech jobs (Installation, Diagnostic Swap, Closure) utilize a dynamic carousel driven by a JSON schema representing steps.

<WizardCarousel
  :steps="wizardSteps"
  :context="{ job, customer, location }"
  @complete="onComplete" />

Flow Example: Diagnostic Wizard

1. Problème signalé [Info Card] → Shows linked Ticket context.
2. Signal ONT [Toggle + Text Input] → Signal present? Input dBm level.
3. Action Prise [Select Cards] → "Redémarrage" / "Swap Hardware".
4. Nouvel équipement [Barcode Scan] → Triggers device camera to read ONT MAC address.
5. Signature [Touch Pad] → Client signs to confirm completion.
6. Résumé [Info Card] → Syncs automatically if connection is active.