# boxabirds/softwarepilots architecture

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

- Interactive diagram: https://gitdiagram.com/boxabirds/softwarepilots
- Repository: https://github.com/boxabirds/softwarepilots

## Overview

1. **Top-level shape**
   This repo is a multi-app Cloudflare project. It splits into a public static marketing site, a learner-facing tutor app, a backend API worker, a separate code-evaluation worker, and a shared domain library. The main architectural boundary is between the browser-facing web app and the Cloudflare Workers backend.

2. **Public marketing site (`src/`)**
   The root `src/` directory is a standalone Astro site for the manifesto/landing pages at softwarepilotry.com. It is static content plus layouts and styles, separate from the tutor product and deployed independently from the app stack.

3. **Tutor frontend (`packages/web/`)**
   The web app is a React + Vite frontend deployed on Cloudflare Pages. It contains the learner experience: dashboard, curriculum navigation, lesson detail, Socratic sessions, simulation pages, admin screens, and reusable UI components. It also includes a Pages Function at `functions/api/[[path]].ts`, which acts as the app’s API bridge/proxy.

4. **Backend API (`packages/api/`)**
   The API is a Hono-based Cloudflare Worker backed by D1. It owns authentication, curriculum reads/writes, chat/session persistence, submissions, progress tracking, prompts, enrollment, admin operations, and tutor-specific endpoints. This is the primary application service and the place where server-side state and business rules live.

5. **Tutor conversation engine**
   The central runtime flow is: browser sends a learner message → API validates the session and loads context → Gemini is called with versioned prompts and tool-calling instructions → Gemini chooses a tutor action such as probing, evaluating, scenario presentation, direct instruction, or completion → the API persists the conversation and any derived state → the web UI renders the response. This is a Socratic, tool-driven chat system rather than a simple prompt-response chat.

6. **Progress, claims, and learning maps**
   Progress is modeled around section-level learning maps and claims, not just message history. The API stores claim assessments, enrollments, progress concepts, completions, and summaries in D1. Completion is derived from demonstrated claims, and the system supports spaced repetition so completed concepts can later decay into review.

7. **Shared domain package (`packages/shared/`)**
   `packages/shared/` is the canonical domain model for curricula, learning maps, exercise/simulation types, and validation logic. It contains the per-track curriculum definitions for Level 0, 1, 10, and 20, plus shared scenarios and learning-map validators. Both the web and API depend on this package to stay aligned on curriculum structure and simulation data.

8. **Curriculum and track boundaries**
   The product is organized by track: Level 1, 10, and 20 are active; Level 0 exists but is hidden from the UI. Each track has its own curriculum content and tutor guidance, while some later modules are shared. This means the curriculum layer is not just content; it is a first-class part of the architecture that shapes UI navigation, prompts, and tutoring behavior.

9. **Evaluator service (`packages/evaluator/`)**
   The evaluator is a separate Worker used for scoring code or solution submissions. It builds a scoring pipeline from prompt construction, gap calculation, and response parsing, and it depends on Gemini API access. This keeps assessment logic isolated from the main tutoring API.

10. **Persistence and infrastructure**
    D1 is the system of record for the API: migrations define schema for curriculum, conversations, prompts, enrollments, learning maps, and learner preferences. Cloudflare Pages hosts the frontend, Workers host the API and evaluator, and Gemini provides the LLM runtime. GitHub OAuth is used for authentication, with JWT-based session validation in the API middleware.

11. **Operations and content management**
    The `scripts/` directory contains deployment, seeding, prompt-management, and local-dev automation. Prompt changes are versioned in D1 and promoted from staging to production via scripts, which means tutoring behavior can evolve without redeploying code. Curriculum and prompt seeds are also treated as operational data, not hardcoded constants.

12. **What to diagram**
    A useful architecture diagram should show four main execution zones: the static marketing site, the Pages-hosted React app, the Worker API with D1 and Gemini, and the evaluator Worker. Then add the shared domain package as a cross-cutting dependency, plus external services for GitHub OAuth and Gemini. The key data flows are learner UI requests into the API, API-to-Gemini tutor turns, API-to-D1 persistence, and evaluator runs for scored submissions.

