# rithusona35-cpu/ncct-ecosystem architecture

> Architecture diagram of the GitHub repository rithusona35-cpu/ncct-ecosystem, 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/rithusona35-cpu/ncct-ecosystem
- Repository: https://github.com/rithusona35-cpu/ncct-ecosystem

## Overview

NCCT is a closed-loop skills-to-employment ecosystem: learners progress from physical training and attendance through LMS learning, assessment, skill-gap diagnosis, remedial recommendations, and a verifiable skill passport; employers match and hire candidates, then provide placement feedback that informs curriculum updates. The graph includes the sampled API, data, and intelligence layers plus major README-documented capabilities. Several frontend pages and integrations were not sampled, so undocumented implementation links are omitted.

Main entry points: [`backend/app/routers/lms.py`](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/lms.py) (Courses and LMS), [`backend/app/routers/assessment.py`](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/assessment.py) (Competency Assessment), [`backend/app/main.py`](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/main.py) (FastAPI Gateway), [`backend/app/routers/attendance.py`](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/attendance.py) (Attendance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Web Portals"]
  node_trainee["Trainee Portal<br/>[page.tsx]"]
  node_trainer["Trainer Portal<br/>[page.tsx]"]
  node_employer["Employer Portal<br/>[page.tsx]"]
  node_admin["Admin Portal<br/>[page.tsx]"]
  node_auth_ui["Session and Access<br/>[AuthContext.tsx]"]
end

subgraph group_backend["API and Domain"]
  node_api["FastAPI Gateway<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_attendance["Attendance<br/>[attendance.py]"]
  node_learning["Courses and LMS<br/>[lms.py]"]
  node_assessment["Competency Assessment<br/>[assessment.py]"]
  node_passport["Skill Passport"]
  node_certificates["Certificates"]
  node_storage["Media Storage<br/>[storage_service.py]"]
  node_database[("Relational Database<br/>[database.py]")]
  node_models["Domain Models<br/>[models.py]"]
end

subgraph group_intelligence["Skills Intelligence"]
  node_matching["Employer Matching"]
  node_skill_gap["Skill-Gap Engine"]
  node_remedial["Remedial Recommendations<br/>[skill_gap.py]"]
  node_feedback["Placement Feedback"]
  node_curriculum["Curriculum Intelligence"]
  node_chatbot["Career Guidance RAG<br/>[query.py]"]
  node_gemini["Gemini Client<br/>[gemini_client.py]"]
end

subgraph group_edge["Training Edge"]
  node_kiosk["ESP32 Training Node<br/>[config.h]"]
end

node_trainee_actor(("Trainee"))
node_trainer_actor(("Trainer"))
node_employer_actor(("Employer"))
node_admin_actor(("Administrator"))

node_api -->|"routes to"| node_auth
node_api -->|"routes to"| node_attendance
node_api -->|"routes to"| node_learning
node_api -->|"routes to"| node_assessment
node_auth -->|"queries users"| node_database
node_attendance -->|"records attendance"| node_database
node_learning -->|"records progress"| node_database
node_assessment -->|"stores results"| node_database
node_assessment -->|"issues"| node_certificates
node_certificates -->|"uploads PDFs"| node_storage
node_skill_gap -->|"recommends learning"| node_remedial
node_matching -->|"uses skill scores"| node_skill_gap
node_admin -->|"views intelligence"| node_curriculum
node_curriculum -->|"aggregates feedback"| node_feedback
node_auth_ui -->|"verifies session"| node_auth
node_trainee_actor -->|"scans badge"| node_kiosk
node_kiosk -->|"syncs attendance"| node_attendance
node_trainee_actor -->|"uses portal"| node_trainee
node_trainer_actor -->|"uses portal"| node_trainer
node_employer_actor -->|"uses portal"| node_employer
node_admin_actor -->|"uses portal"| node_admin
node_attendance -->|"tracks learning"| node_learning
node_learning -->|"measures skills"| node_assessment
node_assessment -->|"informs diagnosis"| node_skill_gap
node_skill_gap -->|"guides remediation"| node_remedial
node_remedial -->|"builds competencies"| node_passport
node_passport -->|"supports matching"| node_matching
node_matching -->|"surfaces candidates"| node_employer_actor
node_employer_actor -->|"reports outcomes"| node_feedback
node_feedback -->|"informs upgrades"| node_curriculum
node_chatbot -.->|"generates guidance"| node_gemini
node_learning -.->|"serves media"| node_storage

click node_trainee "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/app/trainee/courses/page.tsx"
click node_trainer "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/app/trainer/programmes/page.tsx"
click node_employer "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/app/employer/matches/page.tsx"
click node_admin "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/app/admin/dashboard/page.tsx"
click node_auth_ui "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/context/AuthContext.tsx"
click node_api "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/main.py"
click node_auth "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/auth.py"
click node_attendance "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/attendance.py"
click node_learning "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/lms.py"
click node_assessment "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/assessment.py"
click node_passport "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/skill_passport_service.py"
click node_certificates "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/certificate_service.py"
click node_matching "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/employer_matching_service.py"
click node_skill_gap "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/skill_gap_engine.py"
click node_remedial "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/skill_gap.py"
click node_feedback "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/feedback_analytics.py"
click node_curriculum "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/admin_stats_service.py"
click node_chatbot "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/ai-engine/query.py"
click node_gemini "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/ai-engine/gemini_client.py"
click node_storage "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/storage_service.py"
click node_database "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/database.py"
click node_models "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/models.py"
click node_kiosk "https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/firmware/esp32_kiosk/config.h"

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_trainee,node_trainer,node_employer,node_admin,node_auth_ui toneBlue
class node_api,node_auth,node_attendance,node_learning,node_assessment,node_passport,node_certificates,node_storage,node_database,node_models toneAmber
class node_matching,node_skill_gap,node_remedial,node_feedback,node_curriculum,node_chatbot,node_gemini toneMint
class node_kiosk toneRose
class node_trainee_actor,node_trainer_actor,node_employer_actor,node_admin_actor toneIndigo
```

## Components

### Web Portals

- [Trainee Portal](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/app/trainee/courses/page.tsx): `frontend/src/app/trainee/courses/page.tsx`
- [Trainer Portal](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/app/trainer/programmes/page.tsx): `frontend/src/app/trainer/programmes/page.tsx`
- [Employer Portal](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/app/employer/matches/page.tsx): `frontend/src/app/employer/matches/page.tsx`
- [Admin Portal](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/app/admin/dashboard/page.tsx): `frontend/src/app/admin/dashboard/page.tsx`
- [Session and Access](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`

### API and Domain

- [FastAPI Gateway](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Attendance](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/attendance.py): `backend/app/routers/attendance.py`
- [Courses and LMS](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/lms.py): `backend/app/routers/lms.py`
- [Competency Assessment](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/assessment.py): `backend/app/routers/assessment.py`
- [Skill Passport](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/skill_passport_service.py): `backend/app/services/skill_passport_service.py`
- [Certificates](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/certificate_service.py): `backend/app/services/certificate_service.py`
- [Media Storage](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`
- [Relational Database](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain Models](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/models.py): `backend/app/models.py`

### Skills Intelligence

- [Employer Matching](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/employer_matching_service.py): `backend/app/services/employer_matching_service.py`
- [Skill-Gap Engine](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/skill_gap_engine.py): `backend/app/services/skill_gap_engine.py`
- [Remedial Recommendations](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/routers/skill_gap.py): `backend/app/routers/skill_gap.py`
- [Placement Feedback](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/feedback_analytics.py): `backend/app/services/feedback_analytics.py`
- [Curriculum Intelligence](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/backend/app/services/admin_stats_service.py): `backend/app/services/admin_stats_service.py`
- [Career Guidance RAG](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/ai-engine/query.py): `ai-engine/query.py`
- [Gemini Client](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/ai-engine/gemini_client.py): `ai-engine/gemini_client.py`

### Training Edge

- [ESP32 Training Node](https://github.com/rithusona35-cpu/ncct-ecosystem/blob/main/firmware/esp32_kiosk/config.h): `firmware/esp32_kiosk/config.h`

### Other components

- **Trainee**
- **Trainer**
- **Employer**
- **Administrator**

## Connections

- FastAPI Gateway → Authentication: routes to (evidence: `backend/app/main.py`)
- FastAPI Gateway → Attendance: routes to (evidence: `backend/app/main.py`)
- FastAPI Gateway → Courses and LMS: routes to (evidence: `backend/app/main.py`)
- FastAPI Gateway → Competency Assessment: routes to (evidence: `backend/app/main.py`)
- Authentication → Relational Database: queries users (evidence: `backend/app/routers/auth.py`)
- Attendance → Relational Database: records attendance (evidence: `backend/app/routers/attendance.py`)
- Courses and LMS → Relational Database: records progress (evidence: `backend/app/routers/lms.py`)
- Competency Assessment → Relational Database: stores results (evidence: `backend/app/routers/assessment.py`)
- Competency Assessment → Certificates: issues (evidence: `backend/app/routers/assessment.py`)
- Certificates → Media Storage: uploads PDFs (evidence: `backend/app/services/certificate_service.py`)
- Skill-Gap Engine → Remedial Recommendations: recommends learning (evidence: `backend/app/routers/skill_gap.py`)
- Employer Matching → Skill-Gap Engine: uses skill scores (evidence: `backend/app/routers/employer.py`)
- Admin Portal → Curriculum Intelligence: views intelligence (evidence: `frontend/src/app/admin/dashboard/page.tsx`)
- Curriculum Intelligence → Placement Feedback: aggregates feedback (evidence: `backend/app/services/admin_stats_service.py`)
- Session and Access → Authentication: verifies session (evidence: `frontend/src/context/AuthContext.tsx`)
- Trainee → ESP32 Training Node: scans badge (evidence: `README.md`)
- ESP32 Training Node → Attendance: syncs attendance (evidence: `README.md`)
- Trainee → Trainee Portal: uses portal (evidence: `README.md`)
- Trainer → Trainer Portal: uses portal (evidence: `README.md`)
- Employer → Employer Portal: uses portal (evidence: `README.md`)
- Administrator → Admin Portal: uses portal (evidence: `README.md`)
- Attendance → Courses and LMS: tracks learning (evidence: `README.md`)
- Courses and LMS → Competency Assessment: measures skills (evidence: `README.md`)
- Competency Assessment → Skill-Gap Engine: informs diagnosis (evidence: `README.md`)
- Skill-Gap Engine → Remedial Recommendations: guides remediation (evidence: `README.md`)
- Remedial Recommendations → Skill Passport: builds competencies (evidence: `README.md`)
- Skill Passport → Employer Matching: supports matching (evidence: `README.md`)
- Employer Matching → Employer: surfaces candidates (evidence: `README.md`)
- Employer → Placement Feedback: reports outcomes (evidence: `README.md`)
- Placement Feedback → Curriculum Intelligence: informs upgrades (evidence: `README.md`)
- Career Guidance RAG → Gemini Client: generates guidance
- Courses and LMS → Media Storage: serves media
