# kanukuntla-r/career-card-capture architecture

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

- Interactive diagram: https://gitdiagram.com/kanukuntla-r/career-card-capture
- Repository: https://github.com/kanukuntla-r/career-card-capture

## Overview

Career Card Capture is a browser-based workflow for turning handwritten career-service cards into reviewed records: an operator captures an image, the API normalizes it and requests OCR, the operator edits and approves the draft, and PostgreSQL stores the authoritative record. Approved data can sync to Google Sheets or export as CSV. The README documents the end-to-end architecture; source excerpts support card processing, session persistence, OCR, and sheet synchronization. Other route internals and some UI wiring were not sampled, so those links are shown only where documented.

Main entry points: [`apps/api/app/api/routes/cards.py`](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/cards.py) (Card workflow), [`apps/web/components/career-card-app.tsx`](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/career-card-app.tsx) (Operator app), [`apps/web/lib/api.ts`](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/lib/api.ts) (API client), [`apps/api/app/api/routes/sessions.py`](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/sessions.py) (Session routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Capture and review"]
  node_webapp["Operator app"]
  node_camera["Camera capture<br/>[camera-panel.tsx]"]
  node_review["Card review<br/>[card-history.tsx]"]
  node_eventform["Event setup<br/>[new-event-form.tsx]"]
  node_sheetsui["Sync controls"]
  node_webapi["API client<br/>[api.ts]"]
end

subgraph group_api["API workflows"]
  node_events["Event routes<br/>[events.py]"]
  node_sessions["Session routes<br/>[sessions.py]"]
  node_cards["Card workflow<br/>[cards.py]"]
  node_syncroutes["Sync routes<br/>[sync.py]"]
end

subgraph group_processing["Image and OCR"]
  node_vision["Image normalization<br/>[vision.py]"]
  node_ocrfactory["OCR provider selection<br/>[factory.py]"]
  node_hunyuan["Hunyuan OCR<br/>[hunyuan.py]"]
  node_mock["Mock OCR<br/>[mock.py]"]
  node_classification["Response classification<br/>[classification.py]"]
end

subgraph group_data["Records and persistence"]
  node_models["Domain records<br/>[entities.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
end

subgraph group_integrations["Export and sync"]
  node_sheetsync["Sheets sync service<br/>[sync.py]"]
  node_gateway["Google Sheets gateway<br/>[google.py]"]
  node_csv["CSV export<br/>[cards.py]"]
end

node_operator(("Operator"))
node_ocrservice["Local OCR server"]
node_googlesheets[("Google Sheets")]

node_operator -->|"uses"| node_webapp
node_webapp -->|"captures with"| node_camera
node_webapp -.->|"sets up events"| node_eventform
node_webapp -->|"reviews drafts"| node_review
node_webapp -.->|"manages sync"| node_sheetsui
node_webapp -.->|"requests data"| node_webapi
node_webapi -->|"calls API"| node_events
node_webapi -->|"calls API"| node_sessions
node_webapi -->|"calls API"| node_cards
node_webapi -->|"calls API"| node_syncroutes
node_cards -->|"normalizes image"| node_vision
node_cards -->|"requests OCR"| node_ocrfactory
node_ocrfactory -->|"selects provider"| node_hunyuan
node_ocrfactory -->|"selects provider"| node_mock
node_hunyuan -->|"classifies text"| node_classification
node_mock -->|"classifies text"| node_classification
node_hunyuan -->|"sends image"| node_ocrservice
node_cards -->|"reads and updates"| node_models
node_sessions -->|"reads and updates"| node_models
node_cards -->|"persists records"| node_database
node_sessions -->|"queries and commits"| node_database
node_events -.->|"persists events"| node_database
node_cards -->|"queues approved cards"| node_sheetsync
node_syncroutes -->|"runs sync"| node_sheetsync
node_sheetsync -->|"updates rows"| node_gateway
node_gateway -.->|"reads and writes"| node_googlesheets
node_cards -->|"exports records"| node_csv

click node_webapp "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/career-card-app.tsx"
click node_camera "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/camera-panel.tsx"
click node_review "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/card-history.tsx"
click node_eventform "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/new-event-form.tsx"
click node_sheetsui "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/google-sheets-panel.tsx"
click node_webapi "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/lib/api.ts"
click node_events "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/events.py"
click node_sessions "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/sessions.py"
click node_cards "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/cards.py"
click node_syncroutes "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/sync.py"
click node_vision "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/vision.py"
click node_ocrfactory "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/ocr/factory.py"
click node_hunyuan "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/ocr/hunyuan.py"
click node_mock "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/ocr/mock.py"
click node_classification "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/ocr/classification.py"
click node_models "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/models/entities.py"
click node_database "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/core/database.py"
click node_sheetsync "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/sheets/sync.py"
click node_gateway "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/sheets/google.py"
click node_csv "https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/cards.py"

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_camera,node_review,node_eventform,node_sheetsui,node_webapi toneBlue
class node_events,node_sessions,node_cards,node_syncroutes,node_googlesheets toneAmber
class node_vision,node_ocrfactory,node_hunyuan,node_mock,node_classification,node_ocrservice toneMint
class node_models,node_database toneRose
class node_sheetsync,node_gateway,node_csv,node_operator toneIndigo
```

## Components

### Capture and review

- [Operator app](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/career-card-app.tsx): `apps/web/components/career-card-app.tsx`
- [Camera capture](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/camera-panel.tsx): `apps/web/components/camera-panel.tsx`
- [Card review](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/card-history.tsx): `apps/web/components/card-history.tsx`
- [Event setup](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/new-event-form.tsx): `apps/web/components/new-event-form.tsx`
- [Sync controls](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/components/google-sheets-panel.tsx): `apps/web/components/google-sheets-panel.tsx`
- [API client](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`

### API workflows

- [Event routes](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/events.py): `apps/api/app/api/routes/events.py`
- [Session routes](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/sessions.py): `apps/api/app/api/routes/sessions.py`
- [Card workflow](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/cards.py): `apps/api/app/api/routes/cards.py`
- [Sync routes](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/sync.py): `apps/api/app/api/routes/sync.py`

### Image and OCR

- [Image normalization](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/vision.py): `apps/api/app/services/vision.py`
- [OCR provider selection](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/ocr/factory.py): `apps/api/app/services/ocr/factory.py`
- [Hunyuan OCR](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/ocr/hunyuan.py): `apps/api/app/services/ocr/hunyuan.py`
- [Mock OCR](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/ocr/mock.py): `apps/api/app/services/ocr/mock.py`
- [Response classification](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/ocr/classification.py): `apps/api/app/services/ocr/classification.py`

### Records and persistence

- [Domain records](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/models/entities.py): `apps/api/app/models/entities.py`
- [PostgreSQL](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/core/database.py): `apps/api/app/core/database.py`

### Export and sync

- [Sheets sync service](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/sheets/sync.py): `apps/api/app/services/sheets/sync.py`
- [Google Sheets gateway](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/services/sheets/google.py): `apps/api/app/services/sheets/google.py`
- [CSV export](https://github.com/kanukuntla-r/career-card-capture/blob/main/apps/api/app/api/routes/cards.py): `apps/api/app/api/routes/cards.py`

### Other components

- **Operator**
- **Local OCR server**
- **Google Sheets**

## Connections

- Operator → Operator app: uses (evidence: `README.md`)
- Operator app → Camera capture: captures with (evidence: `README.md`)
- Operator app → Event setup: sets up events
- Operator app → Card review: reviews drafts (evidence: `README.md`)
- Operator app → Sync controls: manages sync
- Operator app → API client: requests data
- API client → Event routes: calls API (evidence: `README.md`)
- API client → Session routes: calls API (evidence: `README.md`)
- API client → Card workflow: calls API (evidence: `README.md`)
- API client → Sync routes: calls API (evidence: `README.md`)
- Card workflow → Image normalization: normalizes image (evidence: `apps/api/app/api/routes/cards.py`)
- Card workflow → OCR provider selection: requests OCR (evidence: `apps/api/app/api/routes/cards.py`)
- OCR provider selection → Hunyuan OCR: selects provider (evidence: `apps/api/app/services/ocr/factory.py`)
- OCR provider selection → Mock OCR: selects provider (evidence: `apps/api/app/services/ocr/factory.py`)
- Hunyuan OCR → Response classification: classifies text (evidence: `apps/api/app/services/ocr/hunyuan.py`)
- Mock OCR → Response classification: classifies text (evidence: `apps/api/app/services/ocr/mock.py`)
- Hunyuan OCR → Local OCR server: sends image (evidence: `apps/api/app/services/ocr/hunyuan.py`)
- Card workflow → Domain records: reads and updates (evidence: `apps/api/app/api/routes/cards.py`)
- Session routes → Domain records: reads and updates (evidence: `apps/api/app/api/routes/sessions.py`)
- Card workflow → PostgreSQL: persists records (evidence: `README.md`)
- Session routes → PostgreSQL: queries and commits (evidence: `apps/api/app/api/routes/sessions.py`)
- Event routes → PostgreSQL: persists events
- Card workflow → Sheets sync service: queues approved cards (evidence: `apps/api/app/api/routes/cards.py`)
- Sync routes → Sheets sync service: runs sync (evidence: `apps/api/app/api/routes/sync.py`)
- Sheets sync service → Google Sheets gateway: updates rows (evidence: `apps/api/app/services/sheets/sync.py`)
- Google Sheets gateway → Google Sheets: reads and writes (evidence: `README.md`)
- Card workflow → CSV export: exports records (evidence: `README.md`)
