# redward42/pitcrew architecture

> Architecture diagram of the GitHub repository redward42/pitcrew, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redward42/pitcrew
- Repository: https://github.com/redward42/pitcrew

## Overview

PitCrew is a data-center operations product: sector agents investigate faults, create and route work for qualified technicians, and preserve field findings through lead handoff. The README describes the main journey as Overview → Sector evidence → Work queue → Field checks → Lead handoff. The graph includes that sector workflow alongside earlier investigation, procedure, decision, and communications capabilities. Evidence is limited to the README, SOURCE INDEX references, and sampled excerpts; unsampled UI and API wiring is not inferred.

Main entry points: [`services/core/store.ts`](https://github.com/RedWARd42/PitCrew/blob/main/services/core/store.ts) (State and command store), [`apps/field/components/field-app.tsx`](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/field-app.tsx) (Field and investigation UI), [`services/comms/index.ts`](https://github.com/RedWARd42/PitCrew/blob/main/services/comms/index.ts) (Escalation and handoff), [`services/agents/fleet-agent.ts`](https://github.com/RedWARd42/PitCrew/blob/main/services/agents/fleet-agent.ts) (Fleet agent workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Operator experience"]
  node_sectorui["Sector operations UI<br/>[fleet-app.tsx]"]
  node_fieldui["Field and investigation UI<br/>[field-app.tsx]"]
  node_decisionui["Decision room<br/>[decision-room.tsx]"]
  node_taskui["Task experience"]
  node_investigationui["Investigation UI<br/>[investigation.tsx]"]
end

subgraph group_api["Application API"]
  node_api_routes["Core API routes"]
  node_fleet_api["Fleet API<br/>[route.ts]"]
  node_tools_api["Agent tools API<br/>[route.ts]"]
  node_procedure_api["Procedure compile API<br/>[route.ts]"]
  node_webhook_api["Photon webhook API<br/>[route.ts]"]
end

subgraph group_operations["Operations domain"]
  node_contracts["Shared contracts<br/>[fleet.ts]"]
  node_store[("State and command store<br/>[store.ts]")]
  node_fleet["Fleet incidents and tickets<br/>[fleet.ts]"]
  node_investigation["Investigation state<br/>[investigation.ts]"]
  node_engines["Deterministic engines<br/>[index.ts]"]
  node_simulator["Plant simulator<br/>[index.ts]"]
end

subgraph group_intelligence["Agents and analysis"]
  node_agent_workflows["Fleet agent workflows<br/>[fleet-agent.ts]"]
  node_agent_tools["Advisory tools<br/>[tools.ts]"]
  node_provider["Model provider<br/>[provider.ts]"]
end

subgraph group_fieldcomms["Field and communications"]
  node_comms["Escalation and handoff<br/>[index.ts]"]
  node_photon["Photon messaging adapter<br/>[photon.ts]"]
  node_voice["ElevenLabs voice adapter<br/>[elevenlabs.ts]"]
  node_procedure_compiler["Procedure compiler<br/>[compiler-api.ts]"]
end

node_operator(("Operator / technician"))

node_operator -->|"uses"| node_sectorui
node_operator -->|"records field checks"| node_fieldui
node_sectorui -.->|"requests fleet data"| node_fleet_api
node_fieldui -.->|"uses Core API"| node_api_routes
node_fieldui -->|"renders"| node_decisionui
node_fieldui -->|"renders"| node_investigationui
node_fieldui -->|"renders"| node_taskui
node_fleet_api -->|"calls"| node_fleet
node_fleet_api -->|"validates with"| node_contracts
node_api_routes -->|"dispatches to"| node_store
node_tools_api -->|"reads state from"| node_store
node_tools_api -->|"calls"| node_agent_tools
node_procedure_api -->|"calls"| node_procedure_compiler
node_webhook_api -->|"updates"| node_store
node_webhook_api -->|"uses"| node_photon
node_webhook_api -->|"uses"| node_comms
node_store -->|"advances simulation"| node_simulator
node_store -->|"invokes coordinator"| node_agent_workflows
node_store -->|"processes escalations"| node_comms
node_store -->|"uses"| node_investigation
node_store -->|"validates state"| node_contracts
node_fleet -->|"uses"| node_agent_workflows
node_agent_workflows -->|"runs model workflows"| node_provider
node_agent_workflows -->|"runs deterministic checks"| node_engines
node_agent_tools -->|"calls"| node_engines
node_provider -->|"executes tools"| node_agent_tools
node_comms -->|"checks voice availability"| node_voice
node_photon -->|"implements delivery adapter"| node_comms
node_voice -->|"implements delivery adapter"| node_comms
node_procedure_compiler -->|"uses model provider"| node_provider
node_procedure_compiler -->|"uses schemas"| node_contracts

click node_sectorui "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/fleet-app.tsx"
click node_fieldui "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/field-app.tsx"
click node_decisionui "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/decision-room.tsx"
click node_taskui "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/task-experience.tsx"
click node_investigationui "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/investigation.tsx"
click node_api_routes "https://github.com/RedWARd42/PitCrew/tree/main/apps/field/app/api"
click node_fleet_api "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/app/api/fleet/route.ts"
click node_tools_api "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/app/api/tools/route.ts"
click node_procedure_api "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/app/api/procedures/compile/route.ts"
click node_webhook_api "https://github.com/RedWARd42/PitCrew/blob/main/apps/field/app/api/photon/webhook/route.ts"
click node_contracts "https://github.com/RedWARd42/PitCrew/blob/main/packages/contracts/fleet.ts"
click node_store "https://github.com/RedWARd42/PitCrew/blob/main/services/core/store.ts"
click node_fleet "https://github.com/RedWARd42/PitCrew/blob/main/services/core/fleet.ts"
click node_investigation "https://github.com/RedWARd42/PitCrew/blob/main/services/core/investigation.ts"
click node_engines "https://github.com/RedWARd42/PitCrew/blob/main/services/core/engines/index.ts"
click node_simulator "https://github.com/RedWARd42/PitCrew/blob/main/services/sim/index.ts"
click node_agent_workflows "https://github.com/RedWARd42/PitCrew/blob/main/services/agents/fleet-agent.ts"
click node_agent_tools "https://github.com/RedWARd42/PitCrew/blob/main/services/agents/tools.ts"
click node_provider "https://github.com/RedWARd42/PitCrew/blob/main/services/agents/provider.ts"
click node_comms "https://github.com/RedWARd42/PitCrew/blob/main/services/comms/index.ts"
click node_photon "https://github.com/RedWARd42/PitCrew/blob/main/services/comms/photon.ts"
click node_voice "https://github.com/RedWARd42/PitCrew/blob/main/services/comms/elevenlabs.ts"
click node_procedure_compiler "https://github.com/RedWARd42/PitCrew/blob/main/services/agents/compiler-api.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sectorui,node_fieldui,node_decisionui,node_taskui,node_investigationui toneBlue
class node_api_routes,node_fleet_api,node_tools_api,node_procedure_api,node_webhook_api toneAmber
class node_contracts,node_store,node_fleet,node_investigation,node_engines,node_simulator toneMint
class node_agent_workflows,node_agent_tools,node_provider toneRose
class node_comms,node_photon,node_voice,node_procedure_compiler,node_operator toneIndigo
```

## Components

### Operator experience

- [Sector operations UI](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/fleet-app.tsx): `apps/field/components/fleet-app.tsx`
- [Field and investigation UI](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/field-app.tsx): `apps/field/components/field-app.tsx`
- [Decision room](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/decision-room.tsx): `apps/field/components/decision-room.tsx`
- [Task experience](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/task-experience.tsx): `apps/field/components/task-experience.tsx`
- [Investigation UI](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/components/investigation.tsx): `apps/field/components/investigation.tsx`

### Application API

- [Core API routes](https://github.com/RedWARd42/PitCrew/tree/main/apps/field/app/api): `apps/field/app/api`
- [Fleet API](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/app/api/fleet/route.ts): `apps/field/app/api/fleet/route.ts`
- [Agent tools API](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/app/api/tools/route.ts): `apps/field/app/api/tools/route.ts`
- [Procedure compile API](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/app/api/procedures/compile/route.ts): `apps/field/app/api/procedures/compile/route.ts`
- [Photon webhook API](https://github.com/RedWARd42/PitCrew/blob/main/apps/field/app/api/photon/webhook/route.ts): `apps/field/app/api/photon/webhook/route.ts`

### Operations domain

- [Shared contracts](https://github.com/RedWARd42/PitCrew/blob/main/packages/contracts/fleet.ts): `packages/contracts/fleet.ts`
- [State and command store](https://github.com/RedWARd42/PitCrew/blob/main/services/core/store.ts): `services/core/store.ts`
- [Fleet incidents and tickets](https://github.com/RedWARd42/PitCrew/blob/main/services/core/fleet.ts): `services/core/fleet.ts`
- [Investigation state](https://github.com/RedWARd42/PitCrew/blob/main/services/core/investigation.ts): `services/core/investigation.ts`
- [Deterministic engines](https://github.com/RedWARd42/PitCrew/blob/main/services/core/engines/index.ts): `services/core/engines/index.ts`
- [Plant simulator](https://github.com/RedWARd42/PitCrew/blob/main/services/sim/index.ts): `services/sim/index.ts`

### Agents and analysis

- [Fleet agent workflows](https://github.com/RedWARd42/PitCrew/blob/main/services/agents/fleet-agent.ts): `services/agents/fleet-agent.ts`
- [Advisory tools](https://github.com/RedWARd42/PitCrew/blob/main/services/agents/tools.ts): `services/agents/tools.ts`
- [Model provider](https://github.com/RedWARd42/PitCrew/blob/main/services/agents/provider.ts): `services/agents/provider.ts`

### Field and communications

- [Escalation and handoff](https://github.com/RedWARd42/PitCrew/blob/main/services/comms/index.ts): `services/comms/index.ts`
- [Photon messaging adapter](https://github.com/RedWARd42/PitCrew/blob/main/services/comms/photon.ts): `services/comms/photon.ts`
- [ElevenLabs voice adapter](https://github.com/RedWARd42/PitCrew/blob/main/services/comms/elevenlabs.ts): `services/comms/elevenlabs.ts`
- [Procedure compiler](https://github.com/RedWARd42/PitCrew/blob/main/services/agents/compiler-api.ts): `services/agents/compiler-api.ts`

### Other components

- **Operator / technician**

## Connections

- Operator / technician → Sector operations UI: uses (evidence: `README.md`)
- Operator / technician → Field and investigation UI: records field checks (evidence: `README.md`)
- Sector operations UI → Fleet API: requests fleet data
- Field and investigation UI → Core API routes: uses Core API (evidence: `README.md`)
- Field and investigation UI → Decision room: renders (evidence: `apps/field/components/field-app.tsx`)
- Field and investigation UI → Investigation UI: renders (evidence: `apps/field/components/field-app.tsx`)
- Field and investigation UI → Task experience: renders (evidence: `apps/field/components/field-app.tsx`)
- Fleet API → Fleet incidents and tickets: calls (evidence: `apps/field/app/api/fleet/route.ts`)
- Fleet API → Shared contracts: validates with (evidence: `apps/field/app/api/fleet/route.ts`)
- Core API routes → State and command store: dispatches to (evidence: `apps/field/app/api/command/route.ts`)
- Agent tools API → State and command store: reads state from (evidence: `apps/field/app/api/tools/route.ts`)
- Agent tools API → Advisory tools: calls (evidence: `apps/field/app/api/tools/route.ts`)
- Procedure compile API → Procedure compiler: calls (evidence: `apps/field/app/api/procedures/compile/route.ts`)
- Photon webhook API → State and command store: updates (evidence: `apps/field/app/api/photon/webhook/route.ts`)
- Photon webhook API → Photon messaging adapter: uses (evidence: `apps/field/app/api/photon/webhook/route.ts`)
- Photon webhook API → Escalation and handoff: uses (evidence: `apps/field/app/api/photon/webhook/route.ts`)
- State and command store → Plant simulator: advances simulation (evidence: `services/core/store.ts`)
- State and command store → Fleet agent workflows: invokes coordinator (evidence: `services/core/store.ts`)
- State and command store → Escalation and handoff: processes escalations (evidence: `services/core/store.ts`)
- State and command store → Investigation state: uses (evidence: `services/core/store.ts`)
- State and command store → Shared contracts: validates state (evidence: `services/core/store.ts`)
- Fleet incidents and tickets → Fleet agent workflows: uses (evidence: `services/core/fleet.ts`)
- Fleet agent workflows → Model provider: runs model workflows
- Fleet agent workflows → Deterministic engines: runs deterministic checks
- Advisory tools → Deterministic engines: calls (evidence: `services/agents/tools.ts`)
- Model provider → Advisory tools: executes tools (evidence: `services/agents/provider.ts`)
- Escalation and handoff → ElevenLabs voice adapter: checks voice availability (evidence: `services/comms/index.ts`)
- Photon messaging adapter → Escalation and handoff: implements delivery adapter (evidence: `services/comms/photon.ts`)
- ElevenLabs voice adapter → Escalation and handoff: implements delivery adapter (evidence: `services/comms/elevenlabs.ts`)
- Procedure compiler → Model provider: uses model provider (evidence: `services/agents/compiler-api.ts`)
- Procedure compiler → Shared contracts: uses schemas (evidence: `services/agents/compiler-api.ts`)
