# danishbasha/communication-readiness-platform architecture

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

- Interactive diagram: https://gitdiagram.com/danishbasha/communication-readiness-platform
- Repository: https://github.com/danishbasha/communication-readiness-platform

## Overview

This is an institutional communication-readiness platform for college placement preparation. Students use the frontend to practice voice interviews and listening comprehension, receive diagnostic feedback, and track syllabus checklist completion; mentors verify checklist items, while administrators and trainers manage cohorts and readiness. The backend provides institutional APIs and session/evaluation services, with a Python AI service for interview and learning workflows. The README documents additional capabilities and role workflows; some backend and AI internals are unsampled, so their links are omitted unless explicitly evidenced.

Main entry points: [`frontend/src/App.tsx`](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/App.tsx) (Application Router), [`ai-service/app/main.py`](https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/main.py) (AI Service API), [`backend/src/modules/checklist/checklist.routes.ts`](https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/checklist/checklist.routes.ts) (Placement Checklist), [`frontend/src/components/student/MockInterviewRoom.tsx`](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/MockInterviewRoom.tsx) (Voice Interview Room)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Student Experience"]
  node_app["Application Router<br/>[App.tsx]"]
  node_state["Application State<br/>[AppContext.tsx]"]
  node_student_dashboard["Student Dashboard"]
  node_mock_interview["Voice Interview Room"]
  node_listening_room["Listening Room<br/>[ListeningRoom.tsx]"]
  node_diagnostic["Diagnostic Scorecard"]
  node_api["Client API<br/>[api.ts]"]
end

subgraph group_institutional["Institutional Workflows"]
  node_student_portal["Stakeholder Portals"]
  node_mock_data["Cohort Data<br/>[mockData.ts]"]
end

subgraph group_backend["Platform Backend"]
  node_sessions["Assessment Sessions<br/>[sessions.routes.ts]"]
  node_checklist["Placement Checklist"]
  node_eligibility["Placement Eligibility"]
  node_verifications["Mentor Verification"]
  node_evaluation["Live Interview Engine"]
  node_backend_db[("Platform Database<br/>[pool.ts]")]
end

subgraph group_ai["AI Services"]
  node_ai_app["AI Service API<br/>[main.py]"]
  node_ai_interview["Interview Workflows<br/>[interview.py]"]
  node_ai_learning["Learning Workflows<br/>[learning.py]"]
  node_ai_agents["Agent Workflows<br/>[agent.py]"]
  node_ai_llm["LLM Client<br/>[llm_client.py]"]
end

node_student(("Student"))
node_staff(("Institutional Staff"))
node_llm_provider{{"LLM Provider"}}

node_student -->|"uses"| node_app
node_app -->|"renders"| node_student_dashboard
node_app -->|"renders"| node_mock_interview
node_app -->|"renders"| node_listening_room
node_app -->|"renders"| node_diagnostic
node_app -->|"renders"| node_student_portal
node_state -->|"calls"| node_api
node_state -->|"loads"| node_mock_data
node_staff -->|"uses"| node_student_portal
node_student -->|"practices in"| node_mock_interview
node_student -->|"takes test"| node_listening_room
node_mock_interview -->|"produces"| node_diagnostic
node_student -->|"completes"| node_checklist
node_staff -->|"verifies"| node_verifications
node_sessions -->|"reads/writes"| node_backend_db
node_checklist -->|"reads/writes"| node_backend_db
node_checklist -->|"checks"| node_eligibility
node_verifications -->|"checks"| node_eligibility
node_eligibility -->|"queries"| node_backend_db
node_evaluation -->|"requests scoring"| node_ai_app
node_ai_app -->|"registers"| node_ai_interview
node_ai_app -->|"registers"| node_ai_learning
node_ai_app -->|"registers"| node_ai_agents
node_ai_llm -->|"delegates to"| node_llm_provider

