# sanjanagadamsetty/placement-communication-readiness-platform architecture

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

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

## Overview

This repository combines a student-facing placement-readiness platform with a TypeScript API and a Python AI service. The main documented journey is: students enter the portal, complete voice interview or listening practice, and review readiness feedback; staff portals manage cohorts and mentor-verified checklists. The API also implements assessment sessions, evaluation, credits, and eligibility, while the AI service provides agent and learning endpoints. Some links reflect README descriptions or source-index references rather than inspected implementation; those limits are noted by omitting uncertain connections.

Main entry points: [`frontend/src/App.tsx`](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/App.tsx) (App Router), [`ai-service/app/main.py`](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/main.py) (AI Service API), [`backend/src/config/database.ts`](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/config/database.ts) (Platform Database), [`backend/src/modules/sessions/sessions.routes.ts`](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/sessions/sessions.routes.ts) (Assessment Sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Student and Staff UI"]
  node_app["App Router<br/>[App.tsx]"]
  node_app_state["App State<br/>[AppContext.tsx]"]
  node_student_home["Student Dashboard"]
  node_interview_room["Mock Interview"]
  node_listening_room["Listening Room<br/>[ListeningRoom.tsx]"]
  node_diagnostic["Diagnostic Report"]
  node_staff_portals["Staff Portals"]
  node_frontend_api["Frontend API Client<br/>[api.ts]"]
end

subgraph group_backend["Platform API"]
  node_auth["Authentication<br/>[authenticate.ts]"]
  node_sessions["Assessment Sessions<br/>[sessions.routes.ts]"]
  node_responses["Responses and Scoring"]
  node_checklist["Mentor Checklist"]
  node_eligibility["Placement Eligibility"]
  node_credits["Credits<br/>[credits.service.ts]"]
  node_question_bank["Question Bank"]
end

subgraph group_ai["AI Service"]
  node_ai_entry["AI Service API<br/>[main.py]"]
  node_agent_api["Agent Endpoints<br/>[agent.py]"]
  node_learning_api["Learning Endpoints<br/>[learning.py]"]
  node_llm_client["LLM Client<br/>[llm_client.py]"]
  node_agent_runner["Agent Runner<br/>[agent_runner.py]"]
  node_ai_queue["Agent Job Queue<br/>[queue.py]"]
end

subgraph group_shared["Platform Services"]
  node_database[("Platform Database<br/>[database.ts]")]
end

node_candidate(("Candidate"))

node_candidate -->|"uses portal"| node_app
node_app -->|"provides context"| node_app_state
node_app -->|"routes to"| node_student_home
node_app -->|"routes to"| node_interview_room
node_app -->|"routes to"| node_listening_room
node_app -->|"routes to"| node_diagnostic
node_app -->|"routes to"| node_staff_portals
node_student_home -.->|"starts practice"| node_interview_room
node_student_home -.->|"starts practice"| node_listening_room
node_interview_room -.->|"reviews results"| node_diagnostic
node_app_state -->|"calls"| node_frontend_api
node_candidate -->|"starts assessment"| node_sessions
node_sessions -->|"authenticates with"| node_auth
node_sessions -->|"reads and writes"| node_database
node_sessions -->|"aggregates evaluations"| node_responses
node_responses -->|"reads and writes"| node_database
node_responses -.->|"uses questions"| node_question_bank
node_checklist -->|"checks eligibility"| node_eligibility
node_checklist -->|"reads and writes"| node_database
node_eligibility -->|"queries"| node_database
node_credits -->|"reads and writes"| node_database
node_question_bank -->|"reads and writes"| node_database
node_ai_entry -->|"registers router"| node_agent_api
node_ai_entry -->|"registers router"| node_learning_api
node_ai_entry -->|"initializes"| node_llm_client
node_ai_entry -->|"recovers runs"| node_agent_runner
node_ai_entry -->|"checks queue"| node_ai_queue
node_agent_runner -.->|"requests completions"| node_llm_client

click node_app "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/App.tsx"
click node_app_state "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/context/AppContext.tsx"
click node_student_home "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/components/student/StudentDashboard.tsx"
click node_interview_room "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/components/student/MockInterviewRoom.tsx"
click node_listening_room "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/components/student/ListeningRoom.tsx"
click node_diagnostic "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/components/student/DiagnosticReportView.tsx"
click node_staff_portals "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/tree/main/frontend/src/components/portals"
click node_frontend_api "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/services/api.ts"
click node_auth "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/middleware/authenticate.ts"
click node_sessions "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/sessions/sessions.routes.ts"
click node_responses "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/responses/responses.routes.ts"
click node_checklist "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/checklist/checklist.routes.ts"
click node_eligibility "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/placement/eligibility.service.ts"
click node_credits "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/credits/credits.service.ts"
click node_question_bank "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/question-bank/question-bank.routes.ts"
click node_database "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/config/database.ts"
click node_ai_entry "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/main.py"
click node_agent_api "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/routers/agent.py"
click node_learning_api "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/routers/learning.py"
click node_llm_client "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/services/llm_client.py"
click node_agent_runner "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/agents/agent_runner.py"
click node_ai_queue "https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/workers/queue.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_app_state,node_student_home,node_interview_room,node_listening_room,node_diagnostic,node_staff_portals,node_frontend_api toneBlue
class node_auth,node_sessions,node_responses,node_checklist,node_eligibility,node_credits,node_question_bank toneAmber
class node_ai_entry,node_agent_api,node_learning_api,node_llm_client,node_agent_runner,node_ai_queue toneMint
class node_database toneRose
class node_candidate toneIndigo
```

## Components

### Student and Staff UI

- [App Router](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [App State](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/context/AppContext.tsx): `frontend/src/context/AppContext.tsx`
- [Student Dashboard](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/components/student/StudentDashboard.tsx): `frontend/src/components/student/StudentDashboard.tsx`
- [Mock Interview](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/components/student/MockInterviewRoom.tsx): `frontend/src/components/student/MockInterviewRoom.tsx`
- [Listening Room](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/components/student/ListeningRoom.tsx): `frontend/src/components/student/ListeningRoom.tsx`
- [Diagnostic Report](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/components/student/DiagnosticReportView.tsx): `frontend/src/components/student/DiagnosticReportView.tsx`
- [Staff Portals](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/tree/main/frontend/src/components/portals): `frontend/src/components/portals`
- [Frontend API Client](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Platform API

- [Authentication](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/middleware/authenticate.ts): `backend/src/middleware/authenticate.ts`
- [Assessment Sessions](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/sessions/sessions.routes.ts): `backend/src/modules/sessions/sessions.routes.ts`
- [Responses and Scoring](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/responses/responses.routes.ts): `backend/src/modules/responses/responses.routes.ts`
- [Mentor Checklist](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/checklist/checklist.routes.ts): `backend/src/modules/checklist/checklist.routes.ts`
- [Placement Eligibility](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/placement/eligibility.service.ts): `backend/src/modules/placement/eligibility.service.ts`
- [Credits](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/credits/credits.service.ts): `backend/src/modules/credits/credits.service.ts`
- [Question Bank](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/modules/question-bank/question-bank.routes.ts): `backend/src/modules/question-bank/question-bank.routes.ts`

### AI Service

- [AI Service API](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/main.py): `ai-service/app/main.py`
- [Agent Endpoints](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/routers/agent.py): `ai-service/app/routers/agent.py`
- [Learning Endpoints](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/routers/learning.py): `ai-service/app/routers/learning.py`
- [LLM Client](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/services/llm_client.py): `ai-service/app/services/llm_client.py`
- [Agent Runner](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/agents/agent_runner.py): `ai-service/app/agents/agent_runner.py`
- [Agent Job Queue](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/ai-service/app/workers/queue.py): `ai-service/app/workers/queue.py`

### Platform Services

- [Platform Database](https://github.com/sanjanagadamsetty/placement-communication-readiness-platform/blob/main/backend/src/config/database.ts): `backend/src/config/database.ts`

### Other components

- **Candidate**

## Connections

- Candidate → App Router: uses portal (evidence: `README.md`)
- App Router → App State: provides context (evidence: `frontend/src/App.tsx`)
- App Router → Student Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Mock Interview: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Listening Room: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Diagnostic Report: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Staff Portals: routes to (evidence: `frontend/src/App.tsx`)
- Student Dashboard → Mock Interview: starts practice
- Student Dashboard → Listening Room: starts practice
- Mock Interview → Diagnostic Report: reviews results
- App State → Frontend API Client: calls (evidence: `frontend/src/context/AppContext.tsx`)
- Candidate → Assessment Sessions: starts assessment (evidence: `README.md`)
- Assessment Sessions → Authentication: authenticates with (evidence: `backend/src/modules/sessions/sessions.routes.ts`)
- Assessment Sessions → Platform Database: reads and writes (evidence: `backend/src/modules/sessions/sessions.routes.ts`)
- Assessment Sessions → Responses and Scoring: aggregates evaluations (evidence: `backend/src/modules/sessions/sessions.routes.ts`)
- Responses and Scoring → Platform Database: reads and writes (evidence: `backend/src/modules/responses/responses.routes.ts`)
- Responses and Scoring → Question Bank: uses questions
- Mentor Checklist → Placement Eligibility: checks eligibility (evidence: `backend/src/modules/checklist/checklist.routes.ts`)
- Mentor Checklist → Platform Database: reads and writes (evidence: `backend/src/modules/checklist/checklist.routes.ts`)
- Placement Eligibility → Platform Database: queries (evidence: `backend/src/modules/placement/eligibility.service.ts`)
- Credits → Platform Database: reads and writes (evidence: `backend/src/modules/credits/credits.service.ts`)
- Question Bank → Platform Database: reads and writes (evidence: `backend/src/modules/question-bank/question-bank.routes.ts`)
- AI Service API → Agent Endpoints: registers router (evidence: `ai-service/app/main.py`)
- AI Service API → Learning Endpoints: registers router (evidence: `ai-service/app/main.py`)
- AI Service API → LLM Client: initializes (evidence: `ai-service/app/main.py`)
- AI Service API → Agent Runner: recovers runs (evidence: `ai-service/app/main.py`)
- AI Service API → Agent Job Queue: checks queue (evidence: `ai-service/app/main.py`)
- Agent Runner → LLM Client: requests completions
