# prajwalparish-git/skill-scout-nexus architecture

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

- Interactive diagram: https://gitdiagram.com/prajwalparish-git/skill-scout-nexus
- Repository: https://github.com/prajwalparish-git/skill-scout-nexus

## Overview

Skill Scout Nexus is a placement-readiness coach with both a Streamlit app and a Next.js frontend backed by an HTTP API. Students move from resume/profile assessment through skill-gap planning, quizzes, and voice or chat practice; results inform ongoing plans and readiness views. Organization administrators provision students and review cohort progress. The graph highlights these domain stages, shared services, agent workflows, and persistence. Relationships for unsampled features are included only where the README documents them; source excerpts and the SOURCE INDEX support the remaining links.

Main entry points: [`piq/journey.py`](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/journey.py) (Journey orchestration), [`piq/services.py`](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/services.py) (Application services), [`views/org_admin.py`](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/views/org_admin.py) (Organization portal), [`piq/ui.py`](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/ui.py) (Streamlit experience)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_streamlit["Streamlit experience<br/>[ui.py]"]
  node_web["Web experience"]
  node_api["HTTP API<br/>[server.py]"]
end

subgraph group_journey["Student journey"]
  node_resume["Resume assessment"]
  node_roadmap["Study roadmap"]
  node_quiz["Critic-checked quiz"]
  node_voice["Voice assessment"]
  node_interview["Interview practice<br/>[agents.py]"]
  node_journeyctl["Journey orchestration<br/>[journey.py]"]
  node_services["Application services<br/>[services.py]"]
end

subgraph group_agents["AI and assessment"]
  node_rubric["Rubric evaluation"]
  node_critic["Critic workflow<br/>[graph.py]"]
  node_checks["Quality checks<br/>[checks.py]"]
  node_questionbank[("Question bank<br/>[question_bank.py]")]
end

subgraph group_organizations["Organizations"]
  node_orgadmin["Organization portal<br/>[org_admin.py]"]
  node_orgprovision["Account provisioning"]
  node_orginsights["Cohort insights<br/>[org_insights.py]"]
end

subgraph group_platform["Shared platform"]
  node_store[("SQLite records<br/>[db.py]")]
  node_ai["LLM interface<br/>[llm.py]"]
  node_router["AI provider routing<br/>[ai_router.py]"]
  node_speech["Speech synthesis<br/>[speech_router.py]"]
  node_transcribe["Speech transcription"]
end

node_student(("Student"))
node_admin(("Organization admin"))

node_student -->|"uses"| node_streamlit
node_student -->|"uses"| node_web
node_admin -->|"manages cohort"| node_orgadmin
node_web -->|"requests data"| node_api
node_streamlit -->|"invokes"| node_services
node_streamlit -->|"uses"| node_journeyctl
node_api -->|"calls"| node_services
node_services -->|"uses"| node_resume
node_journeyctl -->|"dispatches"| node_resume
node_journeyctl -->|"dispatches"| node_roadmap
node_journeyctl -->|"dispatches"| node_quiz
node_journeyctl -->|"dispatches"| node_voice
node_journeyctl -->|"persists journey"| node_store
node_services -->|"reads and writes"| node_store
node_services -->|"looks up questions"| node_questionbank
node_quiz -->|"uses review loop"| node_critic
node_critic -->|"verifies drafts"| node_checks
node_critic -->|"records review"| node_store
node_rubric -->|"requests evaluation"| node_ai
node_ai -->|"routes requests"| node_router
node_voice -->|"speaks questions"| node_speech
node_voice -->|"transcribes answers"| node_transcribe
node_orgadmin -->|"provisions accounts"| node_orgprovision
node_orgadmin -->|"reviews cohort"| node_orginsights
node_orgadmin -->|"views student progress"| node_journeyctl

