How boxabirds/softwarepilots works
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: src/index.ts Backend API · src Tutor app · routes API routes · src/index.ts Evaluator
Components 23
Marketing site
Standalone Astro site for public pages and content.
- Public site · Manifesto and landing pages for the public domain.
src
Tutor web app
Pages-hosted learner-facing React application.
- Tutor app · Learner-facing dashboard, lessons, exercises, sessions, and admin UI.
packages/web/src - API bridge · Browser-facing function that forwards app API calls to the backend worker.
packages/web/functions/api/[[path]].ts - Client data · Frontend-side request helpers, auth handling, and chat/persistence integration.
packages/web/src/lib - Screens · Dashboard, curriculum, lesson, Socratic session, simulation, and admin pages.
packages/web/src/pages - UI system · 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 · Server-side application service for tutoring, progress, curriculum, and admin operations.
packages/api/src/index.ts - Session auth · Validates sessions and gates authenticated API access.
packages/api/src/middleware/session-validation.ts - API routes · Auth, chat, curriculum, progress, submissions, simulation, and admin endpoints.
packages/api/src/routes - Tutor engine · Assembles context, resolves prompts, calls Gemini, and applies tutor actions.
packages/api/src/lib/context-assembly.ts - Prompt system · Prompt definitions, resolution logic, and prompt data used by the tutor flow.
packages/api/src/lib/prompts - Domain stores · Curriculum, enrollment, learning-map, narrative, spaced-repetition, and progress logic.
packages/api/src/lib - D1 schema · System-of-record schema for conversations, curriculum, prompts, enrollments, claims, and progress.
packages/api/src/db/migrations - LLM adapter · 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 · Canonical curricula, learning maps, exercises, and simulation types used by web and API.
packages/shared/src - Learning maps · Track-specific curriculum maps and validators for Level 0, 1, 10, and 20.
packages/shared/src/curricula - Sim scenarios · Shared simulation types and scenario definitions used by tutor and evaluator flows.
packages/shared/src/simulation
Evaluator worker
Separate Worker for scoring submissions.
- Evaluator · Separate worker that scores code and solution submissions.
packages/evaluator/src/index.ts - Scoring pipeline · 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 · Deployment, seeding, prompt promotion, and local development scripts.
scripts - GitHub OAuth · Identity provider used for login and account linking.
- Gemini API · Model runtime used by tutoring and evaluation workers.
- D1 database · Persistent storage backing the API's curriculum, progress, and conversation state.
Connections 25
- 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.