Main entry points: [`packages/api/src/index.ts`](https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/index.ts) (Backend API), [`packages/web/src`](https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src) (Tutor app), [`packages/api/src/routes`](https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/routes) (API routes), [`packages/evaluator/src/index.ts`](https://github.com/boxabirds/softwarepilots/blob/main/packages/evaluator/src/index.ts) (Evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_marketing["Marketing site"]
  node_marketing_site["Public site<br/>Astro static site"]
end

subgraph group_web["Tutor web app"]
  node_web_app["Tutor app<br/>React Pages app"]
  node_web_proxy["API bridge<br/>Pages Function proxy<br/>[[[path]].ts]"]
  node_web_client["Client data<br/>API client + auth"]
  node_web_pages["Screens<br/>Routes and views"]
  node_web_ui["UI system<br/>Reusable components"]
end

subgraph group_api["API worker"]
  node_api_worker["Backend API<br/>Hono Worker<br/>[index.ts]"]
  node_api_auth["Session auth<br/>Middleware"]
  node_api_routes["API routes<br/>HTTP routes"]
  node_api_context{{"Tutor engine<br/>Conversation orchestration"}}
  node_api_prompts["Prompt system<br/>Versioned prompts"]
  node_api_persistence[("Domain stores<br/>State and rules")]
  node_api_db[("D1 schema<br/>Migrations")]
  node_api_gemini["LLM adapter<br/>Gemini client<br/>[gemini.ts]"]
end

subgraph group_shared["Shared domain"]
  node_shared_domain["Curriculum core<br/>Shared package"]
  node_shared_maps{{"Learning maps<br/>Track maps"}}
  node_shared_sim["Sim scenarios<br/>Simulation data"]
end

subgraph group_eval["Evaluator worker"]
  node_evaluator_worker["Evaluator<br/>Scoring Worker<br/>[index.ts]"]
  node_evaluator_pipeline{{"Scoring pipeline<br/>Prompted scoring<br/>[pipeline.ts]"}}
end

subgraph group_infra["Infra and ops"]
  node_ops_scripts["Ops scripts<br/>Automation"]
  node_github_oauth(("GitHub OAuth<br/>External auth"))
  node_gemini_api(("Gemini API<br/>External LLM"))
  node_d1_storage[("D1 database<br/>Cloudflare D1")]
end

node_marketing_site -.->|"deployed by"| node_ops_scripts
node_web_app -->|"calls"| node_web_proxy
node_web_app -->|"uses"| node_web_client
node_web_app -->|"renders"| node_web_pages
node_web_app -->|"composes"| node_web_ui
node_web_app -->|"reads curriculum"| node_shared_domain
node_web_proxy -->|"forwards to"| node_api_worker
node_api_worker -->|"applies"| node_api_auth
node_api_worker -->|"serves"| node_api_routes
node_api_routes -->|"orchestrates"| node_api_context
node_api_routes -->|"persists and reads"| node_api_persistence
node_api_context -->|"uses"| node_api_prompts
node_api_context -->|"calls"| node_api_gemini
node_api_persistence -->|"stored in"| node_api_db
node_api_routes -->|"validates against"| node_shared_domain
node_api_prompts -->|"references"| node_shared_domain
node_evaluator_worker -->|"runs"| node_evaluator_pipeline
node_evaluator_pipeline -->|"calls"| node_gemini_api
node_evaluator_worker -->|"scores against"| node_shared_sim
node_ops_scripts -->|"migrates and seeds"| node_api_db
node_ops_scripts -->|"promotes"| node_api_prompts
node_api_worker -.->|"authenticates via"| node_github_oauth
node_api_worker -.->|"depends on"| node_gemini_api
node_evaluator_worker -.->|"depends on"| node_gemini_api
node_api_worker -.->|"stores state in"| node_d1_storage

click node_marketing_site "https://github.com/boxabirds/softwarepilots/tree/main/src"
click node_web_app "https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src"
click node_web_proxy "https://github.com/boxabirds/softwarepilots/blob/main/packages/web/functions/api/[[path]].ts"
click node_web_client "https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src/lib"
click node_web_pages "https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src/pages"
click node_web_ui "https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src/components"
click node_api_worker "https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/index.ts"
click node_api_auth "https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/middleware/session-validation.ts"
click node_api_routes "https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/routes"
click node_api_context "https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/lib/context-assembly.ts"
click node_api_prompts "https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/lib/prompts"
click node_api_persistence "https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/lib"
click node_api_db "https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/db/migrations"
click node_api_gemini "https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/lib/gemini.ts"
click node_shared_domain "https://github.com/boxabirds/softwarepilots/tree/main/packages/shared/src"
click node_shared_maps "https://github.com/boxabirds/softwarepilots/tree/main/packages/shared/src/curricula"
click node_shared_sim "https://github.com/boxabirds/softwarepilots/tree/main/packages/shared/src/simulation"
click node_evaluator_worker "https://github.com/boxabirds/softwarepilots/blob/main/packages/evaluator/src/index.ts"
click node_evaluator_pipeline "https://github.com/boxabirds/softwarepilots/blob/main/packages/evaluator/src/scoring/pipeline.ts"
click node_ops_scripts "https://github.com/boxabirds/softwarepilots/tree/main/scripts"

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_marketing_site toneBlue
class node_web_app,node_web_proxy,node_web_client,node_web_pages,node_web_ui toneAmber
class node_api_worker,node_api_auth,node_api_routes,node_api_context,node_api_prompts,node_api_persistence,node_api_db,node_api_gemini toneMint
class node_shared_domain,node_shared_maps,node_shared_sim toneRose
class node_evaluator_worker,node_evaluator_pipeline toneIndigo
class node_ops_scripts,node_github_oauth,node_gemini_api,node_d1_storage toneTeal
```

## Components

### Marketing site

Standalone Astro site for public pages and content.

- [Public site](https://github.com/boxabirds/softwarepilots/tree/main/src): Astro static site · Manifesto and landing pages for the public domain. · `src`

### Tutor web app

Pages-hosted learner-facing React application.

- [Tutor app](https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src): React Pages app · Learner-facing dashboard, lessons, exercises, sessions, and admin UI. · `packages/web/src`
- [API bridge](https://github.com/boxabirds/softwarepilots/blob/main/packages/web/functions/api/[[path]].ts): Pages Function proxy · Browser-facing function that forwards app API calls to the backend worker. · `packages/web/functions/api/[[path]].ts`
- [Client data](https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src/lib): API client + auth · Frontend-side request helpers, auth handling, and chat/persistence integration. · `packages/web/src/lib`
- [Screens](https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src/pages): Routes and views · Dashboard, curriculum, lesson, Socratic session, simulation, and admin pages. · `packages/web/src/pages`
- [UI system](https://github.com/boxabirds/softwarepilots/tree/main/packages/web/src/components): Reusable components · Shared presentation components for navigation, chat, progress, and exercises. · `packages/web/src/components`

### API worker

Primary Cloudflare Worker for tutoring, progress, and auth.

- [Backend API](https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/index.ts): Hono Worker · Server-side application service for tutoring, progress, curriculum, and admin operations. · `packages/api/src/index.ts`
- [Session auth](https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/middleware/session-validation.ts): Middleware · Validates sessions and gates authenticated API access. · `packages/api/src/middleware/session-validation.ts`
- [API routes](https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/routes): HTTP routes · Auth, chat, curriculum, progress, submissions, simulation, and admin endpoints. · `packages/api/src/routes`
- [Tutor engine](https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/lib/context-assembly.ts): Conversation orchestration · Assembles context, resolves prompts, calls Gemini, and applies tutor actions. · `packages/api/src/lib/context-assembly.ts`
- [Prompt system](https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/lib/prompts): Versioned prompts · Prompt definitions, resolution logic, and prompt data used by the tutor flow. · `packages/api/src/lib/prompts`
- [Domain stores](https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/lib): State and rules · Curriculum, enrollment, learning-map, narrative, spaced-repetition, and progress logic. · `packages/api/src/lib`
- [D1 schema](https://github.com/boxabirds/softwarepilots/tree/main/packages/api/src/db/migrations): Migrations · System-of-record schema for conversations, curriculum, prompts, enrollments, claims, and progress. · `packages/api/src/db/migrations`
- [LLM adapter](https://github.com/boxabirds/softwarepilots/blob/main/packages/api/src/lib/gemini.ts): Gemini client · Wrapper around model calls for tutoring and prompt-driven responses. · `packages/api/src/lib/gemini.ts`

### Shared domain

Canonical curricula, learning maps, and simulation types.

- [Curriculum core](https://github.com/boxabirds/softwarepilots/tree/main/packages/shared/src): Shared package · Canonical curricula, learning maps, exercises, and simulation types used by web and API. · `packages/shared/src`
- [Learning maps](https://github.com/boxabirds/softwarepilots/tree/main/packages/shared/src/curricula): Track maps · Track-specific curriculum maps and validators for Level 0, 1, 10, and 20. · `packages/shared/src/curricula`
- [Sim scenarios](https://github.com/boxabirds/softwarepilots/tree/main/packages/shared/src/simulation): Simulation data · Shared simulation types and scenario definitions used by tutor and evaluator flows. · `packages/shared/src/simulation`

### Evaluator worker

Separate Worker for scoring submissions.

- [Evaluator](https://github.com/boxabirds/softwarepilots/blob/main/packages/evaluator/src/index.ts): Scoring Worker · Separate worker that scores code and solution submissions. · `packages/evaluator/src/index.ts`
- [Scoring pipeline](https://github.com/boxabirds/softwarepilots/blob/main/packages/evaluator/src/scoring/pipeline.ts): Prompted scoring · Builds scoring prompts, computes gaps, and parses evaluation responses. · `packages/evaluator/src/scoring/pipeline.ts`

### Infra and ops

Deployment, seeding, and prompt-management scripts plus external services.

- [Ops scripts](https://github.com/boxabirds/softwarepilots/tree/main/scripts): Automation · Deployment, seeding, prompt promotion, and local development scripts. · `scripts`
- **GitHub OAuth**: External auth · Identity provider used for login and account linking.
- **Gemini API**: External LLM · Model runtime used by tutoring and evaluation workers.
- **D1 database**: Cloudflare D1 · Persistent storage backing the API's curriculum, progress, and conversation state.

## Connections

- Public site → Ops scripts: deployed by · Marketing site is managed alongside the repo's deployment scripts.
- Tutor app → API bridge: calls · Browser UI sends API requests through the Pages Function bridge.
- Tutor app → Client data: uses · Screens rely on shared client helpers and auth/session utilities.
- Tutor app → Screens: renders · Top-level routes compose the learner and admin screens.
- Tutor app → UI system: composes · Pages are built from reusable UI components.
- Tutor app → Curriculum core: reads curriculum · Frontend navigation and lesson structure come from shared domain data.
- API bridge → Backend API: forwards to · Pages function proxies app API traffic to the backend worker.
- Backend API → Session auth: applies · Requests pass through session validation before route handling.
- Backend API → API routes: serves · Worker exposes the main HTTP surface through route modules.
- API routes → Tutor engine: orchestrates · Tutor/chat routes invoke context assembly and model-driven action selection.
- API routes → Domain stores: persists and reads · Routes load curriculum, progress, conversations, and enrollment state.
- Tutor engine → Prompt system: uses · Conversation flow resolves versioned prompts and instructions.
- Tutor engine → LLM adapter: calls · Tutor turns are executed through the Gemini adapter.
- Domain stores → D1 schema: stored in · Domain state is backed by D1 migrations and schema.
- API routes → Curriculum core: validates against · API enforces track, curriculum, and simulation structures from the shared package.
- Prompt system → Curriculum core: references · Prompt logic is aligned with shared curricula and scenario definitions.
- Evaluator → Scoring pipeline: runs · Evaluation worker delegates scoring to the pipeline modules.
- Scoring pipeline → Gemini API: calls · Scoring uses the Gemini API for model-assisted assessment.
- Evaluator → Sim scenarios: scores against · Evaluator consumes shared simulation and exercise definitions.
- Ops scripts → D1 schema: migrates and seeds · Scripts manage prompt/version seeding and database setup.
- Ops scripts → Prompt system: promotes · Prompt changes are copied and promoted through automation.
- Backend API → GitHub OAuth: authenticates via · Login flow depends on GitHub OAuth.
- Backend API → Gemini API: depends on · Backend tutoring flow relies on the external model runtime.
- Evaluator → Gemini API: depends on · Evaluation worker also relies on the model runtime.
- Backend API → D1 database: stores state in · Primary application state is persisted in D1.
