# 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):**
```text
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):**
```text
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. 

```vue
<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.