# mrmps/classifier-dev architecture

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

- Interactive diagram: https://gitdiagram.com/mrmps/classifier-dev
- Repository: https://github.com/mrmps/classifier-dev

## Overview

classifier.dev is a hosted zero-shot text-classification service with a browser-facing account product. The main workflow accepts text and labels over HTTP, validates and budgets the request, classifies through Jev (with an LLM fallback), and returns labels with calibrated confidence. Its wider product includes account management, billing, usage analytics, agent interfaces, public documentation, and a separate agent-feedback protocol. The README documents several capabilities whose internals are not sampled; their paths and links are included only where supported by the tree and documentation.

Main entry points: [`src/server.ts`](https://github.com/mrmps/classifier-dev/blob/main/src/server.ts) (Worker entry), [`src/index.ts`](https://github.com/mrmps/classifier-dev/blob/main/src/index.ts) (Request router), [`src/jev.ts`](https://github.com/mrmps/classifier-dev/blob/main/src/jev.ts) (Jev classifier), [`src/feedback.ts`](https://github.com/mrmps/classifier-dev/blob/main/src/feedback.ts) (Feedback protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_classification["Classification API"]
  node_worker["Worker entry<br/>[server.ts]"]
  node_classify["Request router<br/>[index.ts]"]
  node_query["GET parsing<br/>[query.ts]"]
  node_spend["Spending admission<br/>[index.ts]"]
  node_jev["Jev classifier<br/>[jev.ts]"]
  node_llm["LLM fallback<br/>[index.ts]"]
  node_budget[("Free budget state<br/>[free-budget.ts]")]
end

subgraph group_accounts["Accounts and billing"]
  node_webapp["Account application<br/>[app.tsx]"]
  node_accountapi["Account API<br/>[account-api.ts]"]
  node_accountlogic["Account services<br/>[agents.ts]"]
  node_database[("Account database<br/>[db.ts]")]
  node_billing["Billing integration<br/>[billing.ts]"]
end

subgraph group_telemetry["Usage and operations"]
  node_analytics["Usage analytics<br/>[query.ts]"]
  node_reports["Digest and alerts<br/>[report.ts]"]
end

subgraph group_agents["Agent interfaces"]
  node_agentapi["MCP and skills<br/>[mcp.ts]"]
end

subgraph group_feedback["Agent feedback"]
  node_feedbackapi["Feedback protocol<br/>[feedback.ts]"]
  node_feedbackhttp["Feedback routes<br/>[dispatch.ts]"]
  node_feedbackkv[("Feedback records<br/>[feedback.ts]")]
end

subgraph group_public["Public site"]
  node_docs["Docs and homepage<br/>[docs.ts]"]
  node_home["Browser rendering<br/>[home.ts]"]
  node_cli["classify CLI<br/>[classify.js]"]
end

node_caller(("API caller"))
node_typesafe{{"TypeSafe service"}}
node_gateway{{"AI Gateway"}}
node_openrouter{{"OpenRouter"}}
node_autumn{{"Autumn billing"}}
node_analyticsengine[("Analytics Engine")]
node_email{{"Email delivery"}}

node_caller -->|"sends request"| node_worker
node_worker -->|"dispatches request"| node_classify
node_classify -->|"parses GET"| node_query
node_classify -->|"admits request"| node_spend
node_spend -->|"reserves and settles"| node_budget
node_classify -->|"classifies inputs"| node_jev
node_jev -->|"requests probabilities"| node_typesafe
node_jev -.->|"tries first"| node_gateway
node_classify -.->|"falls back"| node_llm
node_llm -->|"requests completion"| node_openrouter
node_classify -->|"returns classification"| node_caller
node_worker -->|"dispatches account requests"| node_accountapi
node_worker -->|"streams app requests"| node_webapp
node_webapp -->|"invokes account actions"| node_accountlogic
node_accountapi -->|"handles account operations"| node_accountlogic
node_accountlogic -->|"reads and writes"| node_database
node_worker -->|"synchronizes billing"| node_billing
node_billing -->|"syncs customer state"| node_autumn
node_worker -->|"serves account analytics"| node_analytics
node_analytics -->|"queries"| node_analyticsengine
node_reports -->|"queries digest data"| node_analyticsengine
node_reports -->|"sends digest and alerts"| node_email
node_caller -->|"uses agent endpoints"| node_agentapi
node_worker -->|"routes feedback requests"| node_feedbackhttp
node_feedbackhttp -->|"dispatches feedback"| node_feedbackapi
node_feedbackapi -->|"stores reports"| node_feedbackkv
node_feedbackapi -->|"emails accepted reports"| node_email
node_caller -->|"requests documentation"| node_docs
node_docs -->|"renders for browsers"| node_home
node_cli -->|"submits API request"| node_caller

click node_worker "https://github.com/mrmps/classifier-dev/blob/main/src/server.ts"
click node_classify "https://github.com/mrmps/classifier-dev/blob/main/src/index.ts"
click node_query "https://github.com/mrmps/classifier-dev/blob/main/src/query.ts"
click node_spend "https://github.com/mrmps/classifier-dev/blob/main/src/spending/index.ts"
click node_jev "https://github.com/mrmps/classifier-dev/blob/main/src/jev.ts"
click node_llm "https://github.com/mrmps/classifier-dev/blob/main/src/index.ts"
click node_budget "https://github.com/mrmps/classifier-dev/blob/main/src/spending/free-budget.ts"
click node_webapp "https://github.com/mrmps/classifier-dev/blob/main/src/routes/app.tsx"
click node_accountapi "https://github.com/mrmps/classifier-dev/blob/main/src/http/account-api.ts"
click node_accountlogic "https://github.com/mrmps/classifier-dev/blob/main/src/server/agents.ts"
click node_database "https://github.com/mrmps/classifier-dev/blob/main/src/server/db.ts"
click node_billing "https://github.com/mrmps/classifier-dev/blob/main/src/server/billing.ts"
click node_analytics "https://github.com/mrmps/classifier-dev/blob/main/src/server/analytics/query.ts"
click node_reports "https://github.com/mrmps/classifier-dev/blob/main/src/report.ts"
click node_agentapi "https://github.com/mrmps/classifier-dev/blob/main/src/http/mcp.ts"
click node_feedbackapi "https://github.com/mrmps/classifier-dev/blob/main/src/feedback.ts"
click node_feedbackhttp "https://github.com/mrmps/classifier-dev/blob/main/src/http/dispatch.ts"
click node_feedbackkv "https://github.com/mrmps/classifier-dev/blob/main/src/feedback.ts"
click node_docs "https://github.com/mrmps/classifier-dev/blob/main/src/docs.ts"
click node_home "https://github.com/mrmps/classifier-dev/blob/main/src/home.ts"
click node_cli "https://github.com/mrmps/classifier-dev/blob/main/cli/classify.js"

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_worker,node_classify,node_query,node_spend,node_jev,node_llm,node_budget toneBlue
class node_webapp,node_accountapi,node_accountlogic,node_database,node_billing,node_analyticsengine toneAmber
class node_analytics,node_reports,node_caller,node_openrouter toneMint
class node_agentapi toneRose
class node_feedbackapi,node_feedbackhttp,node_feedbackkv,node_typesafe,node_gateway,node_autumn,node_email toneIndigo
class node_docs,node_home,node_cli toneTeal
```

## Components

### Classification API

- [Worker entry](https://github.com/mrmps/classifier-dev/blob/main/src/server.ts): `src/server.ts`
- [Request router](https://github.com/mrmps/classifier-dev/blob/main/src/index.ts): `src/index.ts`
- [GET parsing](https://github.com/mrmps/classifier-dev/blob/main/src/query.ts): `src/query.ts`
- [Spending admission](https://github.com/mrmps/classifier-dev/blob/main/src/spending/index.ts): `src/spending/index.ts`
- [Jev classifier](https://github.com/mrmps/classifier-dev/blob/main/src/jev.ts): `src/jev.ts`
- [LLM fallback](https://github.com/mrmps/classifier-dev/blob/main/src/index.ts): `src/index.ts`
- [Free budget state](https://github.com/mrmps/classifier-dev/blob/main/src/spending/free-budget.ts): `src/spending/free-budget.ts`

### Accounts and billing

- [Account application](https://github.com/mrmps/classifier-dev/blob/main/src/routes/app.tsx): `src/routes/app.tsx`
- [Account API](https://github.com/mrmps/classifier-dev/blob/main/src/http/account-api.ts): `src/http/account-api.ts`
- [Account services](https://github.com/mrmps/classifier-dev/blob/main/src/server/agents.ts): `src/server/agents.ts`
- [Account database](https://github.com/mrmps/classifier-dev/blob/main/src/server/db.ts): `src/server/db.ts`
- [Billing integration](https://github.com/mrmps/classifier-dev/blob/main/src/server/billing.ts): `src/server/billing.ts`

### Usage and operations

- [Usage analytics](https://github.com/mrmps/classifier-dev/blob/main/src/server/analytics/query.ts): `src/server/analytics/query.ts`
- [Digest and alerts](https://github.com/mrmps/classifier-dev/blob/main/src/report.ts): `src/report.ts`

### Agent interfaces

- [MCP and skills](https://github.com/mrmps/classifier-dev/blob/main/src/http/mcp.ts): `src/http/mcp.ts`

### Agent feedback

- [Feedback protocol](https://github.com/mrmps/classifier-dev/blob/main/src/feedback.ts): `src/feedback.ts`
- [Feedback routes](https://github.com/mrmps/classifier-dev/blob/main/src/http/dispatch.ts): `src/http/dispatch.ts`
- [Feedback records](https://github.com/mrmps/classifier-dev/blob/main/src/feedback.ts): `src/feedback.ts`

### Public site

- [Docs and homepage](https://github.com/mrmps/classifier-dev/blob/main/src/docs.ts): `src/docs.ts`
- [Browser rendering](https://github.com/mrmps/classifier-dev/blob/main/src/home.ts): `src/home.ts`
- [classify CLI](https://github.com/mrmps/classifier-dev/blob/main/cli/classify.js): `cli/classify.js`

### Other components

- **API caller**
- **TypeSafe service**
- **AI Gateway**
- **OpenRouter**
- **Autumn billing**
- **Analytics Engine**
- **Email delivery**

## Connections

- API caller → Worker entry: sends request
- Worker entry → Request router: dispatches request
- Request router → GET parsing: parses GET
- Request router → Spending admission: admits request
- Spending admission → Free budget state: reserves and settles
- Request router → Jev classifier: classifies inputs
- Jev classifier → TypeSafe service: requests probabilities
- Jev classifier → AI Gateway: tries first
- Request router → LLM fallback: falls back
- LLM fallback → OpenRouter: requests completion
- Request router → API caller: returns classification
- Worker entry → Account API: dispatches account requests
- Worker entry → Account application: streams app requests
- Account application → Account services: invokes account actions
- Account API → Account services: handles account operations
- Account services → Account database: reads and writes
- Worker entry → Billing integration: synchronizes billing
- Billing integration → Autumn billing: syncs customer state
- Worker entry → Usage analytics: serves account analytics
- Usage analytics → Analytics Engine: queries
- Digest and alerts → Analytics Engine: queries digest data
- Digest and alerts → Email delivery: sends digest and alerts
- API caller → MCP and skills: uses agent endpoints
- Worker entry → Feedback routes: routes feedback requests
- Feedback routes → Feedback protocol: dispatches feedback
- Feedback protocol → Feedback records: stores reports
- Feedback protocol → Email delivery: emails accepted reports
- API caller → Docs and homepage: requests documentation
- Docs and homepage → Browser rendering: renders for browsers
- classify CLI → API caller: submits API request