How y4sserk/skillalign works
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: main.py FastAPI application · run_pipeline.py Pipeline orchestration · page.tsx Explore occupations · notes.py Notes service
Components 28
Web experience
- Explore occupations
app/frontend/app/(public)/explore/page.tsx - Occupation detail
app/frontend/components/features/occupations/occupation-detail.tsx - Skill recommendations
app/frontend/app/(public)/recommendations/page.tsx - Skill-gap roadmap
app/frontend/app/(public)/roadmap/page.tsx - Admin notes
app/frontend/app/(admin)/admin/notes/page.tsx
API and domain
- FastAPI application
app/api/main.py - Occupation routes
app/api/routes/occupations.py - Recommendation routes
app/api/routes/recommendations.py - Notes routes
app/api/routes/notes.py - Occupation service
app/api/services/occupations.py - Recommendation service
app/api/services/recommendations.py - Notes service
app/api/services/notes.py - Occupation contracts
app/api/schemas/occupations.py - Recommendation contracts
app/api/schemas/recommendations.py - Notes contracts
app/api/schemas/notes.py
Search and graph runtime
- Recommendation queries
app/api/repos/recommendations.py - Notes queries
app/api/repos/notes.py - Embedding search
app/core/ml.py - Neo4j client
app/core/neo4j.py - ESCO knowledge graph
- FAISS occupation index
ESCO data pipeline
- Pipeline orchestration
ml_pipeline/run_pipeline.py - CSV ingestion
ml_pipeline/data_ingestion.py - Taxonomy processing
ml_pipeline/data_processing.py - Embedding indexing
ml_pipeline/embedding_generator.py - Graph ETL
ml_pipeline/neo4j_etl.py
Other components
- Career seeker
- Taxonomy curator
Connections 29
- 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
app/api/main.py - FastAPI application → Recommendation routes: registers router
app/api/main.py - FastAPI application → Notes routes: registers router
app/api/main.py - Occupation routes → Occupation service: delegates to
app/api/routes/occupations.py - Occupation service → Occupation contracts: validates and shapes
app/api/services/occupations.py - Recommendation service → Recommendation queries: queries
app/api/services/recommendations.py - Recommendation service → Recommendation contracts: uses contracts
app/api/services/recommendations.py - Notes routes → Notes service: delegates to
app/api/routes/notes.py - Notes service → Notes queries: queries and updates
app/api/services/notes.py - Notes service → Notes contracts: uses contracts
app/api/services/notes.py - Recommendation queries → Embedding search: searches candidates
app/api/repos/recommendations.py - Recommendation queries → Neo4j client: fetches role skills
app/api/repos/recommendations.py - Notes queries → Neo4j client: runs note queries
app/api/repos/notes.py - Neo4j client → ESCO knowledge graph: executes queries
- Pipeline orchestration → CSV ingestion: loads source data
ml_pipeline/run_pipeline.py - Pipeline orchestration → Taxonomy processing: cleans and merges
ml_pipeline/run_pipeline.py - Pipeline orchestration → Graph ETL: hydrates graph
ml_pipeline/run_pipeline.py - Pipeline orchestration → Embedding indexing: builds index
ml_pipeline/run_pipeline.py - Graph ETL → ESCO knowledge graph: writes taxonomy
- Embedding indexing → FAISS occupation index: writes vectors
ml_pipeline/embedding_generator.py - Embedding search → FAISS occupation index: searches vectors
app/core/ml.py