# ashwikha/communication-readiness-platform architecture

> Architecture diagram of the GitHub repository ashwikha/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/ashwikha/communication-readiness-platform
- Repository: https://github.com/ashwikha/communication-readiness-platform

## Overview

LatchUp is a communication-readiness and learning platform: students use role-specific portals to complete mock interviews, listening activities, and assessments, while staff manage programs, placements, and student progress. The backend handles sessions, evaluation, credits, and placement workflows; a Python AI service provides interview and learning endpoints plus agent-based capabilities. The source index supports several module relationships, but the README is empty and many product areas were not excerpted, so unverified links are omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/App.tsx) (Application shell), [`ai-service/app/main.py`](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/main.py) (AI API), [`backend/src/services/llmEvaluationService.ts`](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/services/llmEvaluationService.ts) (Streaming AI evaluation), [`backend/src/index.ts`](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/index.ts) (Backend API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Application shell<br/>[App.tsx]"]
  node_context["App state<br/>[AppContext.tsx]"]
  node_api["Frontend API client<br/>[api.ts]"]
  node_dashboard["Student dashboard"]
  node_interviewroom["Mock interview"]
  node_listeningroom["Listening room<br/>[ListeningRoom.tsx]"]
  node_reports["Diagnostic reports"]
  node_adminportal["Department administration"]
  node_ownerportal["Platform administration"]
  node_superportal["Super administration"]
  node_classes["Class management"]
end

subgraph group_platform["Platform workflows"]
  node_backend["Backend API<br/>[index.ts]"]
  node_routes["Route registry<br/>[index.ts]"]
  node_sessions["Interview sessions<br/>[sessions.routes.ts]"]
  node_attempts["Assessment attempts<br/>[attempts.routes.ts]"]
  node_responses["Response evaluation"]
  node_placement["Placement eligibility"]
  node_credits["Credit management<br/>[credits.service.ts]"]
  node_learningroutes["Learning routes<br/>[learning.routes.ts]"]
  node_llmevaluation["Streaming AI evaluation"]
  node_events["Domain events<br/>[events.ts]"]
end

subgraph group_ai["AI services"]
  node_aiservice["AI API<br/>[main.py]"]
  node_interviewapi["Interview endpoints<br/>[interview.py]"]
  node_learningapi["AI learning endpoints<br/>[learning.py]"]
  node_agentapi["Agent endpoints<br/>[agent.py]"]
  node_agentrunner["Agent runner<br/>[agent_runner.py]"]
  node_llmclient["LLM client<br/>[llm_client.py]"]
end

subgraph group_state["State and persistence"]
  node_agentrepo["Agent run repository"]
  node_database[("Shared PostgreSQL<br/>[connection.py]")]
  node_cache["Backend cache<br/>[cacheService.ts]"]
  node_redis["Redis cache<br/>[cache_service.py]"]
end

node_user(("Students and staff"))

node_user -->|"uses"| node_app
node_app -->|"provides state"| node_context
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_interviewroom
node_app -->|"routes to"| node_listeningroom
node_app -->|"routes to"| node_reports
node_app -->|"routes to"| node_adminportal
node_app -->|"routes to"| node_ownerportal
node_app -->|"routes to"| node_superportal
node_context -->|"calls"| node_api
node_adminportal -.->|"manages"| node_classes
node_backend -.->|"registers"| node_routes
node_sessions -->|"uses evaluation"| node_llmevaluation
node_responses -.->|"evaluates responses"| node_llmevaluation
node_llmevaluation -->|"posts evaluation"| node_aiservice
node_attempts -->|"uses credits"| node_credits
node_sessions -.->|"publishes or reads"| node_events
node_placement -.->|"checks eligibility"| node_credits
node_learningroutes -.->|"requests AI"| node_aiservice
node_aiservice -->|"mounts"| node_interviewapi
node_aiservice -->|"mounts"| node_learningapi
node_aiservice -->|"mounts"| node_agentapi
node_agentapi -->|"calls"| node_agentrunner
node_agentrunner -->|"persists runs"| node_agentrepo
node_agentrepo -->|"queries"| node_database
node_interviewapi -->|"uses"| node_llmclient
node_learningapi -.->|"uses"| node_llmclient
node_backend -.->|"uses cache"| node_cache
node_aiservice -->|"initializes"| node_redis

click node_app "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/App.tsx"
click node_context "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/context/AppContext.tsx"
click node_api "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/services/api.ts"
click node_dashboard "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/student/StudentDashboard.tsx"
click node_interviewroom "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/student/MockInterviewRoom.tsx"
click node_listeningroom "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/student/ListeningRoom.tsx"
click node_reports "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/student/DiagnosticReportView.tsx"
click node_adminportal "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/portals/DepartmentAdminPortal.tsx"
click node_ownerportal "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/portals/PlatformOwnerPortal.tsx"
click node_superportal "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/portals/SuperAdminPortal.tsx"
click node_classes "https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/common/DepartmentClassesManager.tsx"
click node_backend "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/index.ts"
click node_routes "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/routes/index.ts"
click node_sessions "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/sessions/sessions.routes.ts"
click node_attempts "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/attempts/attempts.routes.ts"
click node_responses "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/responses/responses.routes.ts"
click node_placement "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/placement/eligibility.service.ts"
click node_credits "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/credits/credits.service.ts"
click node_learningroutes "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/routes/learning.routes.ts"
click node_llmevaluation "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/services/llmEvaluationService.ts"
click node_events "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/shared/events/events.ts"
click node_aiservice "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/main.py"
click node_interviewapi "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/routers/interview.py"
click node_learningapi "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/routers/learning.py"
click node_agentapi "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/routers/agent.py"
click node_agentrunner "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/agents/agent_runner.py"
click node_llmclient "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/services/llm_client.py"
click node_agentrepo "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/repositories/agent_repository.py"
click node_database "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/database/connection.py"
click node_cache "https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/services/cacheService.ts"
click node_redis "https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/cache/cache_service.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_context,node_api,node_dashboard,node_interviewroom,node_listeningroom,node_reports,node_adminportal,node_ownerportal,node_superportal,node_classes toneBlue
class node_backend,node_routes,node_sessions,node_attempts,node_responses,node_placement,node_credits,node_learningroutes,node_llmevaluation,node_events toneAmber
class node_aiservice,node_interviewapi,node_learningapi,node_agentapi,node_agentrunner,node_llmclient toneMint
class node_agentrepo,node_database,node_cache,node_redis toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Application shell](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [App state](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/context/AppContext.tsx): `frontend/src/context/AppContext.tsx`
- [Frontend API client](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Student dashboard](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/student/StudentDashboard.tsx): `frontend/src/components/student/StudentDashboard.tsx`
- [Mock interview](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/student/MockInterviewRoom.tsx): `frontend/src/components/student/MockInterviewRoom.tsx`
- [Listening room](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/student/ListeningRoom.tsx): `frontend/src/components/student/ListeningRoom.tsx`
- [Diagnostic reports](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/student/DiagnosticReportView.tsx): `frontend/src/components/student/DiagnosticReportView.tsx`
- [Department administration](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/portals/DepartmentAdminPortal.tsx): `frontend/src/components/portals/DepartmentAdminPortal.tsx`
- [Platform administration](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/portals/PlatformOwnerPortal.tsx): `frontend/src/components/portals/PlatformOwnerPortal.tsx`
- [Super administration](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/portals/SuperAdminPortal.tsx): `frontend/src/components/portals/SuperAdminPortal.tsx`
- [Class management](https://github.com/ashwikha/communication-readiness-platform/blob/main/frontend/src/components/common/DepartmentClassesManager.tsx): `frontend/src/components/common/DepartmentClassesManager.tsx`

### Platform workflows

- [Backend API](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Route registry](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/routes/index.ts): `backend/src/routes/index.ts`
- [Interview sessions](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/sessions/sessions.routes.ts): `backend/src/modules/sessions/sessions.routes.ts`
- [Assessment attempts](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/attempts/attempts.routes.ts): `backend/src/modules/attempts/attempts.routes.ts`
- [Response evaluation](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/responses/responses.routes.ts): `backend/src/modules/responses/responses.routes.ts`
- [Placement eligibility](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/placement/eligibility.service.ts): `backend/src/modules/placement/eligibility.service.ts`
- [Credit management](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/modules/credits/credits.service.ts): `backend/src/modules/credits/credits.service.ts`
- [Learning routes](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/routes/learning.routes.ts): `backend/src/routes/learning.routes.ts`
- [Streaming AI evaluation](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/services/llmEvaluationService.ts): `backend/src/services/llmEvaluationService.ts`
- [Domain events](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/shared/events/events.ts): `backend/src/shared/events/events.ts`

### AI services

- [AI API](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/main.py): `ai-service/app/main.py`
- [Interview endpoints](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/routers/interview.py): `ai-service/app/routers/interview.py`
- [AI learning endpoints](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/routers/learning.py): `ai-service/app/routers/learning.py`
- [Agent endpoints](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/routers/agent.py): `ai-service/app/routers/agent.py`
- [Agent runner](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/agents/agent_runner.py): `ai-service/app/agents/agent_runner.py`
- [LLM client](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/services/llm_client.py): `ai-service/app/services/llm_client.py`

### State and persistence

- [Agent run repository](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/repositories/agent_repository.py): `ai-service/app/repositories/agent_repository.py`
- [Shared PostgreSQL](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/database/connection.py): `ai-service/app/database/connection.py`
- [Backend cache](https://github.com/ashwikha/communication-readiness-platform/blob/main/backend/src/services/cacheService.ts): `backend/src/services/cacheService.ts`
- [Redis cache](https://github.com/ashwikha/communication-readiness-platform/blob/main/ai-service/app/cache/cache_service.py): `ai-service/app/cache/cache_service.py`

### Other components

- **Students and staff**

## Connections

- Students and staff → Application shell: uses
- Application shell → App state: provides state (evidence: `frontend/src/App.tsx`)
- Application shell → Student dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Mock interview: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Listening room: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Diagnostic reports: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Department administration: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Platform administration: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Super administration: routes to (evidence: `frontend/src/App.tsx`)
- App state → Frontend API client: calls (evidence: `frontend/src/context/AppContext.tsx`)
- Department administration → Class management: manages
- Backend API → Route registry: registers
- Interview sessions → Streaming AI evaluation: uses evaluation (evidence: `backend/src/modules/sessions/sessions.routes.ts`)
- Response evaluation → Streaming AI evaluation: evaluates responses
- Streaming AI evaluation → AI API: posts evaluation (evidence: `backend/src/services/llmEvaluationService.ts`)
- Assessment attempts → Credit management: uses credits (evidence: `backend/src/modules/attempts/attempts.routes.ts`)
- Interview sessions → Domain events: publishes or reads (evidence: `backend/src/modules/sessions/sessions.routes.ts`)
- Placement eligibility → Credit management: checks eligibility
- Learning routes → AI API: requests AI
- AI API → Interview endpoints: mounts (evidence: `ai-service/app/main.py`)
- AI API → AI learning endpoints: mounts (evidence: `ai-service/app/main.py`)
- AI API → Agent endpoints: mounts (evidence: `ai-service/app/main.py`)
- Agent endpoints → Agent runner: calls (evidence: `ai-service/app/routers/agent.py`)
- Agent runner → Agent run repository: persists runs (evidence: `ai-service/app/agents/agent_runner.py`)
- Agent run repository → Shared PostgreSQL: queries (evidence: `ai-service/app/repositories/agent_repository.py`)
- Interview endpoints → LLM client: uses (evidence: `ai-service/app/routers/interview.py`)
- AI learning endpoints → LLM client: uses
- Backend API → Backend cache: uses cache
- AI API → Redis cache: initializes (evidence: `ai-service/app/main.py`)