click node_app "https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/App.tsx"
click node_state "https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/context/AppContext.tsx"
click node_student_dashboard "https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/StudentDashboard.tsx"
click node_mock_interview "https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/MockInterviewRoom.tsx"
click node_listening_room "https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/ListeningRoom.tsx"
click node_diagnostic "https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/DiagnosticReportView.tsx"
click node_student_portal "https://github.com/danishbasha/communication-readiness-platform/tree/main/frontend/src/components/portals"
click node_mock_data "https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/data/mockData.ts"
click node_api "https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/services/api.ts"
click node_sessions "https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/sessions/sessions.routes.ts"
click node_checklist "https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/checklist/checklist.routes.ts"
click node_eligibility "https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/placement/eligibility.service.ts"
click node_verifications "https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/verifications/verifications.routes.ts"
click node_evaluation "https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/services/llmEvaluationService.ts"
click node_backend_db "https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/shared/db/pool.ts"
click node_ai_app "https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/main.py"
click node_ai_interview "https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/routers/interview.py"
click node_ai_learning "https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/routers/learning.py"
click node_ai_agents "https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/routers/agent.py"
click node_ai_llm "https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/services/llm_client.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_app,node_state,node_student_dashboard,node_mock_interview,node_listening_room,node_diagnostic,node_api toneBlue
class node_student_portal,node_mock_data toneAmber
class node_sessions,node_checklist,node_eligibility,node_verifications,node_evaluation,node_backend_db toneMint
class node_ai_app,node_ai_interview,node_ai_learning,node_ai_agents,node_ai_llm toneRose
class node_student,node_staff,node_llm_provider toneIndigo
```

## Components

### Student Experience

- [Application Router](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Application State](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/context/AppContext.tsx): `frontend/src/context/AppContext.tsx`
- [Student Dashboard](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/StudentDashboard.tsx): `frontend/src/components/student/StudentDashboard.tsx`
- [Voice Interview Room](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/MockInterviewRoom.tsx): `frontend/src/components/student/MockInterviewRoom.tsx`
- [Listening Room](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/ListeningRoom.tsx): `frontend/src/components/student/ListeningRoom.tsx`
- [Diagnostic Scorecard](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/components/student/DiagnosticReportView.tsx): `frontend/src/components/student/DiagnosticReportView.tsx`
- [Client API](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Institutional Workflows

- [Stakeholder Portals](https://github.com/danishbasha/communication-readiness-platform/tree/main/frontend/src/components/portals): `frontend/src/components/portals`
- [Cohort Data](https://github.com/danishbasha/communication-readiness-platform/blob/main/frontend/src/data/mockData.ts): `frontend/src/data/mockData.ts`

### Platform Backend

- [Assessment Sessions](https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/sessions/sessions.routes.ts): `backend/src/modules/sessions/sessions.routes.ts`
- [Placement Checklist](https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/checklist/checklist.routes.ts): `backend/src/modules/checklist/checklist.routes.ts`
- [Placement Eligibility](https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/placement/eligibility.service.ts): `backend/src/modules/placement/eligibility.service.ts`
- [Mentor Verification](https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/modules/verifications/verifications.routes.ts): `backend/src/modules/verifications/verifications.routes.ts`
- [Live Interview Engine](https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/services/llmEvaluationService.ts): `backend/src/services/llmEvaluationService.ts`
- [Platform Database](https://github.com/danishbasha/communication-readiness-platform/blob/main/backend/src/shared/db/pool.ts): `backend/src/shared/db/pool.ts`

### AI Services

- [AI Service API](https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/main.py): `ai-service/app/main.py`
- [Interview Workflows](https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/routers/interview.py): `ai-service/app/routers/interview.py`
- [Learning Workflows](https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/routers/learning.py): `ai-service/app/routers/learning.py`
- [Agent Workflows](https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/routers/agent.py): `ai-service/app/routers/agent.py`
- [LLM Client](https://github.com/danishbasha/communication-readiness-platform/blob/main/ai-service/app/services/llm_client.py): `ai-service/app/services/llm_client.py`

### Other components

- **Student**
- **Institutional Staff**
- **LLM Provider**

## Connections

- Student → Application Router: uses (evidence: `README.md`)
- Application Router → Student Dashboard: renders (evidence: `frontend/src/App.tsx`)
- Application Router → Voice Interview Room: renders (evidence: `frontend/src/App.tsx`)
- Application Router → Listening Room: renders (evidence: `frontend/src/App.tsx`)
- Application Router → Diagnostic Scorecard: renders (evidence: `frontend/src/App.tsx`)
- Application Router → Stakeholder Portals: renders (evidence: `frontend/src/App.tsx`)
- Application State → Client API: calls (evidence: `frontend/src/context/AppContext.tsx`)
- Application State → Cohort Data: loads (evidence: `frontend/src/context/AppContext.tsx`)
- Institutional Staff → Stakeholder Portals: uses (evidence: `README.md`)
- Student → Voice Interview Room: practices in (evidence: `README.md`)
- Student → Listening Room: takes test (evidence: `README.md`)
- Voice Interview Room → Diagnostic Scorecard: produces (evidence: `README.md`)
- Student → Placement Checklist: completes (evidence: `README.md`)
- Institutional Staff → Mentor Verification: verifies (evidence: `README.md`)
- Assessment Sessions → Platform Database: reads/writes (evidence: `backend/src/modules/sessions/sessions.routes.ts`)
- Placement Checklist → Platform Database: reads/writes (evidence: `backend/src/modules/checklist/checklist.routes.ts`)
- Placement Checklist → Placement Eligibility: checks (evidence: `backend/src/modules/checklist/checklist.routes.ts`)
- Mentor Verification → Placement Eligibility: checks (evidence: `backend/src/modules/verifications/verifications.routes.ts`)
- Placement Eligibility → Platform Database: queries (evidence: `backend/src/modules/placement/eligibility.service.ts`)
- Live Interview Engine → AI Service API: requests scoring (evidence: `backend/src/services/llmEvaluationService.ts`)
- AI Service API → Interview Workflows: registers (evidence: `ai-service/app/main.py`)
- AI Service API → Learning Workflows: registers (evidence: `ai-service/app/main.py`)
- AI Service API → Agent Workflows: registers (evidence: `ai-service/app/main.py`)
- LLM Client → LLM Provider: delegates to (evidence: `ai-service/app/services/llm_client.py`)