# andy1924/carrick architecture

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

- Interactive diagram: https://gitdiagram.com/andy1924/carrick
- Repository: https://github.com/andy1924/carrick

## Overview

Carrick turns field reports into reviewed, auditable schedule-progress exports. Supervisors import a schedule and submit notes or documents; the API extracts events, proposes activity matches, and stages them for planner clarification or approval before export. Rule-based matching is built into the worker, with optional AI retrieval and reranking. The README also describes structured progress history and CSV-log workflows. The map reflects the sampled API, worker, and web code; unsampled capabilities are included only where documented, and their internal links are omitted where implementation evidence is unavailable.

Main entry points: [`services/api/app.py`](https://github.com/andy1924/carrick/blob/main/services/api/app.py) (HTTP API), [`services/worker/ai.py`](https://github.com/andy1924/carrick/blob/main/services/worker/ai.py) (AI analysis), [`apps/web/app.js`](https://github.com/andy1924/carrick/blob/main/apps/web/app.js) (Workspace UI), [`services/worker/engine.py`](https://github.com/andy1924/carrick/blob/main/services/worker/engine.py) (Rule matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and interface"]
  node_workspace["Workspace UI<br/>[app.js]"]
  node_preview["Introduction preview<br/>[landing.js]"]
end

subgraph group_workflow["Progress workflow"]
  node_http["HTTP API<br/>[app.py]"]
  node_schedule_import["Schedule import<br/>[app.py]"]
  node_report_intake["Report intake<br/>[app.py]"]
  node_document_text["Document text<br/>[ingest.py]"]
  node_event_review["Event decisions<br/>[app.py]"]
  node_progress_export["Progress export<br/>[app.py]"]
end

subgraph group_analysis["Schedule analysis"]
  node_schedule_parser["Schedule parser<br/>[engine.py]"]
  node_rule_matching["Rule matching<br/>[engine.py]"]
  node_ai_analysis["AI analysis<br/>[ai.py]"]
end

subgraph group_state["Persistence and integrations"]
  node_sqlite[("SQLite state<br/>[app.py]")]
  node_openai{{"OpenAI API"}}
end

node_supervisor(("Supervisor"))
node_planner(("Planner"))

node_supervisor -->|"submits updates"| node_workspace
node_planner -->|"reviews events"| node_workspace
node_workspace -->|"calls API"| node_http
node_preview -->|"requests preview"| node_http
node_http -->|"routes imports"| node_schedule_import
node_http -->|"routes reports"| node_report_intake
node_http -->|"routes decisions"| node_event_review
node_http -->|"routes exports"| node_progress_export
node_report_intake -->|"extracts documents"| node_document_text
node_schedule_import -->|"parses schedule"| node_schedule_parser
node_report_intake -->|"matches events"| node_rule_matching
node_report_intake -->|"analyzes with AI"| node_ai_analysis
node_ai_analysis -->|"uses schedule context"| node_rule_matching
node_ai_analysis -->|"requests embeddings"| node_openai
node_ai_analysis -->|"requests extraction"| node_openai
node_schedule_import -->|"stores schedule"| node_sqlite
node_report_intake -->|"stores reports"| node_sqlite
node_event_review -->|"records decisions"| node_sqlite
node_progress_export -->|"reads approved progress"| node_sqlite

click node_workspace "https://github.com/andy1924/carrick/blob/main/apps/web/app.js"
click node_preview "https://github.com/andy1924/carrick/blob/main/apps/web/landing.js"
click node_http "https://github.com/andy1924/carrick/blob/main/services/api/app.py"
click node_schedule_import "https://github.com/andy1924/carrick/blob/main/services/api/app.py"
click node_report_intake "https://github.com/andy1924/carrick/blob/main/services/api/app.py"
click node_document_text "https://github.com/andy1924/carrick/blob/main/services/worker/ingest.py"
click node_event_review "https://github.com/andy1924/carrick/blob/main/services/api/app.py"
click node_progress_export "https://github.com/andy1924/carrick/blob/main/services/api/app.py"
click node_schedule_parser "https://github.com/andy1924/carrick/blob/main/services/worker/engine.py"
click node_rule_matching "https://github.com/andy1924/carrick/blob/main/services/worker/engine.py"
click node_ai_analysis "https://github.com/andy1924/carrick/blob/main/services/worker/ai.py"
click node_sqlite "https://github.com/andy1924/carrick/blob/main/services/api/app.py"

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_workspace,node_preview toneBlue
class node_http,node_schedule_import,node_report_intake,node_document_text,node_event_review,node_progress_export toneAmber
class node_schedule_parser,node_rule_matching,node_ai_analysis toneMint
class node_sqlite,node_openai toneRose
class node_supervisor,node_planner toneIndigo
```

## Components

### Capture and interface

- [Workspace UI](https://github.com/andy1924/carrick/blob/main/apps/web/app.js): `apps/web/app.js`
- [Introduction preview](https://github.com/andy1924/carrick/blob/main/apps/web/landing.js): `apps/web/landing.js`

### Progress workflow

- [HTTP API](https://github.com/andy1924/carrick/blob/main/services/api/app.py): `services/api/app.py`
- [Schedule import](https://github.com/andy1924/carrick/blob/main/services/api/app.py): `services/api/app.py`
- [Report intake](https://github.com/andy1924/carrick/blob/main/services/api/app.py): `services/api/app.py`
- [Document text](https://github.com/andy1924/carrick/blob/main/services/worker/ingest.py): `services/worker/ingest.py`
- [Event decisions](https://github.com/andy1924/carrick/blob/main/services/api/app.py): `services/api/app.py`
- [Progress export](https://github.com/andy1924/carrick/blob/main/services/api/app.py): `services/api/app.py`

### Schedule analysis

- [Schedule parser](https://github.com/andy1924/carrick/blob/main/services/worker/engine.py): `services/worker/engine.py`
- [Rule matching](https://github.com/andy1924/carrick/blob/main/services/worker/engine.py): `services/worker/engine.py`
- [AI analysis](https://github.com/andy1924/carrick/blob/main/services/worker/ai.py): `services/worker/ai.py`

### Persistence and integrations

- [SQLite state](https://github.com/andy1924/carrick/blob/main/services/api/app.py): `services/api/app.py`
- **OpenAI API**

### Other components

- **Supervisor**
- **Planner**

## Connections

- Supervisor → Workspace UI: submits updates (evidence: `README.md`)
- Planner → Workspace UI: reviews events (evidence: `README.md`)
- Workspace UI → HTTP API: calls API (evidence: `apps/web/app.js`)
- Introduction preview → HTTP API: requests preview (evidence: `apps/web/landing.js`)
- HTTP API → Schedule import: routes imports (evidence: `services/api/app.py`)
- HTTP API → Report intake: routes reports (evidence: `services/api/app.py`)
- HTTP API → Event decisions: routes decisions (evidence: `services/api/app.py`)
- HTTP API → Progress export: routes exports (evidence: `services/api/app.py`)
- Report intake → Document text: extracts documents (evidence: `services/api/app.py`)
- Schedule import → Schedule parser: parses schedule (evidence: `services/api/app.py`)
- Report intake → Rule matching: matches events (evidence: `services/api/app.py`)
- Report intake → AI analysis: analyzes with AI (evidence: `services/api/app.py`)
- AI analysis → Rule matching: uses schedule context (evidence: `services/worker/ai.py`)
- AI analysis → OpenAI API: requests embeddings (evidence: `services/worker/ai.py`)
- AI analysis → OpenAI API: requests extraction (evidence: `services/worker/ai.py`)
- Schedule import → SQLite state: stores schedule (evidence: `README.md`)
- Report intake → SQLite state: stores reports (evidence: `README.md`)
- Event decisions → SQLite state: records decisions (evidence: `README.md`)
- Progress export → SQLite state: reads approved progress (evidence: `README.md`)
