# khvavuong/career-readiness architecture

> Architecture diagram of the GitHub repository khvavuong/career-readiness, 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/khvavuong/career-readiness
- Repository: https://github.com/khvavuong/career-readiness

## Overview

This is an AI career-readiness platform: users build a profile, review CV-derived skills, and explore skill-roadmap and readiness information tied to target roles and job-market data. Admins curate the skill catalog, imported job requirements, and reference-roadmap mappings; background workers handle extraction, CV analysis, market rebuilds, and roadmap imports. The graph connects only relationships supported by excerpts or the source index. The README provides no product documentation, and several UI and service internals were not sampled, so those connections are omitted.

Main entry points: [`apps/api/app/worker/handlers.py`](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/worker/handlers.py) (Worker handlers), [`apps/api/app/api/v1/router.py`](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/router.py) (API routes), [`apps/api/app/services/cv_service.py`](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/cv_service.py) (CV analysis), [`apps/api/app/services/reference_roadmap_service.py`](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/reference_roadmap_service.py) (Reference roadmaps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web_onboarding["Onboarding"]
  node_web_dashboard["Dashboard"]
  node_web_roadmap["Skill roadmap"]
  node_web_admin["Admin workspace<br/>[admin-shell.tsx]"]
end

subgraph group_api["API and identity"]
  node_app["API application<br/>[main.py]"]
  node_routes["API routes<br/>[router.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_profile_api["Profile routes<br/>[profile.py]"]
  node_readiness_api["Readiness routes<br/>[readiness.py]"]
  node_roles_api["Role routes<br/>[roles.py]"]
end

subgraph group_career["Career intelligence"]
  node_cv["CV analysis<br/>[cv_service.py]"]
  node_catalog[("Skill catalog")]
  node_readiness["Readiness scoring"]
  node_market["Market insights<br/>[market_service.py]"]
  node_job_import["Job extraction"]
end

subgraph group_curation["Admin curation"]
  node_admin_queries["Admin queries"]
  node_review_store[("Review queue")]
  node_roadmap_service["Reference roadmaps"]
  node_roadmap_source["Roadmap source<br/>[client.py]"]
end

subgraph group_runtime["Async processing"]
  node_task_queue["Task queue<br/>[task_queue.py]"]
  node_worker["Worker handlers<br/>[handlers.py]"]
  node_ai["AI adapters<br/>[factory.py]"]
end

node_user(("User"))

node_app -->|"mounts routes"| node_routes
node_routes -->|"registers"| node_profile_api
node_routes -->|"registers"| node_readiness_api
node_routes -->|"registers"| node_roles_api
node_routes -->|"routes auth"| node_auth
node_profile_api -->|"calls"| node_cv
node_readiness_api -->|"calls"| node_readiness
node_roles_api -->|"calls"| node_market
node_worker -->|"dispatches tasks"| node_task_queue
node_worker -->|"invokes analysis"| node_cv
node_worker -->|"invokes extraction"| node_job_import
node_worker -->|"rebuilds market"| node_market
node_worker -->|"imports roadmap"| node_roadmap_service
node_worker -->|"gets analyzers"| node_ai
node_roadmap_service -->|"fetches source"| node_roadmap_source
node_roadmap_service -->|"records unresolved"| node_review_store
node_cv -->|"uses analyzer"| node_ai
node_cv -->|"resolves skills"| node_catalog
node_admin_queries -->|"lists candidates"| node_review_store
node_admin_queries -->|"loads skill summaries"| node_catalog

click node_web_onboarding "https://github.com/khvavuong/career-readiness/blob/main/apps/web/features/onboarding/onboarding-flow.tsx"
click node_web_dashboard "https://github.com/khvavuong/career-readiness/blob/main/apps/web/features/dashboard/dashboard-overview.tsx"
click node_web_roadmap "https://github.com/khvavuong/career-readiness/blob/main/apps/web/features/skill-graph/roadmap-workspace.tsx"
click node_web_admin "https://github.com/khvavuong/career-readiness/blob/main/apps/web/features/admin/admin-shell.tsx"
click node_app "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/main.py"
click node_routes "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/router.py"
click node_auth "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/auth_service.py"
click node_profile_api "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/profile.py"
click node_readiness_api "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/readiness.py"
click node_roles_api "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/roles.py"
click node_cv "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/cv_service.py"
click node_catalog "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/repositories/skill_repository.py"
click node_readiness "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/readiness_service.py"
click node_market "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/market_service.py"
click node_job_import "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/job_extraction_service.py"
click node_admin_queries "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/admin_query_service.py"
click node_review_store "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/repositories/review_repository.py"
click node_roadmap_service "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/reference_roadmap_service.py"
click node_roadmap_source "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/reference_roadmaps/client.py"
click node_task_queue "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/queue/task_queue.py"
click node_worker "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/worker/handlers.py"
click node_ai "https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/ai/factory.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_web_onboarding,node_web_dashboard,node_web_roadmap,node_web_admin,node_user toneBlue
class node_app,node_routes,node_auth,node_profile_api,node_readiness_api,node_roles_api toneAmber
class node_cv,node_catalog,node_readiness,node_market,node_job_import toneMint
class node_admin_queries,node_review_store,node_roadmap_service,node_roadmap_source toneRose
class node_task_queue,node_worker,node_ai toneIndigo
```

## Components

### User experience

- [Onboarding](https://github.com/khvavuong/career-readiness/blob/main/apps/web/features/onboarding/onboarding-flow.tsx): `apps/web/features/onboarding/onboarding-flow.tsx`
- [Dashboard](https://github.com/khvavuong/career-readiness/blob/main/apps/web/features/dashboard/dashboard-overview.tsx): `apps/web/features/dashboard/dashboard-overview.tsx`
- [Skill roadmap](https://github.com/khvavuong/career-readiness/blob/main/apps/web/features/skill-graph/roadmap-workspace.tsx): `apps/web/features/skill-graph/roadmap-workspace.tsx`
- [Admin workspace](https://github.com/khvavuong/career-readiness/blob/main/apps/web/features/admin/admin-shell.tsx): `apps/web/features/admin/admin-shell.tsx`

### API and identity

- [API application](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [API routes](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/router.py): `apps/api/app/api/v1/router.py`
- [Authentication](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/auth_service.py): `apps/api/app/services/auth_service.py`
- [Profile routes](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/profile.py): `apps/api/app/api/v1/profile.py`
- [Readiness routes](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/readiness.py): `apps/api/app/api/v1/readiness.py`
- [Role routes](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/api/v1/roles.py): `apps/api/app/api/v1/roles.py`

### Career intelligence

- [CV analysis](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/cv_service.py): `apps/api/app/services/cv_service.py`
- [Skill catalog](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/repositories/skill_repository.py): `apps/api/app/repositories/skill_repository.py`
- [Readiness scoring](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/readiness_service.py): `apps/api/app/services/readiness_service.py`
- [Market insights](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/market_service.py): `apps/api/app/services/market_service.py`
- [Job extraction](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/job_extraction_service.py): `apps/api/app/services/job_extraction_service.py`

### Admin curation

- [Admin queries](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/admin_query_service.py): `apps/api/app/services/admin_query_service.py`
- [Review queue](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/repositories/review_repository.py): `apps/api/app/repositories/review_repository.py`
- [Reference roadmaps](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/services/reference_roadmap_service.py): `apps/api/app/services/reference_roadmap_service.py`
- [Roadmap source](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/reference_roadmaps/client.py): `apps/api/app/reference_roadmaps/client.py`

### Async processing

- [Task queue](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/queue/task_queue.py): `apps/api/app/queue/task_queue.py`
- [Worker handlers](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/worker/handlers.py): `apps/api/app/worker/handlers.py`
- [AI adapters](https://github.com/khvavuong/career-readiness/blob/main/apps/api/app/ai/factory.py): `apps/api/app/ai/factory.py`

### Other components

- **User**

## Connections

- API application → API routes: mounts routes (evidence: `apps/api/app/main.py`)
- API routes → Profile routes: registers (evidence: `apps/api/app/api/v1/router.py`)
- API routes → Readiness routes: registers (evidence: `apps/api/app/api/v1/router.py`)
- API routes → Role routes: registers (evidence: `apps/api/app/api/v1/router.py`)
- API routes → Authentication: routes auth
- Profile routes → CV analysis: calls (evidence: `apps/api/app/api/v1/profile.py`)
- Readiness routes → Readiness scoring: calls (evidence: `apps/api/app/api/v1/readiness.py`)
- Role routes → Market insights: calls (evidence: `apps/api/app/api/v1/roles.py`)
- Worker handlers → Task queue: dispatches tasks (evidence: `apps/api/app/worker/handlers.py`)
- Worker handlers → CV analysis: invokes analysis (evidence: `apps/api/app/worker/handlers.py`)
- Worker handlers → Job extraction: invokes extraction (evidence: `apps/api/app/worker/handlers.py`)
- Worker handlers → Market insights: rebuilds market (evidence: `apps/api/app/worker/handlers.py`)
- Worker handlers → Reference roadmaps: imports roadmap (evidence: `apps/api/app/worker/handlers.py`)
- Worker handlers → AI adapters: gets analyzers (evidence: `apps/api/app/worker/handlers.py`)
- Reference roadmaps → Roadmap source: fetches source (evidence: `apps/api/app/services/reference_roadmap_service.py`)
- Reference roadmaps → Review queue: records unresolved (evidence: `apps/api/app/services/reference_roadmap_service.py`)
- CV analysis → AI adapters: uses analyzer (evidence: `apps/api/app/services/cv_service.py`)
- CV analysis → Skill catalog: resolves skills (evidence: `apps/api/app/services/cv_service.py`)
- Admin queries → Review queue: lists candidates (evidence: `apps/api/app/services/admin_query_service.py`)
- Admin queries → Skill catalog: loads skill summaries (evidence: `apps/api/app/services/admin_query_service.py`)
