# techbypradnya/skillmaps-ai architecture

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

- Interactive diagram: https://gitdiagram.com/techbypradnya/skillmaps-ai
- Repository: https://github.com/techbypradnya/skillmaps-ai

## Overview

SkillGraph AI is an adaptive learning platform: learners create a profile and choose a target role, then explore a skill graph, assess proficiency, and receive gap analysis and an adaptive learning path. The platform also offers recommendations, progress dashboards, feedback, what-if planning, and an AI companion. The graph shows the backend route-to-service structure where source references support it. Frontend-to-backend calls are not evidenced in the excerpts, so those links are marked unverified.

Main entry points: [`backend/app/api/routes/misc_routes.py`](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/misc_routes.py) (Learning feature routes), [`backend/app/services/path_optimizer.py`](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/path_optimizer.py) (Adaptive path planning), [`backend/app/main.py`](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/main.py) (FastAPI application), [`frontend/lib/api.ts`](https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/lib/api.ts) (Frontend API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner experience"]
  node_auth_ui["Sign in and signup<br/>[page.tsx]"]
  node_onboarding["Profile onboarding<br/>[page.tsx]"]
  node_learning_ui["Learning workspace<br/>[page.tsx]"]
  node_assessment_ui["Assessment screen<br/>[page.tsx]"]
  node_dashboard_ui["Progress dashboard<br/>[page.tsx]"]
  node_companion_ui["AI companion<br/>[page.tsx]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth_routes.py]"]
  node_profile_routes["Profile routes<br/>[profile.py]"]
  node_skill_routes["Skill graph routes"]
  node_path_routes["Learning path routes<br/>[path_routes.py]"]
  node_misc_routes["Learning feature routes<br/>[misc_routes.py]"]
end

subgraph group_learning["Learning intelligence"]
  node_profile_service["Learner profiling<br/>[profiler.py]"]
  node_skill_graph["Skill graph engine<br/>[skill_graph.py]"]
  node_gap_analysis["Gap analysis<br/>[gap_analyzer.py]"]
  node_assessment["Assessment engine<br/>[assessment.py]"]
  node_path_optimizer["Adaptive path planning<br/>[path_optimizer.py]"]
  node_recommendations["Resource recommendations<br/>[recommendation.py]"]
  node_dashboard["Readiness and dashboard<br/>[dashboard.py]"]
  node_companion["Companion chat<br/>[companion.py]"]
  node_what_if["Scenario simulation<br/>[what_if.py]"]
  node_feedback["Learning feedback<br/>[feedback.py]"]
  node_explanation["Journey explanations<br/>[explanation.py]"]
end

subgraph group_persistence["Domain data"]
  node_models["Domain models<br/>[models.py]"]
  node_seed_data["Curated learning catalog<br/>[seed_data.py]"]
  node_db_seed["Database seeding<br/>[seed.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_database[("Relational database")]
end

subgraph group_integrations["AI integration"]
  node_llm["LLM provider<br/>[llm_provider.py]"]
end

node_learner(("Learner"))

node_learner -->|"signs in"| node_auth_ui
node_learner -->|"sets goals"| node_onboarding
node_learner -->|"learns"| node_learning_ui
node_learner -->|"takes assessment"| node_assessment_ui
node_learner -->|"checks progress"| node_dashboard_ui
node_learner -->|"asks questions"| node_companion_ui
node_auth_ui -.->|"uses"| node_api_client
node_onboarding -.->|"uses"| node_api_client
node_learning_ui -.->|"uses"| node_api_client
node_assessment_ui -.->|"uses"| node_api_client
node_dashboard_ui -.->|"uses"| node_api_client
node_companion_ui -.->|"uses"| node_api_client
node_api_client -.->|"calls API"| node_app
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_profile_routes
node_app -->|"registers"| node_skill_routes
node_app -->|"registers"| node_path_routes
node_app -->|"registers"| node_misc_routes
node_app -->|"seeds on startup"| node_db_seed
node_auth_routes -->|"queries users"| node_models
node_auth_routes -->|"gets sessions"| node_db_session
node_auth_routes -.->|"uses security"| node_profile_service
node_profile_routes -->|"profiles learners"| node_profile_service
node_profile_routes -->|"queries profiles"| node_models
node_skill_routes -->|"builds graph"| node_skill_graph
node_skill_routes -->|"analyzes gaps"| node_gap_analysis
node_path_routes -->|"plans paths"| node_path_optimizer
node_misc_routes -->|"generates and scores"| node_assessment
node_misc_routes -->|"replans path"| node_path_optimizer
node_misc_routes -->|"scores resources"| node_recommendations
node_misc_routes -->|"records feedback"| node_feedback
node_misc_routes -->|"simulates scenario"| node_what_if
node_misc_routes -->|"handles chat"| node_companion
node_misc_routes -->|"explains journey"| node_explanation
node_misc_routes -->|"builds dashboard"| node_dashboard
node_assessment -->|"generates text"| node_llm
node_companion -->|"generates replies"| node_llm
node_gap_analysis -->|"uses graph"| node_skill_graph
node_path_optimizer -->|"uses gap analysis"| node_gap_analysis
node_path_optimizer -->|"selects resources"| node_recommendations
node_path_optimizer -->|"orders skills"| node_skill_graph
node_dashboard -->|"uses gaps"| node_gap_analysis
node_dashboard -->|"reads active path"| node_path_optimizer
node_dashboard -->|"uses recommendations"| node_recommendations
node_companion -->|"uses learner gaps"| node_gap_analysis
node_companion -->|"uses learner path"| node_path_optimizer
node_explanation -->|"uses gaps"| node_gap_analysis
node_explanation -->|"uses path"| node_path_optimizer

click node_auth_ui "https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/login/page.tsx"
click node_onboarding "https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/onboarding/page.tsx"
click node_learning_ui "https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/my-path/page.tsx"
click node_assessment_ui "https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/assessment/page.tsx"
click node_dashboard_ui "https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/dashboard/page.tsx"
click node_companion_ui "https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/companion/page.tsx"
click node_api_client "https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/lib/api.ts"
click node_app "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/auth_routes.py"
click node_profile_routes "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/profile.py"
click node_skill_routes "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/skill_graph_routes.py"
click node_path_routes "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/path_routes.py"
click node_misc_routes "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/misc_routes.py"
click node_profile_service "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/profiler.py"
click node_skill_graph "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/skill_graph.py"
click node_gap_analysis "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/gap_analyzer.py"
click node_assessment "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/assessment.py"
click node_path_optimizer "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/path_optimizer.py"
click node_recommendations "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/recommendation.py"
click node_dashboard "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/dashboard.py"
click node_companion "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/companion.py"
click node_what_if "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/what_if.py"
click node_feedback "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/feedback.py"
click node_explanation "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/explanation.py"
click node_llm "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/llm_provider.py"
click node_models "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/models/models.py"
click node_seed_data "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/data/seed_data.py"
click node_db_seed "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/db/seed.py"
click node_db_session "https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/db/session.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_auth_ui,node_onboarding,node_learning_ui,node_assessment_ui,node_dashboard_ui,node_companion_ui,node_api_client toneBlue
class node_app,node_auth_routes,node_profile_routes,node_skill_routes,node_path_routes,node_misc_routes toneAmber
class node_profile_service,node_skill_graph,node_gap_analysis,node_assessment,node_path_optimizer,node_recommendations,node_dashboard,node_companion,node_what_if,node_feedback,node_explanation toneMint
class node_models,node_seed_data,node_db_seed,node_db_session,node_database toneRose
class node_llm,node_learner toneIndigo
```

## Components

### Learner experience

- [Sign in and signup](https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`
- [Profile onboarding](https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/onboarding/page.tsx): `frontend/app/onboarding/page.tsx`
- [Learning workspace](https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/my-path/page.tsx): `frontend/app/my-path/page.tsx`
- [Assessment screen](https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/assessment/page.tsx): `frontend/app/assessment/page.tsx`
- [Progress dashboard](https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [AI companion](https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/app/companion/page.tsx): `frontend/app/companion/page.tsx`
- [Frontend API client](https://github.com/techbypradnya/skillmaps-ai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and identity

- [FastAPI application](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/auth_routes.py): `backend/app/api/routes/auth_routes.py`
- [Profile routes](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/profile.py): `backend/app/api/routes/profile.py`
- [Skill graph routes](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/skill_graph_routes.py): `backend/app/api/routes/skill_graph_routes.py`
- [Learning path routes](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/path_routes.py): `backend/app/api/routes/path_routes.py`
- [Learning feature routes](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/api/routes/misc_routes.py): `backend/app/api/routes/misc_routes.py`

### Learning intelligence

- [Learner profiling](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/profiler.py): `backend/app/services/profiler.py`
- [Skill graph engine](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/skill_graph.py): `backend/app/services/skill_graph.py`
- [Gap analysis](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/gap_analyzer.py): `backend/app/services/gap_analyzer.py`
- [Assessment engine](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/assessment.py): `backend/app/services/assessment.py`
- [Adaptive path planning](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/path_optimizer.py): `backend/app/services/path_optimizer.py`
- [Resource recommendations](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/recommendation.py): `backend/app/services/recommendation.py`
- [Readiness and dashboard](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/dashboard.py): `backend/app/services/dashboard.py`
- [Companion chat](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/companion.py): `backend/app/services/companion.py`
- [Scenario simulation](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/what_if.py): `backend/app/services/what_if.py`
- [Learning feedback](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/feedback.py): `backend/app/services/feedback.py`
- [Journey explanations](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/explanation.py): `backend/app/services/explanation.py`

### Domain data

- [Domain models](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/models/models.py): `backend/app/models/models.py`
- [Curated learning catalog](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/data/seed_data.py): `backend/app/data/seed_data.py`
- [Database seeding](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/db/seed.py): `backend/app/db/seed.py`
- [Database sessions](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- **Relational database**

### AI integration

- [LLM provider](https://github.com/techbypradnya/skillmaps-ai/blob/main/backend/app/services/llm_provider.py): `backend/app/services/llm_provider.py`

### Other components

- **Learner**

## Connections

- Learner → Sign in and signup: signs in
- Learner → Profile onboarding: sets goals
- Learner → Learning workspace: learns
- Learner → Assessment screen: takes assessment
- Learner → Progress dashboard: checks progress
- Learner → AI companion: asks questions
- Sign in and signup → Frontend API client: uses
- Profile onboarding → Frontend API client: uses
- Learning workspace → Frontend API client: uses
- Assessment screen → Frontend API client: uses
- Progress dashboard → Frontend API client: uses
- AI companion → Frontend API client: uses
- Frontend API client → FastAPI application: calls API
- FastAPI application → Authentication routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Profile routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Skill graph routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Learning path routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Learning feature routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Database seeding: seeds on startup (evidence: `backend/app/main.py`)
- Authentication routes → Domain models: queries users (evidence: `backend/app/api/routes/auth_routes.py`)
- Authentication routes → Database sessions: gets sessions (evidence: `backend/app/api/routes/auth_routes.py`)
- Authentication routes → Learner profiling: uses security
- Profile routes → Learner profiling: profiles learners (evidence: `backend/app/api/routes/profile.py`)
- Profile routes → Domain models: queries profiles (evidence: `backend/app/api/routes/profile.py`)
- Skill graph routes → Skill graph engine: builds graph (evidence: `backend/app/api/routes/skill_graph_routes.py`)
- Skill graph routes → Gap analysis: analyzes gaps (evidence: `backend/app/api/routes/skill_graph_routes.py`)
- Learning path routes → Adaptive path planning: plans paths (evidence: `backend/app/api/routes/path_routes.py`)
- Learning feature routes → Assessment engine: generates and scores (evidence: `backend/app/api/routes/misc_routes.py`)
- Learning feature routes → Adaptive path planning: replans path (evidence: `backend/app/api/routes/misc_routes.py`)
- Learning feature routes → Resource recommendations: scores resources (evidence: `backend/app/api/routes/misc_routes.py`)
- Learning feature routes → Learning feedback: records feedback (evidence: `backend/app/api/routes/misc_routes.py`)
- Learning feature routes → Scenario simulation: simulates scenario (evidence: `backend/app/api/routes/misc_routes.py`)
- Learning feature routes → Companion chat: handles chat (evidence: `backend/app/api/routes/misc_routes.py`)
- Learning feature routes → Journey explanations: explains journey (evidence: `backend/app/api/routes/misc_routes.py`)
- Learning feature routes → Readiness and dashboard: builds dashboard (evidence: `backend/app/api/routes/misc_routes.py`)
- Assessment engine → LLM provider: generates text (evidence: `backend/app/services/assessment.py`)
- Companion chat → LLM provider: generates replies (evidence: `backend/app/services/companion.py`)
- Gap analysis → Skill graph engine: uses graph (evidence: `backend/app/services/gap_analyzer.py`)
- Adaptive path planning → Gap analysis: uses gap analysis (evidence: `backend/app/services/path_optimizer.py`)
- Adaptive path planning → Resource recommendations: selects resources (evidence: `backend/app/services/path_optimizer.py`)
- Adaptive path planning → Skill graph engine: orders skills (evidence: `backend/app/services/path_optimizer.py`)
- Readiness and dashboard → Gap analysis: uses gaps (evidence: `backend/app/services/dashboard.py`)
- Readiness and dashboard → Adaptive path planning: reads active path (evidence: `backend/app/services/dashboard.py`)
- Readiness and dashboard → Resource recommendations: uses recommendations (evidence: `backend/app/services/dashboard.py`)
- Companion chat → Gap analysis: uses learner gaps (evidence: `backend/app/services/companion.py`)
- Companion chat → Adaptive path planning: uses learner path (evidence: `backend/app/services/companion.py`)
- Journey explanations → Gap analysis: uses gaps (evidence: `backend/app/services/explanation.py`)
- Journey explanations → Adaptive path planning: uses path (evidence: `backend/app/services/explanation.py`)