click node_streamlit "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/ui.py"
click node_web "https://github.com/prajwalparish-git/skill-scout-nexus/tree/main/frontend/app"
click node_api "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/server.py"
click node_resume "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/resume_parser_agent.py"
click node_roadmap "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/study_planner_agent.py"
click node_quiz "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/critic_quiz_agent.py"
click node_voice "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/voice_interview_agent.py"
click node_interview "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/agents.py"
click node_journeyctl "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/journey.py"
click node_services "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/services.py"
click node_rubric "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/rubric_evaluator_agent.py"
click node_critic "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/graph.py"
click node_checks "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/checks.py"
click node_questionbank "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/question_bank.py"
click node_orgadmin "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/views/org_admin.py"
click node_orgprovision "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/core/org_provisioning.py"
click node_orginsights "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/org_insights.py"
click node_store "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/db.py"
click node_ai "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/llm.py"
click node_router "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/core/ai_router.py"
click node_speech "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/core/speech_router.py"
click node_transcribe "https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/core/transcribe_router.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_streamlit,node_web,node_api toneBlue
class node_resume,node_roadmap,node_quiz,node_voice,node_interview,node_journeyctl,node_services toneAmber
class node_rubric,node_critic,node_checks,node_questionbank toneMint
class node_orgadmin,node_orgprovision,node_orginsights toneRose
class node_store,node_ai,node_router,node_speech,node_transcribe,node_student,node_admin toneIndigo
```

## Components

### User experience

- [Streamlit experience](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/ui.py): `piq/ui.py`
- [Web experience](https://github.com/prajwalparish-git/skill-scout-nexus/tree/main/frontend/app): `frontend/app`
- [HTTP API](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/server.py): `server.py`

### Student journey

- [Resume assessment](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/resume_parser_agent.py): `agents/resume_parser_agent.py`
- [Study roadmap](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/study_planner_agent.py): `agents/study_planner_agent.py`
- [Critic-checked quiz](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/critic_quiz_agent.py): `agents/critic_quiz_agent.py`
- [Voice assessment](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/voice_interview_agent.py): `agents/voice_interview_agent.py`
- [Interview practice](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/agents.py): `piq/agents.py`
- [Journey orchestration](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/journey.py): `piq/journey.py`
- [Application services](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/services.py): `piq/services.py`

### AI and assessment

- [Rubric evaluation](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/agents/rubric_evaluator_agent.py): `agents/rubric_evaluator_agent.py`
- [Critic workflow](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/graph.py): `piq/graph.py`
- [Quality checks](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/checks.py): `piq/checks.py`
- [Question bank](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/question_bank.py): `piq/question_bank.py`

### Organizations

- [Organization portal](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/views/org_admin.py): `views/org_admin.py`
- [Account provisioning](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/core/org_provisioning.py): `core/org_provisioning.py`
- [Cohort insights](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/org_insights.py): `piq/org_insights.py`

### Shared platform

- [SQLite records](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/db.py): `piq/db.py`
- [LLM interface](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/piq/llm.py): `piq/llm.py`
- [AI provider routing](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/core/ai_router.py): `core/ai_router.py`
- [Speech synthesis](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/core/speech_router.py): `core/speech_router.py`
- [Speech transcription](https://github.com/prajwalparish-git/skill-scout-nexus/blob/main/core/transcribe_router.py): `core/transcribe_router.py`

### Other components

- **Student**
- **Organization admin**

## Connections

- Student → Streamlit experience: uses
- Student → Web experience: uses
- Organization admin → Organization portal: manages cohort
- Web experience → HTTP API: requests data (evidence: `server.py`)
- Streamlit experience → Application services: invokes (evidence: `app.py`)
- Streamlit experience → Journey orchestration: uses (evidence: `app.py`)
- HTTP API → Application services: calls (evidence: `server.py`)
- Application services → Resume assessment: uses (evidence: `piq/services.py`)
- Journey orchestration → Resume assessment: dispatches (evidence: `piq/journey.py`)
- Journey orchestration → Study roadmap: dispatches (evidence: `piq/journey.py`)
- Journey orchestration → Critic-checked quiz: dispatches (evidence: `piq/journey.py`)
- Journey orchestration → Voice assessment: dispatches (evidence: `piq/journey.py`)
- Journey orchestration → SQLite records: persists journey (evidence: `piq/journey.py`)
- Application services → SQLite records: reads and writes (evidence: `piq/services.py`)
- Application services → Question bank: looks up questions (evidence: `piq/services.py`)
- Critic-checked quiz → Critic workflow: uses review loop (evidence: `piq/graph.py`)
- Critic workflow → Quality checks: verifies drafts (evidence: `piq/graph.py`)
- Critic workflow → SQLite records: records review (evidence: `piq/graph.py`)
- Rubric evaluation → LLM interface: requests evaluation
- LLM interface → AI provider routing: routes requests (evidence: `piq/llm.py`)
- Voice assessment → Speech synthesis: speaks questions (evidence: `piq/journey.py`)
- Voice assessment → Speech transcription: transcribes answers
- Organization portal → Account provisioning: provisions accounts
- Organization portal → Cohort insights: reviews cohort (evidence: `views/org_admin.py`)
- Organization portal → Journey orchestration: views student progress (evidence: `views/org_admin.py`)
