# ychine/tdks-overclock architecture

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

- Interactive diagram: https://gitdiagram.com/ychine/tdks-overclock
- Repository: https://github.com/ychine/tdks-overclock

## Overview

Linaw helps workers understand employment contracts and quitclaims: consent, upload, OCR, human verification, plain-language interpretation, and referrals. The React app coordinates the workflow and keeps working state in the browser tab; confirmed fields feed chat, while payroll calculations are deterministic. Separate capabilities include contract comparison and a questionnaire for users without a contract. Backend routes proxy OCR and chat to Lumen. The README documents the main workflow and guardrails; some frontend and service connections are not shown in sampled source, so those links use README evidence or are omitted.

Main entry points: [`frontend/src/pages/Summary.jsx`](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Summary.jsx) (Contract summary), [`backend/src/routes/chat.js`](https://github.com/ychine/tdks-overclock/blob/main/backend/src/routes/chat.js) (Chat routes), [`backend/src/routes/ocr.js`](https://github.com/ychine/tdks-overclock/blob/main/backend/src/routes/ocr.js) (OCR routes), [`frontend/src/App.jsx`](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/App.jsx) (App routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Contract workflow"]
  node_app["App routing<br/>[App.jsx]"]
  node_consent["Consent<br/>[Consent.jsx]"]
  node_upload["Document upload<br/>[Upload.jsx]"]
  node_ocrapi["OCR API client<br/>[ocr.js]"]
  node_extract["Field extraction<br/>[extract.js]"]
  node_reading["OCR reading<br/>[Reading.jsx]"]
  node_review["Field verification<br/>[Review.jsx]"]
end

subgraph group_interpretation["Understanding tools"]
  node_summary["Contract summary<br/>[Summary.jsx]"]
  node_glossary["Legal glossary<br/>[glossary.js]"]
  node_salary["Salary breakdown<br/>[Salary.jsx]"]
  node_payroll["Payroll calculator<br/>[payroll.js]"]
  node_chatui["Ask Linaw<br/>[Chat.jsx]"]
  node_chatapi["Chat API client<br/>[chat.js]"]
  node_compare["Contract comparison<br/>[Compare.jsx]"]
  node_questions["No-contract questions<br/>[Questions.jsx]"]
  node_help["Agency referrals<br/>[Help.jsx]"]
  node_agencies["Agency directory<br/>[agencies.js]"]
end

subgraph group_server["Backend services"]
  node_ocrroute["OCR routes<br/>[ocr.js]"]
  node_lumenocr["Lumen OCR<br/>[lumenOcr.js]"]
  node_chatroute["Chat routes<br/>[chat.js]"]
  node_chatmsg["Chat message builder<br/>[chatMessage.js]"]
  node_legalrefs["Verified law selection<br/>[legalRefs.js]"]
  node_lumenchat["Lumen AI chat<br/>[lumenChat.js]"]
  node_express["Express API<br/>[server.js]"]
end

subgraph group_shared["Shared frontend"]
  node_i18n["Translations<br/>[I18nProvider.jsx]"]
end

node_worker(("Worker"))
node_lumen["Lumen service"]

node_worker -->|"uses"| node_app
node_app -->|"routes to"| node_consent
node_consent -->|"agrees then uploads"| node_upload
node_upload -->|"submits document"| node_ocrapi
node_ocrapi -->|"requests OCR"| node_ocrroute
node_express -->|"mounts"| node_ocrroute
node_ocrroute -->|"calls"| node_lumenocr
node_lumenocr -->|"sends document"| node_lumen
node_lumenocr -.->|"returns OCR pages"| node_ocrroute
node_ocrapi -.->|"provides OCR result"| node_reading
node_reading -->|"extracts fields"| node_extract
node_extract -->|"presents fields"| node_review
node_worker -->|"checks and corrects"| node_review
node_review -->|"confirms fields for"| node_summary
node_summary -.->|"explains terms"| node_glossary
node_summary -->|"offers breakdown"| node_salary
node_salary -->|"calculates pay"| node_payroll
node_summary -->|"offers questions"| node_chatui
node_chatui -.->|"sends question"| node_chatapi
node_chatapi -.->|"requests answer"| node_chatroute
node_express -->|"mounts"| node_chatroute
node_chatroute -->|"builds message"| node_chatmsg
node_chatroute -->|"selects law"| node_legalrefs
node_chatroute -->|"sends message"| node_lumenchat
node_lumenchat -->|"asks AI"| node_lumen
node_worker -->|"compares contracts"| node_compare
node_worker -->|"answers questions"| node_questions
node_summary -->|"offers referrals"| node_help
node_help -.->|"shows agencies"| node_agencies
node_app -->|"provides translations"| node_i18n

click node_app "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/App.jsx"
click node_consent "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Consent.jsx"
click node_upload "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Upload.jsx"
click node_ocrapi "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/api/ocr.js"
click node_ocrroute "https://github.com/ychine/tdks-overclock/blob/main/backend/src/routes/ocr.js"
click node_lumenocr "https://github.com/ychine/tdks-overclock/blob/main/backend/src/services/lumenOcr.js"
click node_extract "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/lib/extract.js"
click node_reading "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Reading.jsx"
click node_review "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Review.jsx"
click node_summary "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Summary.jsx"
click node_glossary "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/lib/glossary.js"
click node_salary "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Salary.jsx"
click node_payroll "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/lib/payroll.js"
click node_chatui "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Chat.jsx"
click node_chatapi "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/api/chat.js"
click node_chatroute "https://github.com/ychine/tdks-overclock/blob/main/backend/src/routes/chat.js"
click node_chatmsg "https://github.com/ychine/tdks-overclock/blob/main/backend/src/services/chatMessage.js"
click node_legalrefs "https://github.com/ychine/tdks-overclock/blob/main/backend/src/services/legalRefs.js"
click node_lumenchat "https://github.com/ychine/tdks-overclock/blob/main/backend/src/services/lumenChat.js"
click node_compare "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Compare.jsx"
click node_questions "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Questions.jsx"
click node_help "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Help.jsx"
click node_agencies "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/lib/agencies.js"
click node_i18n "https://github.com/ychine/tdks-overclock/blob/main/frontend/src/i18n/I18nProvider.jsx"
click node_express "https://github.com/ychine/tdks-overclock/blob/main/backend/server.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_app,node_consent,node_upload,node_ocrapi,node_extract,node_reading,node_review toneBlue
class node_summary,node_glossary,node_salary,node_payroll,node_chatui,node_chatapi,node_compare,node_questions,node_help,node_agencies toneAmber
class node_ocrroute,node_lumenocr,node_chatroute,node_chatmsg,node_legalrefs,node_lumenchat,node_express toneMint
class node_i18n,node_worker toneRose
class node_lumen toneIndigo
```

## Components

### Contract workflow

- [App routing](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Consent](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Consent.jsx): `frontend/src/pages/Consent.jsx`
- [Document upload](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Upload.jsx): `frontend/src/pages/Upload.jsx`
- [OCR API client](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/api/ocr.js): `frontend/src/api/ocr.js`
- [Field extraction](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/lib/extract.js): `frontend/src/lib/extract.js`
- [OCR reading](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Reading.jsx): `frontend/src/pages/Reading.jsx`
- [Field verification](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Review.jsx): `frontend/src/pages/Review.jsx`

### Understanding tools

- [Contract summary](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Summary.jsx): `frontend/src/pages/Summary.jsx`
- [Legal glossary](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/lib/glossary.js): `frontend/src/lib/glossary.js`
- [Salary breakdown](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Salary.jsx): `frontend/src/pages/Salary.jsx`
- [Payroll calculator](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/lib/payroll.js): `frontend/src/lib/payroll.js`
- [Ask Linaw](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Chat.jsx): `frontend/src/pages/Chat.jsx`
- [Chat API client](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/api/chat.js): `frontend/src/api/chat.js`
- [Contract comparison](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Compare.jsx): `frontend/src/pages/Compare.jsx`
- [No-contract questions](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Questions.jsx): `frontend/src/pages/Questions.jsx`
- [Agency referrals](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/pages/Help.jsx): `frontend/src/pages/Help.jsx`
- [Agency directory](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/lib/agencies.js): `frontend/src/lib/agencies.js`

### Backend services

- [OCR routes](https://github.com/ychine/tdks-overclock/blob/main/backend/src/routes/ocr.js): `backend/src/routes/ocr.js`
- [Lumen OCR](https://github.com/ychine/tdks-overclock/blob/main/backend/src/services/lumenOcr.js): `backend/src/services/lumenOcr.js`
- [Chat routes](https://github.com/ychine/tdks-overclock/blob/main/backend/src/routes/chat.js): `backend/src/routes/chat.js`
- [Chat message builder](https://github.com/ychine/tdks-overclock/blob/main/backend/src/services/chatMessage.js): `backend/src/services/chatMessage.js`
- [Verified law selection](https://github.com/ychine/tdks-overclock/blob/main/backend/src/services/legalRefs.js): `backend/src/services/legalRefs.js`
- [Lumen AI chat](https://github.com/ychine/tdks-overclock/blob/main/backend/src/services/lumenChat.js): `backend/src/services/lumenChat.js`
- [Express API](https://github.com/ychine/tdks-overclock/blob/main/backend/server.js): `backend/server.js`

### Shared frontend

- [Translations](https://github.com/ychine/tdks-overclock/blob/main/frontend/src/i18n/I18nProvider.jsx): `frontend/src/i18n/I18nProvider.jsx`

### Other components

- **Worker**
- **Lumen service**

## Connections

- Worker → App routing: uses
- App routing → Consent: routes to (evidence: `frontend/src/App.jsx`)
- Consent → Document upload: agrees then uploads
- Document upload → OCR API client: submits document
- OCR API client → OCR routes: requests OCR
- Express API → OCR routes: mounts (evidence: `backend/server.js`)
- OCR routes → Lumen OCR: calls (evidence: `backend/src/routes/ocr.js`)
- Lumen OCR → Lumen service: sends document
- Lumen OCR → OCR routes: returns OCR pages (evidence: `backend/src/routes/ocr.js`)
- OCR API client → OCR reading: provides OCR result
- OCR reading → Field extraction: extracts fields
- Field extraction → Field verification: presents fields (evidence: `frontend/src/pages/Review.jsx`)
- Worker → Field verification: checks and corrects
- Field verification → Contract summary: confirms fields for
- Contract summary → Legal glossary: explains terms
- Contract summary → Salary breakdown: offers breakdown
- Salary breakdown → Payroll calculator: calculates pay
- Contract summary → Ask Linaw: offers questions
- Ask Linaw → Chat API client: sends question
- Chat API client → Chat routes: requests answer
- Express API → Chat routes: mounts (evidence: `backend/server.js`)
- Chat routes → Chat message builder: builds message (evidence: `backend/src/routes/chat.js`)
- Chat routes → Verified law selection: selects law (evidence: `backend/src/routes/chat.js`)
- Chat routes → Lumen AI chat: sends message (evidence: `backend/src/routes/chat.js`)
- Lumen AI chat → Lumen service: asks AI
- Worker → Contract comparison: compares contracts
- Worker → No-contract questions: answers questions
- Contract summary → Agency referrals: offers referrals
- Agency referrals → Agency directory: shows agencies
- App routing → Translations: provides translations (evidence: `frontend/src/App.jsx`)
