# zabrodsk/proof architecture

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

- Interactive diagram: https://gitdiagram.com/zabrodsk/proof
- Repository: https://github.com/zabrodsk/proof

## Overview

Proof is a web app for reviewing AP Seminar drafts, discovering scholarly sources, and producing MLA citations, alongside a separate landing page and waitlist. The main workflow is: a student imports or uploads a draft and sources, submits a review, and receives findings and evidence; the Studio workflow persists account-owned documents and runs through a worker, while the class workspace keeps review data in browser storage. The graph also preserves discovery, integrations, citation tools, and the separate waitlist. Some domain modules are represented from README capabilities and the source index; their internal calls are omitted where excerpts do not establish them.

Main entry points: [`src/main.tsx`](https://github.com/zabrodsk/proof/blob/main/src/main.tsx) (App entry), [`src/StudioSession.tsx`](https://github.com/zabrodsk/proof/blob/main/src/StudioSession.tsx) (Studio session), [`src/Classroom.tsx`](https://github.com/zabrodsk/proof/blob/main/src/Classroom.tsx) (Class workspace), [`server/classroom.ts`](https://github.com/zabrodsk/proof/blob/main/server/classroom.ts) (Class review jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Application experience"]
  node_app["App entry<br/>[main.tsx]"]
  node_studio["Studio workspace<br/>[Studio.tsx]"]
  node_studio_session["Studio session<br/>[StudioSession.tsx]"]
  node_studio_api["Studio API client<br/>[studio-api.ts]"]
  node_classroom_ui["Class workspace<br/>[Classroom.tsx]"]
  node_integration_ui["Integration workspace"]
end

subgraph group_review["Draft review"]
  node_class_review["Class review jobs<br/>[classroom.ts]"]
  node_document_parse["Document parsing<br/>[documents.ts]"]
  node_claim_judging["Claim assessment<br/>[judge.ts]"]
end

subgraph group_backend["Persistent analysis"]
  node_backend_router["Backend API<br/>[router.ts]"]
  node_run_service["Run management<br/>[service.ts]"]
  node_analysis_engine["Analysis engine<br/>[engine.ts]"]
  node_source_library["Source library<br/>[library.ts]"]
  node_job_worker["Job worker<br/>[worker.ts]"]
  node_postgres[("PostgreSQL<br/>[db.ts]")]
  node_file_storage[("Private file storage<br/>[storage.ts]")]
end

subgraph group_research["Research and citations"]
  node_source_discovery["Source discovery<br/>[discovery.ts]"]
  node_scholarly_sources["Scholarly source checks<br/>[scholarly.ts]"]
  node_mla_tool["MLA citations<br/>[mla.ts]"]
end

subgraph group_integrations["Connected services"]
  node_integration_service["Integration service<br/>[service.ts]"]
  node_mcp["MCP connection<br/>[mcp.ts]"]
end

subgraph group_landing["Landing and signup"]
  node_landing_page["Landing page<br/>[Landing.tsx]"]
  node_waitlist["Waitlist service<br/>[index.ts]"]
  node_waitlist_store[("Waitlist database<br/>[waitlist.ts]")]
end

node_student(("Student"))

node_student -->|"opens app"| node_app
node_app -->|"routes to"| node_studio_session
node_app -->|"routes to"| node_classroom_ui
node_app -->|"routes to"| node_integration_ui
node_studio_session -->|"renders"| node_studio
node_studio_session -->|"uses"| node_studio_api
node_studio_api -.->|"calls API"| node_backend_router
node_classroom_ui -.->|"submits reviews"| node_class_review
node_class_review -->|"parses documents"| node_document_parse
node_class_review -->|"assesses claims"| node_claim_judging
node_classroom_ui -.->|"formats class citations"| node_mla_tool
node_backend_router -->|"creates assets"| node_source_library
node_backend_router -->|"manages runs"| node_run_service
node_run_service -->|"stores run"| node_postgres
node_run_service -->|"enqueues run"| node_job_worker
node_job_worker -.->|"processes jobs"| node_analysis_engine
node_analysis_engine -->|"retrieves evidence"| node_source_library
node_analysis_engine -->|"stores findings"| node_postgres
node_source_library -.->|"persists files"| node_file_storage
node_student -.->|"finds sources"| node_source_discovery
node_student -.->|"checks scholarship"| node_scholarly_sources
node_student -.->|"generates citations"| node_mla_tool
node_integration_ui -.->|"uses integrations"| node_integration_service
node_integration_service -.->|"supports MCP"| node_mcp
node_student -.->|"visits site"| node_landing_page
node_landing_page -.->|"submits signup"| node_waitlist
node_waitlist -->|"stores signup"| node_waitlist_store

click node_app "https://github.com/zabrodsk/proof/blob/main/src/main.tsx"
click node_studio "https://github.com/zabrodsk/proof/blob/main/src/Studio.tsx"
click node_studio_session "https://github.com/zabrodsk/proof/blob/main/src/StudioSession.tsx"
click node_studio_api "https://github.com/zabrodsk/proof/blob/main/src/studio-api.ts"
click node_classroom_ui "https://github.com/zabrodsk/proof/blob/main/src/Classroom.tsx"
click node_integration_ui "https://github.com/zabrodsk/proof/blob/main/src/IntegrationWorkspace.tsx"
click node_class_review "https://github.com/zabrodsk/proof/blob/main/server/classroom.ts"
click node_document_parse "https://github.com/zabrodsk/proof/blob/main/server/documents.ts"
click node_claim_judging "https://github.com/zabrodsk/proof/blob/main/server/judge.ts"
click node_backend_router "https://github.com/zabrodsk/proof/blob/main/server/backend/router.ts"
click node_run_service "https://github.com/zabrodsk/proof/blob/main/server/backend/service.ts"
click node_analysis_engine "https://github.com/zabrodsk/proof/blob/main/server/backend/engine.ts"
click node_source_library "https://github.com/zabrodsk/proof/blob/main/server/backend/library.ts"
click node_job_worker "https://github.com/zabrodsk/proof/blob/main/server/worker.ts"
click node_postgres "https://github.com/zabrodsk/proof/blob/main/server/backend/db.ts"
click node_file_storage "https://github.com/zabrodsk/proof/blob/main/server/backend/storage.ts"
click node_source_discovery "https://github.com/zabrodsk/proof/blob/main/server/discovery.ts"
click node_scholarly_sources "https://github.com/zabrodsk/proof/blob/main/server/scholarly.ts"
click node_mla_tool "https://github.com/zabrodsk/proof/blob/main/shared/mla.ts"
click node_integration_service "https://github.com/zabrodsk/proof/blob/main/server/integrations/service.ts"
click node_mcp "https://github.com/zabrodsk/proof/blob/main/server/integrations/mcp.ts"
click node_landing_page "https://github.com/zabrodsk/proof/blob/main/site/src/Landing.tsx"
click node_waitlist "https://github.com/zabrodsk/proof/blob/main/site/worker/index.ts"
click node_waitlist_store "https://github.com/zabrodsk/proof/blob/main/site/db/waitlist.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_app,node_studio,node_studio_session,node_studio_api,node_classroom_ui,node_integration_ui toneBlue
class node_class_review,node_document_parse,node_claim_judging toneAmber
class node_backend_router,node_run_service,node_analysis_engine,node_source_library,node_job_worker,node_postgres,node_file_storage toneMint
class node_source_discovery,node_scholarly_sources,node_mla_tool toneRose
class node_integration_service,node_mcp,node_student toneIndigo
class node_landing_page,node_waitlist,node_waitlist_store toneTeal
```

## Components

### Application experience

- [App entry](https://github.com/zabrodsk/proof/blob/main/src/main.tsx): `src/main.tsx`
- [Studio workspace](https://github.com/zabrodsk/proof/blob/main/src/Studio.tsx): `src/Studio.tsx`
- [Studio session](https://github.com/zabrodsk/proof/blob/main/src/StudioSession.tsx): `src/StudioSession.tsx`
- [Studio API client](https://github.com/zabrodsk/proof/blob/main/src/studio-api.ts): `src/studio-api.ts`
- [Class workspace](https://github.com/zabrodsk/proof/blob/main/src/Classroom.tsx): `src/Classroom.tsx`
- [Integration workspace](https://github.com/zabrodsk/proof/blob/main/src/IntegrationWorkspace.tsx): `src/IntegrationWorkspace.tsx`

### Draft review

- [Class review jobs](https://github.com/zabrodsk/proof/blob/main/server/classroom.ts): `server/classroom.ts`
- [Document parsing](https://github.com/zabrodsk/proof/blob/main/server/documents.ts): `server/documents.ts`
- [Claim assessment](https://github.com/zabrodsk/proof/blob/main/server/judge.ts): `server/judge.ts`

### Persistent analysis

- [Backend API](https://github.com/zabrodsk/proof/blob/main/server/backend/router.ts): `server/backend/router.ts`
- [Run management](https://github.com/zabrodsk/proof/blob/main/server/backend/service.ts): `server/backend/service.ts`
- [Analysis engine](https://github.com/zabrodsk/proof/blob/main/server/backend/engine.ts): `server/backend/engine.ts`
- [Source library](https://github.com/zabrodsk/proof/blob/main/server/backend/library.ts): `server/backend/library.ts`
- [Job worker](https://github.com/zabrodsk/proof/blob/main/server/worker.ts): `server/worker.ts`
- [PostgreSQL](https://github.com/zabrodsk/proof/blob/main/server/backend/db.ts): `server/backend/db.ts`
- [Private file storage](https://github.com/zabrodsk/proof/blob/main/server/backend/storage.ts): `server/backend/storage.ts`

### Research and citations

- [Source discovery](https://github.com/zabrodsk/proof/blob/main/server/discovery.ts): `server/discovery.ts`
- [Scholarly source checks](https://github.com/zabrodsk/proof/blob/main/server/scholarly.ts): `server/scholarly.ts`
- [MLA citations](https://github.com/zabrodsk/proof/blob/main/shared/mla.ts): `shared/mla.ts`

### Connected services

- [Integration service](https://github.com/zabrodsk/proof/blob/main/server/integrations/service.ts): `server/integrations/service.ts`
- [MCP connection](https://github.com/zabrodsk/proof/blob/main/server/integrations/mcp.ts): `server/integrations/mcp.ts`

### Landing and signup

- [Landing page](https://github.com/zabrodsk/proof/blob/main/site/src/Landing.tsx): `site/src/Landing.tsx`
- [Waitlist service](https://github.com/zabrodsk/proof/blob/main/site/worker/index.ts): `site/worker/index.ts`
- [Waitlist database](https://github.com/zabrodsk/proof/blob/main/site/db/waitlist.ts): `site/db/waitlist.ts`

### Other components

- **Student**

## Connections

- Student → App entry: opens app
- App entry → Studio session: routes to (evidence: `src/main.tsx`)
- App entry → Class workspace: routes to (evidence: `src/main.tsx`)
- App entry → Integration workspace: routes to (evidence: `src/main.tsx`)
- Studio session → Studio workspace: renders (evidence: `src/StudioSession.tsx`)
- Studio session → Studio API client: uses (evidence: `src/StudioSession.tsx`)
- Studio API client → Backend API: calls API
- Class workspace → Class review jobs: submits reviews
- Class review jobs → Document parsing: parses documents (evidence: `server/classroom.ts`)
- Class review jobs → Claim assessment: assesses claims (evidence: `server/classroom.ts`)
- Class workspace → MLA citations: formats class citations
- Backend API → Source library: creates assets (evidence: `server/backend/router.ts`)
- Backend API → Run management: manages runs (evidence: `server/backend/router.ts`)
- Run management → PostgreSQL: stores run (evidence: `server/backend/service.ts`)
- Run management → Job worker: enqueues run (evidence: `server/backend/service.ts`)
- Job worker → Analysis engine: processes jobs (evidence: `server/worker.ts`)
- Analysis engine → Source library: retrieves evidence (evidence: `server/backend/engine.ts`)
- Analysis engine → PostgreSQL: stores findings (evidence: `server/backend/engine.ts`)
- Source library → Private file storage: persists files (evidence: `server/backend/library.ts`)
- Student → Source discovery: finds sources
- Student → Scholarly source checks: checks scholarship
- Student → MLA citations: generates citations
- Integration workspace → Integration service: uses integrations
- Integration service → MCP connection: supports MCP
- Student → Landing page: visits site
- Landing page → Waitlist service: submits signup
- Waitlist service → Waitlist database: stores signup (evidence: `site/worker/index.ts`)