# bcsdlab/bcsd_united architecture

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

- Interactive diagram: https://gitdiagram.com/bcsdlab/bcsd_united
- Repository: https://github.com/bcsdlab/bcsd_united

## Overview

BCSD United is a Cloudflare Workers monorepo centered on the KOIN web app, with a Slack operations bot, a legacy API Worker, and error-autofix automation. The main user-facing flow is browser to SSR web app to the Java KOIN API. The bot’s spreadsheet workflows convert bus, cooperative-shop, and lecture data into reviewable submissions; error automation handles webhook/queue-driven diagnosis and pull-request fixes. Several links come from README statements or indexed imports; unsampled runtime wiring is omitted rather than inferred.

Main entry points: [`apps/api/src/app.ts`](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/api/src/app.ts) (API Worker), [`apps/error-automation/src/index.ts`](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/index.ts) (Error webhook), [`apps/error-automation/src/queue.ts`](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/queue.ts) (Autofix queue), [`apps/b-bot/src/services/coop/pipeline.ts`](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/coop/pipeline.ts) (Co-op timetable review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["KOIN Web"]
  node_webapp["Web app and SSR<br/>[client.tsx]"]
end

subgraph group_api["Legacy API"]
  node_apiworker["API Worker<br/>[app.ts]"]
  node_identity["Identity"]
  node_commerce["Commerce"]
  node_academic["Academic"]
  node_community["Community"]
  node_campus["Campus services"]
  node_db[("D1 database<br/>[client.ts]")]
end

subgraph group_bot["Slack Bot"]
  node_botworker["Bot Worker<br/>[worker.ts]"]
  node_bus["Bus timetable review<br/>[pipeline.ts]"]
  node_coop["Co-op timetable review<br/>[pipeline.ts]"]
  node_coopvision["Image extraction<br/>[vision.ts]"]
  node_coopconvert["Co-op conversion<br/>[convert.ts]"]
  node_lecture["Lecture review<br/>[pipeline.ts]"]
  node_dining["Dining delivery<br/>[worker.ts]"]
end

subgraph group_automation["Error Automation"]
  node_errorhook["Error webhook<br/>[index.ts]"]
  node_queue["Autofix queue<br/>[queue.ts]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.ts]"]
  node_model["Model review<br/>[model.ts]"]
  node_github["GitHub operations<br/>[github.ts]"]
  node_pullrequest["Pull request prep<br/>[pull-request.ts]"]
end

node_browser(("Web user"))
node_javaapi["Java API"]
node_slack(("Slack user"))
node_practor(("GitHub PR"))

node_browser -->|"uses"| node_webapp
node_webapp -->|"calls API"| node_javaapi
node_apiworker -->|"registers routes"| node_identity
node_apiworker -->|"registers routes"| node_commerce
node_apiworker -->|"registers routes"| node_academic
node_apiworker -->|"registers routes"| node_community
node_apiworker -->|"registers routes"| node_campus
node_slack -.->|"interacts"| node_botworker
node_bus --> node_coop
node_coop -->|"extracts image"| node_coopvision
node_coop -->|"converts timetable"| node_coopconvert
node_errorhook -->|"gathers evidence"| node_diagnostics
node_errorhook -->|"parses request"| node_model
node_errorhook -->|"uses GitHub"| node_github
node_errorhook -->|"inspects PR"| node_pullrequest
node_queue -->|"validates"| node_github
node_queue -->|"invokes model"| node_model
node_queue -->|"prepares PR"| node_pullrequest
node_github -.->|"publishes changes"| node_practor

click node_webapp "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/web/src/client.tsx"
click node_apiworker "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/api/src/app.ts"
click node_identity "https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains/identity"
click node_commerce "https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains/commerce"
click node_academic "https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains/academic"
click node_community "https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains/community"
click node_campus "https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains"
click node_db "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/api/src/db/client.ts"
click node_botworker "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/worker.ts"
click node_bus "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/bus/pipeline.ts"
click node_coop "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/coop/pipeline.ts"
click node_coopvision "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/coop/vision.ts"
click node_coopconvert "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/coop/convert.ts"
click node_lecture "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/lecture/pipeline.ts"
click node_dining "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/dining/worker.ts"
click node_errorhook "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/index.ts"
click node_queue "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/queue.ts"
click node_diagnostics "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/diagnostics.ts"
click node_model "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/model.ts"
click node_github "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/github.ts"
click node_pullrequest "https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/pull-request.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_webapp,node_browser,node_slack toneBlue
class node_apiworker,node_identity,node_commerce,node_academic,node_community,node_campus,node_db toneAmber
class node_botworker,node_bus,node_coop,node_coopvision,node_coopconvert,node_lecture,node_dining,node_javaapi toneMint
class node_errorhook,node_queue,node_diagnostics,node_model,node_github,node_pullrequest toneRose
class node_practor toneIndigo
```

## Components

### KOIN Web

- [Web app and SSR](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/web/src/client.tsx): `apps/web/src/client.tsx`

### Legacy API

- [API Worker](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Identity](https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains/identity): `apps/api/src/domains/identity`
- [Commerce](https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains/commerce): `apps/api/src/domains/commerce`
- [Academic](https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains/academic): `apps/api/src/domains/academic`
- [Community](https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains/community): `apps/api/src/domains/community`
- [Campus services](https://github.com/bcsdlab/bcsd_united/tree/develop/apps/api/src/domains): `apps/api/src/domains`
- [D1 database](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/api/src/db/client.ts): `apps/api/src/db/client.ts`

### Slack Bot

- [Bot Worker](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/worker.ts): `apps/b-bot/worker.ts`
- [Bus timetable review](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/bus/pipeline.ts): `apps/b-bot/src/services/bus/pipeline.ts`
- [Co-op timetable review](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/coop/pipeline.ts): `apps/b-bot/src/services/coop/pipeline.ts`
- [Image extraction](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/coop/vision.ts): `apps/b-bot/src/services/coop/vision.ts`
- [Co-op conversion](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/coop/convert.ts): `apps/b-bot/src/services/coop/convert.ts`
- [Lecture review](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/lecture/pipeline.ts): `apps/b-bot/src/services/lecture/pipeline.ts`
- [Dining delivery](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/b-bot/src/services/dining/worker.ts): `apps/b-bot/src/services/dining/worker.ts`

### Error Automation

- [Error webhook](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/index.ts): `apps/error-automation/src/index.ts`
- [Autofix queue](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/queue.ts): `apps/error-automation/src/queue.ts`
- [Diagnostics](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/diagnostics.ts): `apps/error-automation/src/diagnostics.ts`
- [Model review](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/model.ts): `apps/error-automation/src/model.ts`
- [GitHub operations](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/github.ts): `apps/error-automation/src/github.ts`
- [Pull request prep](https://github.com/bcsdlab/bcsd_united/blob/develop/apps/error-automation/src/pull-request.ts): `apps/error-automation/src/pull-request.ts`

### Other components

- **Web user**
- **Java API**
- **Slack user**
- **GitHub PR**

## Connections

- Web user → Web app and SSR: uses (evidence: `README.md`)
- Web app and SSR → Java API: calls API (evidence: `README.md`)
- API Worker → Identity: registers routes (evidence: `apps/api/src/app.ts`)
- API Worker → Commerce: registers routes (evidence: `apps/api/src/app.ts`)
- API Worker → Academic: registers routes (evidence: `apps/api/src/app.ts`)
- API Worker → Community: registers routes (evidence: `apps/api/src/app.ts`)
- API Worker → Campus services: registers routes (evidence: `apps/api/src/app.ts`)
- Slack user → Bot Worker: interacts
- Bus timetable review → Co-op timetable review
- Co-op timetable review → Image extraction: extracts image (evidence: `apps/b-bot/src/services/coop/pipeline.ts`)
- Co-op timetable review → Co-op conversion: converts timetable (evidence: `apps/b-bot/src/services/coop/pipeline.ts`)
- Error webhook → Diagnostics: gathers evidence (evidence: `apps/error-automation/src/index.ts`)
- Error webhook → Model review: parses request (evidence: `apps/error-automation/src/index.ts`)
- Error webhook → GitHub operations: uses GitHub (evidence: `apps/error-automation/src/index.ts`)
- Error webhook → Pull request prep: inspects PR (evidence: `apps/error-automation/src/index.ts`)
- Autofix queue → GitHub operations: validates (evidence: `apps/error-automation/src/queue.ts`)
- Autofix queue → Model review: invokes model (evidence: `apps/error-automation/src/queue.ts`)
- Autofix queue → Pull request prep: prepares PR (evidence: `apps/error-automation/src/queue.ts`)
- GitHub operations → GitHub PR: publishes changes