> 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/agent.md).

# FleetOS Refactor Agent

## Mission

Refactor FleetOS into a cleaner, more reliable operations product without changing its core user-facing behavior.

The product already has a strong wedge:

* turn WhatsApp/email/web requests into structured jobs
* allow fleet ↔ supplier coordination
* track quoting, approval, execution, completion
* support technician, bay, parts, and vehicle coordination

Your job is to reduce architectural mess, tighten domain logic, improve operator UX, and sharpen copy.

Do not rebuild the product from scratch. Do not remove major existing workflows. Refactor in place with compatibility layers where needed.

***

## Core Objectives

1. Reduce architectural complexity in:
   * `App.tsx`
   * `hooks/useFleetOSDashboard.ts`
   * `services/shared/QueryService.ts`
2. Separate:
   * business workflow logic
   * data access
   * UI mapping
   * demo-mode behavior
3. Standardize naming:
   * remove vague names like `counterparty`, `counterparty_name`, `phone_only_name`
   * use explicit domain names for fleet/supplier/company/contact fields
4. Improve dashboard clarity:
   * one obvious next action per role
   * cleaner hierarchy
   * lower visual noise
   * clearer separation of monitor state vs edit state
5. Rewrite landing-page copy to sound like a serious operations tool, not a conceptual “protocol” brand.

***

## Non-Negotiables

* Preserve supplier vs fleet role behavior.
* Preserve the core request lifecycle:
  * request created
  * supplier responds / quotes
  * fleet approves
  * work starts
  * work completes
* Preserve magic-link-first access flow, but improve its structure.
* Preserve demo mode, but isolate it from production logic.
* Keep new code strongly typed.
* Prefer smaller focused files over giant controller files.
* Avoid introducing large new dependencies unless absolutely necessary.

***

## Product Truth

FleetOS is not a generic ticketing app.

It is a fleet-service coordination layer for real operational work:

* roadside
* tires
* repairs
* maintenance
* shop scheduling
* parts coordination
* technician assignment
* audit trail

The product should feel like:

* fewer missed jobs
* faster approvals
* less admin
* shorter downtime
* clearer accountability
* better service history

The product should not feel like:

* abstract protocol marketing
* conceptual futurism
* vague “empower/calm” branding

***

## Current Repo Priorities

### Phase 1 — Architecture

Refactor first:

1. `services/shared/QueryService.ts`
2. `hooks/useFleetOSDashboard.ts`
3. `App.tsx`

### Phase 2 — Domain/UI Separation

Then: 4. `components/fleetos/types/dashboard.ts` 5. status mapping and workflow modeling

### Phase 3 — UX/UI

Then: 6. `components/fleetos/pages/UnifiedDashboard.tsx` 7. `components/fleetos/forms/AddJobModal.tsx`

### Phase 4 — Copy / Conversion

Then: 8. `components/fleetos/pages/CleanLanding.tsx`

***

## Required Refactor Direction

### 1. `App.tsx`

Target: app shell only.

Move out:

* onboarding completion logic
* company/user/profile creation logic
* demo seeding
* session bootstrap logic
* route resolution logic

Create dedicated modules such as:

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

Goal: `App.tsx` should mostly:

* bootstrap session
* resolve view
* render current page

### 2. `useFleetOSDashboard.ts`

Split into focused hooks:

* `useDashboardData`
* `useDashboardFilters`
* `useDashboardActions`
* `useDashboardDemoState`

Goal: this should stop being an all-in-one controller hook.

### 3. `QueryService.ts`

Split by responsibility:

* `RequestQueryService.ts`
* `RequestWorkflowService.ts`
* `RequestSchedulingService.ts`
* `RelationshipService.ts`

Important: workflow transitions must be explicit and guarded.

### 4. Status Model

Current status logic is overloaded.

Introduce a cleaner internal model:

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

You may keep the existing DB status compatibility layer for now, but do not let display labels masquerade as domain truth.

### 5. Naming Cleanup

Replace vague names with explicit names.

Bad:

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

Better:

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

### 6. Demo Mode

Demo logic must be isolated.

Create:

* `demo/fixtures/*.ts`
* `demo/DemoModeService.ts`

Avoid scattering `isDemo` branching through core production logic.

### 7. UX/UI Principles

The dashboard must feel operational.

Priorities:

* clearer hierarchy
* fewer all-caps labels
* fewer simultaneous actions
* clearer “what happens next”
* role-specific clarity for supplier vs fleet

### 8. Copy Principles

Use concrete operational language.

Good:

* Turn WhatsApp requests into trackable jobs
* Quote, track, and complete fleet service work
* No new app required
* Every request logged, assigned, and tracked
* Faster approvals, less downtime

Avoid:

* protocol-heavy language
* “designed to empower”
* “creating calm”
* vague metaphors unless tightly tied to ops value

***

## Landing Page Copy Direction

Use language like:

### Hero

**Turn WhatsApp requests into trackable jobs**\
Quote, track, and complete fleet service work from one dashboard.\
No new app required. Keep using WhatsApp and email, but run the job in FleetOS.

### Supporting sections

* One inbox for every service request
* Every job assigned and timestamped
* Faster approvals, less downtime
* Technician, bay, parts, and vehicle in one workflow
* Full service history for every fleet relationship

***

## Execution Rules

* Make incremental commits.
* Keep compatibility wrappers while refactoring.
* Do not break the app just to achieve purity.
* Preserve current flows before improving them.
* Prefer moving logic into services/hooks rather than rewriting behavior first.
* If uncertain, choose operational clarity over cleverness.

***

## Definition of Success

Success means:

* smaller, clearer files
* explicit workflow logic
* cleaner naming
* demo isolated from production
* dashboard easier to understand
* landing page more trustworthy and conversion-ready
* no loss of core product capability


---

# 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/agent.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.