# nitin3560/careeros architecture

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

- Interactive diagram: https://gitdiagram.com/nitin3560/careeros
- Repository: https://github.com/nitin3560/careeros

## Overview

CareerOS brings job discovery, candidate matching, and application management into one workflow: jobs are collected and normalized, stored, ranked against candidate profiles, and served through a web app and REST API. Resume parsing and per-job tailoring extend that workflow. The README documents the major boundaries and capabilities; source excerpts and the index support several implementation links, but unsampled route and worker wiring is not inferred beyond those references.

Main entry points: [`apps/api/app/main.py`](https://github.com/nitin3560/careeros/blob/main/apps/api/app/main.py) (REST API), [`apps/api/app/models.py`](https://github.com/nitin3560/careeros/blob/main/apps/api/app/models.py) (PostgreSQL records), [`apps/api/app/services/job_matching.py`](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/job_matching.py) (Job matching), [`apps/api/app/workers/ingestion.py`](https://github.com/nitin3560/careeros/blob/main/apps/api/app/workers/ingestion.py) (Ingestion worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Job collection"]
  node_source_adapters["Job source adapters"]
  node_source_discovery["Public source discovery<br/>[public_sources.py]"]
  node_job_persistence["Job normalization and persistence<br/>[persist.py]"]
  node_poller_fetch["Board fetching<br/>[fetcher.py]"]
  node_poller_normalize["Poller normalization<br/>[normalization.py]"]
  node_poller_repository["Poller writes and state<br/>[repository.py]"]
  node_poller_scheduler["Poller scheduling<br/>[scheduler.py]"]
end

subgraph group_backend["API and persistence"]
  node_api["REST API<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_database_session["Database sessions<br/>[database.py]"]
  node_job_store[("PostgreSQL records<br/>[models.py]")]
end

subgraph group_candidate["Candidate matching"]
  node_resume_parsing["Resume parsing<br/>[resume_parsing.py]"]
  node_job_matching["Job matching<br/>[job_matching.py]"]
  node_ai_client["AI provider client<br/>[ai_client.py]"]
  node_tailoring["Resume tailoring<br/>[tailoring.py]"]
  node_resume_export["Resume export<br/>[resume_export.py]"]
end

subgraph group_experience["Web experience"]
  node_web_app["CareerOS web app"]
  node_web_api["Web API client<br/>[api.ts]"]
end

subgraph group_async["Background processing"]
  node_background_jobs["Background job tracking<br/>[background_jobs.py]"]
  node_ingestion_worker["Ingestion worker<br/>[ingestion.py]"]
  node_matching_worker["Matching worker<br/>[matching.py]"]
  node_redis_queue["Redis queue"]
end

node_candidate_user(("Job seeker"))
node_company_sources(("Company job sources"))
node_llm_provider["LLM providers"]

node_candidate_user -->|"uses"| node_web_app
node_web_app -->|"requests data"| node_web_api
node_web_api -->|"calls REST"| node_api
node_api -->|"opens sessions"| node_database_session
node_api -->|"uses responses"| node_schemas
node_database_session -->|"queries records"| node_job_store
node_api -->|"uses password hashing"| node_auth
node_company_sources -->|"provides job feeds"| node_source_discovery
node_source_discovery -->|"dispatches fetches"| node_source_adapters
node_source_adapters -->|"saves normalized jobs"| node_job_persistence
node_job_persistence -->|"writes jobs"| node_job_store
node_company_sources -->|"supplies board data"| node_poller_fetch
node_poller_fetch -.->|"normalizes fetched jobs"| node_poller_normalize
node_poller_normalize -.->|"provides normalized jobs"| node_poller_repository
node_poller_repository -->|"writes job records"| node_job_store
node_poller_scheduler -.->|"schedules polling"| node_poller_fetch
node_api -->|"supports resume parsing"| node_resume_parsing
node_api -->|"serves ranked matches"| node_job_matching
node_job_matching -->|"filters job corpus"| node_job_store
node_job_matching -->|"requests AI ranking"| node_ai_client
node_ai_client -->|"sends completions"| node_llm_provider
node_api -->|"supports per-job tailoring"| node_tailoring
node_api -->|"exports resume versions"| node_resume_export
node_ingestion_worker -->|"updates job status"| node_background_jobs
node_ingestion_worker -->|"ingests jobs"| node_job_store
node_matching_worker -->|"updates job status"| node_background_jobs
node_matching_worker -->|"runs matching"| node_job_matching
node_redis_queue -.->|"dispatches work"| node_ingestion_worker
node_redis_queue -.->|"dispatches work"| node_matching_worker

click node_web_app "https://github.com/nitin3560/careeros/tree/main/apps/web/src/app"
click node_web_api "https://github.com/nitin3560/careeros/blob/main/apps/web/src/lib/api.ts"
click node_api "https://github.com/nitin3560/careeros/blob/main/apps/api/app/main.py"
click node_auth "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/auth.py"
click node_schemas "https://github.com/nitin3560/careeros/blob/main/apps/api/app/schemas.py"
click node_database_session "https://github.com/nitin3560/careeros/blob/main/apps/api/app/database.py"
click node_job_store "https://github.com/nitin3560/careeros/blob/main/apps/api/app/models.py"
click node_source_adapters "https://github.com/nitin3560/careeros/tree/main/apps/api/app/services/job_ingestion"
click node_source_discovery "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/job_ingestion/public_sources.py"
click node_job_persistence "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/job_ingestion/persist.py"
click node_poller_fetch "https://github.com/nitin3560/careeros/blob/main/apps/api/app/ingestion/poller/fetcher.py"
click node_poller_normalize "https://github.com/nitin3560/careeros/blob/main/apps/api/app/ingestion/poller/normalization.py"
click node_poller_repository "https://github.com/nitin3560/careeros/blob/main/apps/api/app/ingestion/poller/repository.py"
click node_poller_scheduler "https://github.com/nitin3560/careeros/blob/main/apps/api/app/ingestion/poller/scheduler.py"
click node_resume_parsing "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/resume_parsing.py"
click node_job_matching "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/job_matching.py"
click node_ai_client "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/ai_client.py"
click node_tailoring "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/tailoring.py"
click node_resume_export "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/resume_export.py"
click node_background_jobs "https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/background_jobs.py"
click node_ingestion_worker "https://github.com/nitin3560/careeros/blob/main/apps/api/app/workers/ingestion.py"
click node_matching_worker "https://github.com/nitin3560/careeros/blob/main/apps/api/app/workers/matching.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_source_adapters,node_source_discovery,node_job_persistence,node_poller_fetch,node_poller_normalize,node_poller_repository,node_poller_scheduler toneBlue
class node_api,node_auth,node_schemas,node_database_session,node_job_store toneAmber
class node_resume_parsing,node_job_matching,node_ai_client,node_tailoring,node_resume_export toneMint
class node_web_app,node_web_api toneRose
class node_background_jobs,node_ingestion_worker,node_matching_worker,node_redis_queue,node_candidate_user,node_company_sources,node_llm_provider toneIndigo
```

## Components

### Job collection

- [Job source adapters](https://github.com/nitin3560/careeros/tree/main/apps/api/app/services/job_ingestion): `apps/api/app/services/job_ingestion`
- [Public source discovery](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/job_ingestion/public_sources.py): `apps/api/app/services/job_ingestion/public_sources.py`
- [Job normalization and persistence](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/job_ingestion/persist.py): `apps/api/app/services/job_ingestion/persist.py`
- [Board fetching](https://github.com/nitin3560/careeros/blob/main/apps/api/app/ingestion/poller/fetcher.py): `apps/api/app/ingestion/poller/fetcher.py`
- [Poller normalization](https://github.com/nitin3560/careeros/blob/main/apps/api/app/ingestion/poller/normalization.py): `apps/api/app/ingestion/poller/normalization.py`
- [Poller writes and state](https://github.com/nitin3560/careeros/blob/main/apps/api/app/ingestion/poller/repository.py): `apps/api/app/ingestion/poller/repository.py`
- [Poller scheduling](https://github.com/nitin3560/careeros/blob/main/apps/api/app/ingestion/poller/scheduler.py): `apps/api/app/ingestion/poller/scheduler.py`

### API and persistence

- [REST API](https://github.com/nitin3560/careeros/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Authentication](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/auth.py): `apps/api/app/services/auth.py`
- [API schemas](https://github.com/nitin3560/careeros/blob/main/apps/api/app/schemas.py): `apps/api/app/schemas.py`
- [Database sessions](https://github.com/nitin3560/careeros/blob/main/apps/api/app/database.py): `apps/api/app/database.py`
- [PostgreSQL records](https://github.com/nitin3560/careeros/blob/main/apps/api/app/models.py): `apps/api/app/models.py`

### Candidate matching

- [Resume parsing](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/resume_parsing.py): `apps/api/app/services/resume_parsing.py`
- [Job matching](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/job_matching.py): `apps/api/app/services/job_matching.py`
- [AI provider client](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/ai_client.py): `apps/api/app/services/ai_client.py`
- [Resume tailoring](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/tailoring.py): `apps/api/app/services/tailoring.py`
- [Resume export](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/resume_export.py): `apps/api/app/services/resume_export.py`

### Web experience

- [CareerOS web app](https://github.com/nitin3560/careeros/tree/main/apps/web/src/app): `apps/web/src/app`
- [Web API client](https://github.com/nitin3560/careeros/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### Background processing

- [Background job tracking](https://github.com/nitin3560/careeros/blob/main/apps/api/app/services/background_jobs.py): `apps/api/app/services/background_jobs.py`
- [Ingestion worker](https://github.com/nitin3560/careeros/blob/main/apps/api/app/workers/ingestion.py): `apps/api/app/workers/ingestion.py`
- [Matching worker](https://github.com/nitin3560/careeros/blob/main/apps/api/app/workers/matching.py): `apps/api/app/workers/matching.py`
- **Redis queue**

### Other components

- **Job seeker**
- **Company job sources**
- **LLM providers**

## Connections

- Job seeker → CareerOS web app: uses (evidence: `README.md`)
- CareerOS web app → Web API client: requests data (evidence: `README.md`)
- Web API client → REST API: calls REST (evidence: `README.md`)
- REST API → Database sessions: opens sessions (evidence: `apps/api/app/main.py`)
- REST API → API schemas: uses responses (evidence: `apps/api/app/main.py`)
- Database sessions → PostgreSQL records: queries records (evidence: `apps/api/app/main.py`)
- REST API → Authentication: uses password hashing (evidence: `apps/api/app/main.py`)
- Company job sources → Public source discovery: provides job feeds (evidence: `README.md`)
- Public source discovery → Job source adapters: dispatches fetches (evidence: `apps/api/app/services/job_ingestion/public_sources.py`)
- Job source adapters → Job normalization and persistence: saves normalized jobs (evidence: `apps/api/app/services/job_ingestion/bulk.py`)
- Job normalization and persistence → PostgreSQL records: writes jobs (evidence: `apps/api/app/services/job_ingestion/persist.py`)
- Company job sources → Board fetching: supplies board data (evidence: `README.md`)
- Board fetching → Poller normalization: normalizes fetched jobs
- Poller normalization → Poller writes and state: provides normalized jobs (evidence: `apps/api/app/ingestion/poller/repository.py`)
- Poller writes and state → PostgreSQL records: writes job records (evidence: `apps/api/app/ingestion/poller/repository.py`)
- Poller scheduling → Board fetching: schedules polling
- REST API → Resume parsing: supports resume parsing (evidence: `README.md`)
- REST API → Job matching: serves ranked matches (evidence: `README.md`)
- Job matching → PostgreSQL records: filters job corpus (evidence: `README.md`)
- Job matching → AI provider client: requests AI ranking (evidence: `apps/api/app/services/job_matching.py`)
- AI provider client → LLM providers: sends completions (evidence: `apps/api/app/services/ai_client.py`)
- REST API → Resume tailoring: supports per-job tailoring (evidence: `README.md`)
- REST API → Resume export: exports resume versions (evidence: `apps/api/app/main.py`)
- Ingestion worker → Background job tracking: updates job status (evidence: `apps/api/app/workers/ingestion.py`)
- Ingestion worker → PostgreSQL records: ingests jobs (evidence: `apps/api/app/workers/ingestion.py`)
- Matching worker → Background job tracking: updates job status (evidence: `apps/api/app/workers/matching.py`)
- Matching worker → Job matching: runs matching (evidence: `apps/api/app/workers/matching.py`)
- Redis queue → Ingestion worker: dispatches work
- Redis queue → Matching worker: dispatches work
