> For the complete documentation index, see [llms.txt](https://t420.gitbook.io/t420/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t420.gitbook.io/t420/production-plan.md).

# production-plan

## FleetOS Refactor Production Plan

> **Status: EXECUTED** — All 4 phases were implemented as of 2026-04-04. This document is retained as a historical record of the refactoring plan. See the codebase for current architecture.

### Objective

Refactor FleetOS into a cleaner, more maintainable operations product while preserving current core behavior.

This plan is designed for incremental execution. The goal is not to redesign the company thesis. The goal is to reduce architectural drag, make workflow logic explicit, improve operator UX, and tighten copy so the product feels more trustworthy and conversion-ready.

***

### Guiding Principles

* Preserve current supplier vs fleet role behavior.
* Preserve core workflow behavior before improving it.
* Add compatibility wrappers during refactor.
* Prefer smaller, focused files over large controller files.
* Separate business logic from UI logic.
* Separate demo behavior from production behavior.
* Prioritize operational clarity over conceptual branding.

***

### Current Problem Areas

#### Architecture

* `App.tsx` is overloaded with bootstrap, onboarding, routing, and demo behavior.
* `hooks/useFleetOSDashboard.ts` acts like an application controller.
* `services/shared/QueryService.ts` mixes query, workflow, scheduling, relationship, and notification concerns.

#### Product Model

* Request status is overloaded.
* UI labels and domain truth are too closely mixed.
* Naming is ambiguous in key form and workflow paths.

#### UX/UI

* Dashboard hierarchy is dense.
* Role-specific next actions are not clear enough.
* Add-job flow is powerful but semantically messy.

#### Copy

* Landing page mixes strong operational copy with abstract conceptual language.
* Operator-facing language sometimes sounds like investor branding.

***

### Execution Phases

## Phase 1 — Stabilize the Architecture

### 1. Split `QueryService.ts`

#### Goal

Turn the shared service into explicit domain modules without breaking the app.

#### New target files

* `services/requests/RequestQueryService.ts`
* `services/requests/RequestWorkflowService.ts`
* `services/requests/RequestSchedulingService.ts`
* `services/relationships/RelationshipService.ts`

#### Work

* Move read/fetch operations into `RequestQueryService`
* Move request state transitions into `RequestWorkflowService`
* Move bay/technician scheduling logic into `RequestSchedulingService`
* Move relationship creation/fetch logic into `RelationshipService`
* Keep `services/shared/QueryService.ts` as a compatibility wrapper initially

#### Deliverables

* same behavior
* cleaner service boundaries
* easier testability
* explicit workflow ownership

***

### 2. Split `useFleetOSDashboard.ts`

#### Goal

Break the giant dashboard hook into focused modules.

#### New target files

* `hooks/dashboard/useDashboardData.ts`
* `hooks/dashboard/useDashboardFilters.ts`
* `hooks/dashboard/useDashboardActions.ts`
* `hooks/dashboard/useDashboardDemoState.ts`

#### Work

* Move loading/fetching into `useDashboardData`
* Move URL-backed filters into `useDashboardFilters`
* Move action handlers and optimistic updates into `useDashboardActions`
* Move demo fixtures and demo persistence into `useDashboardDemoState`
* Keep a small top-level `useFleetOSDashboard.ts` as composition only

#### Deliverables

* reduced file complexity
* easier reasoning about changes
* better separation of state concerns

***

### 3. Slim down `App.tsx`

#### Goal

Make `App.tsx` an app shell, not an orchestration layer.

#### New target files

* `services/onboarding/OnboardingService.ts`
* `services/auth/SessionBootstrapService.ts`
* `services/demo/DemoSeedService.ts`
* `lib/navigation/resolveInitialView.ts`

#### Work

* Move onboarding completion and profile creation out of `App.tsx`
* Move session bootstrap and stale-session validation out of `App.tsx`
* Move demo seeding out of `App.tsx`
* Move route/view resolution out of `App.tsx`
* Reduce `App.tsx` to composition, navigation, and page rendering

#### Deliverables

* smaller shell file
* less coupling between auth, onboarding, and UI rendering

***

## Phase 2 — Clarify the Product Model

### 4. Split `dashboard.ts`

#### Goal

Separate types, UI tokens, and mapping logic.

#### New target files

* `types/serviceRequest.ts`
* `types/contact.ts`
* `types/requestStatus.ts`
* `ui/dashboardTokens.ts`
* `ui/mapRequestToDashboardCard.ts`

#### Work

* move domain types into `types/*`
* move UI constants into `ui/dashboardTokens.ts`
* move status-to-card adaptation into `ui/mapRequestToDashboardCard.ts`
* keep compatibility exports during transition

#### Deliverables

* clearer separation between domain and presentation

***

### 5. Introduce explicit request status modeling

#### Goal

Stop overloading one status field with too much meaning.

#### Introduce internal models

* `RequestCommercialStatus`
  * requested
  * quoted
  * approved
  * declined
  * invoiced
* `RequestOperationalStatus`
  * unscheduled
  * scheduled
  * en\_route
  * in\_progress
  * waiting\_parts
  * ready\_for\_pickup
  * completed
  * cancelled
* `RequestPriority`
  * emergency
  * urgent
  * routine

#### Work

* add `services/requests/requestStateMachine.ts`
* define allowed transitions
* use compatibility mapping for current DB statuses
* avoid treating UI labels as domain truth

#### Deliverables

* more reliable business logic
* easier future scheduling/orchestration work

***

### 6. Standardize naming

#### Goal

Remove vague naming in forms and workflow code.

#### Replace vague names

Bad:

* `counterparty`
* `counterparty_name`
* `phone_only_name`

Better:

* `fleetCompanyName`
* `fleetContactName`
* `supplierCompanyName`
* `supplierContactPhone`
* `supplierContactEmail`

#### Work

* refactor form models
* refactor adapters
* refactor onboarding where touched
* preserve compatibility while transitioning

#### Deliverables

* clearer code
* less confusion in role-based flows

***

## Phase 3 — Improve Operator UX

### 7. Refactor `UnifiedDashboard.tsx`

#### Goal

Turn the dashboard into a clearer operator workspace.

#### New target files

* `components/fleetos/dashboard/DashboardTopBar.tsx`
* `components/fleetos/dashboard/DashboardTabs.tsx`
* `components/fleetos/dashboard/DashboardStatusStrip.tsx`
* `components/fleetos/dashboard/JobListPanel.tsx`
* `components/fleetos/dashboard/ContactsPanel.tsx`
* `components/fleetos/dashboard/DashboardDialogs.tsx`
* `components/fleetos/dashboard/DashboardOverlays.tsx`

#### Work

* split top bar, tabs, status strip, job list, contacts list, and dialogs into smaller sections
* reduce visual density
* reduce unnecessary all-caps
* surface one obvious next action per role
* make supplier and fleet views feel more distinct in purpose

#### Deliverables

* cleaner hierarchy
* easier maintainability
* more obvious operator workflow

***

### 8. Refactor `AddJobModal.tsx`

#### Goal

Keep all current functionality, but use explicit role-aware form models.

#### Work

* separate the form into clear sections:
  1. who is this for
  2. vehicle and location
  3. work required
  4. timing
  5. commercial controls
* use explicit field names
* keep fleet-only and supplier-only sections logically separated
* make scheduling, budget, and deadline easier to understand

#### Deliverables

* better form semantics
* lower cognitive load
* easier future changes

***

## Phase 4 — Improve Conversion and Trust

### 9. Rewrite `CleanLanding.tsx`

#### Goal

Make FleetOS sound like an operations product, not a conceptual protocol brand.

#### New target files

* `components/fleetos/landing/LandingPage.tsx`
* `components/fleetos/landing/MagicLinkEntry.tsx`
* `components/fleetos/landing/DemoEntry.tsx`
* `components/fleetos/landing/AccessRecoveryPanel.tsx`

#### Work

* split auth/demo/recovery from marketing layout
* rewrite abstract section headings
* emphasize request intake, coordination, audit trail, approvals, and downtime reduction
* keep magic-link-first access, but make first-time setup clearer

#### Copy direction

Use:

* Turn WhatsApp requests into trackable jobs
* Quote, track, and complete fleet service work from one dashboard
* No new app required
* One inbox for every service request
* Every job assigned and timestamped
* Faster approvals, less downtime
* Technician, bay, parts, and vehicle in one workflow

Avoid:

* “designed to empower”
* “creating calm”
* “protocol” heavy operator copy
* vague metaphors not tied to operational value

#### Deliverables

* stronger trust
* better operator conversion path
* cleaner separation of landing vs auth behavior

***

### 10. Copy pass across dashboard

#### Goal

Tighten operator language across the app.

#### Work

* reduce all-caps usage
* use clearer action labels
* improve tab names and empty states
* make FAQ language objection-oriented, not conceptual
* strengthen buyer confidence in operational value

#### Deliverables

* better readability
* more trustworthy operator-facing product language

***

### Suggested Commit Sequence

1. `refactor: split query service into request workflow query scheduling modules`
2. `refactor: decompose dashboard hook into data filters actions and demo modules`
3. `refactor: move onboarding session and demo bootstrap out of App`
4. `refactor: separate dashboard types ui tokens and mapping`
5. `feat: add explicit request state machine and compatibility mapping`
6. `refactor: standardize fleet supplier and contact naming`
7. `refactor: decompose unified dashboard into focused panels and dialogs`
8. `refactor: simplify add job modal with explicit role-based form model`
9. `rewrite: landing page copy and split auth demo and recovery flows`
10. `polish: tighten dashboard labels hierarchy and conversion copy`

***

### Definition of Done

The refactor is successful when:

* architecture is split into smaller clear modules
* workflow logic is explicit and guarded
* demo mode is isolated from production mode
* naming is clearer and role-explicit
* dashboard UX is easier to scan and act on
* landing page copy is more operational and trustworthy
* current core product behavior remains intact


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://t420.gitbook.io/t420/production-plan.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.