# y4sserk/skillalign architecture

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

- Interactive diagram: https://gitdiagram.com/y4sserk/skillalign
- Repository: https://github.com/y4sserk/skillalign

## Overview

SkillAlign is a career recommendation and skill-gap analysis product. Users explore ESCO occupations or submit skills to find semantically similar roles, compare required skills, and use the resulting gaps as a roadmap; administrators manage occupation notes. The web interface reaches a FastAPI API backed by Neo4j and a FAISS/SentenceTransformer engine. A separate ESCO pipeline ingests and processes taxonomy data, hydrates Neo4j, and creates the search index. Some API and frontend wiring is unsampled, so those links are omitted unless documented or directly supported.

Main entry points: [`app/api/main.py`](https://github.com/y4sserk/skillalign/blob/main/app/api/main.py) (FastAPI application), [`ml_pipeline/run_pipeline.py`](https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/run_pipeline.py) (Pipeline orchestration), [`app/frontend/app/(public)/explore/page.tsx`](https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(public)/explore/page.tsx) (Explore occupations), [`app/api/services/notes.py`](https://github.com/y4sserk/skillalign/blob/main/app/api/services/notes.py) (Notes service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_explore["Explore occupations<br/>[page.tsx]"]
  node_web_detail["Occupation detail"]
  node_web_recommend["Skill recommendations<br/>[page.tsx]"]
  node_web_roadmap["Skill-gap roadmap<br/>[page.tsx]"]
  node_web_notes["Admin notes<br/>[page.tsx]"]
end

subgraph group_api["API and domain"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_occupation_routes["Occupation routes<br/>[occupations.py]"]
  node_recommend_routes["Recommendation routes<br/>[recommendations.py]"]
  node_notes_routes["Notes routes<br/>[notes.py]"]
  node_occupation_service["Occupation service<br/>[occupations.py]"]
  node_recommend_service["Recommendation service<br/>[recommendations.py]"]
  node_notes_service["Notes service<br/>[notes.py]"]
  node_occupation_schema["Occupation contracts<br/>[occupations.py]"]
  node_recommend_schema["Recommendation contracts<br/>[recommendations.py]"]
  node_notes_schema["Notes contracts<br/>[notes.py]"]
end

subgraph group_runtime["Search and graph runtime"]
  node_recommend_repo["Recommendation queries<br/>[recommendations.py]"]
  node_notes_repo["Notes queries<br/>[notes.py]"]
  node_ml_engine["Embedding search<br/>[ml.py]"]
  node_neo4j_client["Neo4j client<br/>[neo4j.py]"]
  node_neo4j_store[("ESCO knowledge graph")]
  node_faiss_store[("FAISS occupation index")]
end

subgraph group_pipeline["ESCO data pipeline"]
  node_pipeline_runner["Pipeline orchestration<br/>[run_pipeline.py]"]
  node_ingestion["CSV ingestion<br/>[data_ingestion.py]"]
  node_processing["Taxonomy processing<br/>[data_processing.py]"]
  node_embedding_build["Embedding indexing"]
  node_graph_etl["Graph ETL<br/>[neo4j_etl.py]"]
end

node_user(("Career seeker"))
node_admin(("Taxonomy curator"))

node_user -->|"explores roles"| node_web_explore
node_user -->|"submits skills"| node_web_recommend
node_user -->|"reviews gaps"| node_web_roadmap
node_admin -->|"curates notes"| node_web_notes
node_web_explore -->|"opens role"| node_web_detail
node_web_explore -->|"uses JSON API"| node_api_app
node_web_recommend -->|"uses JSON API"| node_api_app
node_web_notes -->|"uses JSON API"| node_api_app
node_api_app -->|"registers router"| node_occupation_routes
node_api_app -->|"registers router"| node_recommend_routes
node_api_app -->|"registers router"| node_notes_routes
node_occupation_routes -->|"delegates to"| node_occupation_service
node_occupation_service -->|"validates and shapes"| node_occupation_schema
node_recommend_service -->|"queries"| node_recommend_repo
node_recommend_service -->|"uses contracts"| node_recommend_schema
node_notes_routes -->|"delegates to"| node_notes_service
node_notes_service -->|"queries and updates"| node_notes_repo
node_notes_service -->|"uses contracts"| node_notes_schema
node_recommend_repo -->|"searches candidates"| node_ml_engine
node_recommend_repo -->|"fetches role skills"| node_neo4j_client
node_notes_repo -->|"runs note queries"| node_neo4j_client
node_neo4j_client -->|"executes queries"| node_neo4j_store
node_pipeline_runner -->|"loads source data"| node_ingestion
node_pipeline_runner -->|"cleans and merges"| node_processing
node_pipeline_runner -->|"hydrates graph"| node_graph_etl
node_pipeline_runner -->|"builds index"| node_embedding_build
node_graph_etl -->|"writes taxonomy"| node_neo4j_store
node_embedding_build -->|"writes vectors"| node_faiss_store
node_ml_engine -->|"searches vectors"| node_faiss_store

click node_web_explore "https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(public)/explore/page.tsx"
click node_web_detail "https://github.com/y4sserk/skillalign/blob/main/app/frontend/components/features/occupations/occupation-detail.tsx"
click node_web_recommend "https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(public)/recommendations/page.tsx"
click node_web_roadmap "https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(public)/roadmap/page.tsx"
click node_web_notes "https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(admin)/admin/notes/page.tsx"
click node_api_app "https://github.com/y4sserk/skillalign/blob/main/app/api/main.py"
click node_occupation_routes "https://github.com/y4sserk/skillalign/blob/main/app/api/routes/occupations.py"
click node_recommend_routes "https://github.com/y4sserk/skillalign/blob/main/app/api/routes/recommendations.py"
click node_notes_routes "https://github.com/y4sserk/skillalign/blob/main/app/api/routes/notes.py"
click node_occupation_service "https://github.com/y4sserk/skillalign/blob/main/app/api/services/occupations.py"
click node_recommend_service "https://github.com/y4sserk/skillalign/blob/main/app/api/services/recommendations.py"
click node_notes_service "https://github.com/y4sserk/skillalign/blob/main/app/api/services/notes.py"
click node_occupation_schema "https://github.com/y4sserk/skillalign/blob/main/app/api/schemas/occupations.py"
click node_recommend_schema "https://github.com/y4sserk/skillalign/blob/main/app/api/schemas/recommendations.py"
click node_notes_schema "https://github.com/y4sserk/skillalign/blob/main/app/api/schemas/notes.py"
click node_recommend_repo "https://github.com/y4sserk/skillalign/blob/main/app/api/repos/recommendations.py"
click node_notes_repo "https://github.com/y4sserk/skillalign/blob/main/app/api/repos/notes.py"
click node_ml_engine "https://github.com/y4sserk/skillalign/blob/main/app/core/ml.py"
click node_neo4j_client "https://github.com/y4sserk/skillalign/blob/main/app/core/neo4j.py"
click node_pipeline_runner "https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/run_pipeline.py"
click node_ingestion "https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/data_ingestion.py"
click node_processing "https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/data_processing.py"
click node_embedding_build "https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/embedding_generator.py"
click node_graph_etl "https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/neo4j_etl.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_explore,node_web_detail,node_web_recommend,node_web_roadmap,node_web_notes toneBlue
class node_api_app,node_occupation_routes,node_recommend_routes,node_notes_routes,node_occupation_service,node_recommend_service,node_notes_service,node_occupation_schema,node_recommend_schema,node_notes_schema toneAmber
class node_recommend_repo,node_notes_repo,node_ml_engine,node_neo4j_client,node_neo4j_store,node_faiss_store toneMint
class node_pipeline_runner,node_ingestion,node_processing,node_embedding_build,node_graph_etl toneRose
class node_user,node_admin toneIndigo
```

## Components

### Web experience

- [Explore occupations](https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(public)/explore/page.tsx): `app/frontend/app/(public)/explore/page.tsx`
- [Occupation detail](https://github.com/y4sserk/skillalign/blob/main/app/frontend/components/features/occupations/occupation-detail.tsx): `app/frontend/components/features/occupations/occupation-detail.tsx`
- [Skill recommendations](https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(public)/recommendations/page.tsx): `app/frontend/app/(public)/recommendations/page.tsx`
- [Skill-gap roadmap](https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(public)/roadmap/page.tsx): `app/frontend/app/(public)/roadmap/page.tsx`
- [Admin notes](https://github.com/y4sserk/skillalign/blob/main/app/frontend/app/(admin)/admin/notes/page.tsx): `app/frontend/app/(admin)/admin/notes/page.tsx`

### API and domain

- [FastAPI application](https://github.com/y4sserk/skillalign/blob/main/app/api/main.py): `app/api/main.py`
- [Occupation routes](https://github.com/y4sserk/skillalign/blob/main/app/api/routes/occupations.py): `app/api/routes/occupations.py`
- [Recommendation routes](https://github.com/y4sserk/skillalign/blob/main/app/api/routes/recommendations.py): `app/api/routes/recommendations.py`
- [Notes routes](https://github.com/y4sserk/skillalign/blob/main/app/api/routes/notes.py): `app/api/routes/notes.py`
- [Occupation service](https://github.com/y4sserk/skillalign/blob/main/app/api/services/occupations.py): `app/api/services/occupations.py`
- [Recommendation service](https://github.com/y4sserk/skillalign/blob/main/app/api/services/recommendations.py): `app/api/services/recommendations.py`
- [Notes service](https://github.com/y4sserk/skillalign/blob/main/app/api/services/notes.py): `app/api/services/notes.py`
- [Occupation contracts](https://github.com/y4sserk/skillalign/blob/main/app/api/schemas/occupations.py): `app/api/schemas/occupations.py`
- [Recommendation contracts](https://github.com/y4sserk/skillalign/blob/main/app/api/schemas/recommendations.py): `app/api/schemas/recommendations.py`
- [Notes contracts](https://github.com/y4sserk/skillalign/blob/main/app/api/schemas/notes.py): `app/api/schemas/notes.py`

### Search and graph runtime

- [Recommendation queries](https://github.com/y4sserk/skillalign/blob/main/app/api/repos/recommendations.py): `app/api/repos/recommendations.py`
- [Notes queries](https://github.com/y4sserk/skillalign/blob/main/app/api/repos/notes.py): `app/api/repos/notes.py`
- [Embedding search](https://github.com/y4sserk/skillalign/blob/main/app/core/ml.py): `app/core/ml.py`
- [Neo4j client](https://github.com/y4sserk/skillalign/blob/main/app/core/neo4j.py): `app/core/neo4j.py`
- **ESCO knowledge graph**
- **FAISS occupation index**

### ESCO data pipeline

- [Pipeline orchestration](https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/run_pipeline.py): `ml_pipeline/run_pipeline.py`
- [CSV ingestion](https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/data_ingestion.py): `ml_pipeline/data_ingestion.py`
- [Taxonomy processing](https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/data_processing.py): `ml_pipeline/data_processing.py`
- [Embedding indexing](https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/embedding_generator.py): `ml_pipeline/embedding_generator.py`
- [Graph ETL](https://github.com/y4sserk/skillalign/blob/main/ml_pipeline/neo4j_etl.py): `ml_pipeline/neo4j_etl.py`

### Other components

- **Career seeker**
- **Taxonomy curator**

## Connections

- Career seeker → Explore occupations: explores roles
- Career seeker → Skill recommendations: submits skills
- Career seeker → Skill-gap roadmap: reviews gaps
- Taxonomy curator → Admin notes: curates notes
- Explore occupations → Occupation detail: opens role
- Explore occupations → FastAPI application: uses JSON API
- Skill recommendations → FastAPI application: uses JSON API
- Admin notes → FastAPI application: uses JSON API
- FastAPI application → Occupation routes: registers router (evidence: `app/api/main.py`)
- FastAPI application → Recommendation routes: registers router (evidence: `app/api/main.py`)
- FastAPI application → Notes routes: registers router (evidence: `app/api/main.py`)
- Occupation routes → Occupation service: delegates to (evidence: `app/api/routes/occupations.py`)
- Occupation service → Occupation contracts: validates and shapes (evidence: `app/api/services/occupations.py`)
- Recommendation service → Recommendation queries: queries (evidence: `app/api/services/recommendations.py`)
- Recommendation service → Recommendation contracts: uses contracts (evidence: `app/api/services/recommendations.py`)
- Notes routes → Notes service: delegates to (evidence: `app/api/routes/notes.py`)
- Notes service → Notes queries: queries and updates (evidence: `app/api/services/notes.py`)
- Notes service → Notes contracts: uses contracts (evidence: `app/api/services/notes.py`)
- Recommendation queries → Embedding search: searches candidates (evidence: `app/api/repos/recommendations.py`)
- Recommendation queries → Neo4j client: fetches role skills (evidence: `app/api/repos/recommendations.py`)
- Notes queries → Neo4j client: runs note queries (evidence: `app/api/repos/notes.py`)
- Neo4j client → ESCO knowledge graph: executes queries
- Pipeline orchestration → CSV ingestion: loads source data (evidence: `ml_pipeline/run_pipeline.py`)
- Pipeline orchestration → Taxonomy processing: cleans and merges (evidence: `ml_pipeline/run_pipeline.py`)
- Pipeline orchestration → Graph ETL: hydrates graph (evidence: `ml_pipeline/run_pipeline.py`)
- Pipeline orchestration → Embedding indexing: builds index (evidence: `ml_pipeline/run_pipeline.py`)
- Graph ETL → ESCO knowledge graph: writes taxonomy
- Embedding indexing → FAISS occupation index: writes vectors (evidence: `ml_pipeline/embedding_generator.py`)
- Embedding search → FAISS occupation index: searches vectors (evidence: `app/core/ml.py`)