# si-mong/podium architecture

> Architecture diagram of the GitHub repository si-mong/podium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/si-mong/podium
- Repository: https://github.com/si-mong/podium

## Overview

Podium is an AI presentation-coaching service: users manage projects, upload or record practice sessions, receive voice and motion analysis, review feedback by semantic segment, and compare practice rounds. The graph focuses on the documented production API and analysis workflow. Sampled source confirms session orchestration, file handling, and persistence; some pipeline internals and frontend behavior are not shown, so uncertain implementation links are omitted.

Main entry points: [`backend/app/api/sessions.py`](https://github.com/si-mong/podium/blob/main/backend/app/api/sessions.py) (Session API), [`backend/app/main.py`](https://github.com/si-mong/podium/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/core/database.py`](https://github.com/si-mong/podium/blob/main/backend/app/core/database.py) (Relational database), [`backend/app/pipeline/step2_video_analysis.py`](https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step2_video_analysis.py) (Motion and VLM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_web["Web app<br/>[page.tsx]"]
end

subgraph group_api["API and sessions"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Account access<br/>[auth.py]"]
  node_projects["Project API<br/>[projects.py]"]
  node_sessions["Session API<br/>[sessions.py]"]
  node_schemas["API schemas<br/>[session.py]"]
end

subgraph group_analysis["Presentation analysis"]
  node_preprocess["Media preprocessing"]
  node_voice["Voice and STT"]
  node_voice_tools["Voice analysis tools<br/>[analyze.py]"]
  node_video["Motion and VLM"]
  node_chunking["Smart chunking<br/>[step2_chunking.py]"]
  node_segments["Semantic segments"]
  node_aggregation["Segment metrics<br/>[step4_aggregate.py]"]
end

subgraph group_data["Persistence"]
  node_files["Session files<br/>[storage.py]"]
  node_db[("Relational database<br/>[database.py]")]
  node_models["Domain records<br/>[session.py]"]
end

node_presenter(("Presenter"))
node_stt_service{{"Speech recognition"}}
node_vlm_service{{"Vision model"}}

node_presenter -->|"uses"| node_web
node_web -->|"requests API"| node_app
node_app -->|"dispatches"| node_auth
node_app -->|"dispatches"| node_projects
node_app -->|"dispatches"| node_sessions
node_sessions -->|"formats responses"| node_schemas
node_sessions -->|"stores media"| node_files
node_sessions -->|"runs preprocessing"| node_preprocess
node_preprocess -->|"reads and writes"| node_files
node_sessions -->|"runs motion analysis"| node_video
node_video -->|"plans chunks"| node_chunking
node_video -.->|"analyzes video"| node_vlm_service
node_sessions -->|"runs voice analysis"| node_voice
node_voice -->|"uses analysis"| node_voice_tools
node_voice_tools -.->|"transcribes speech"| node_stt_service
node_sessions -->|"runs segmentation"| node_segments
node_sessions -->|"aggregates segment metrics"| node_aggregation
node_sessions -->|"reads and writes"| node_db
node_auth -->|"reads and writes"| node_db
node_projects -->|"reads and writes"| node_db
node_db -->|"persists"| node_models

click node_web "https://github.com/si-mong/podium/blob/main/frontend/src/app/page.tsx"
click node_app "https://github.com/si-mong/podium/blob/main/backend/app/main.py"
click node_auth "https://github.com/si-mong/podium/blob/main/backend/app/api/auth.py"
click node_projects "https://github.com/si-mong/podium/blob/main/backend/app/api/projects.py"
click node_sessions "https://github.com/si-mong/podium/blob/main/backend/app/api/sessions.py"
click node_schemas "https://github.com/si-mong/podium/blob/main/backend/app/schemas/session.py"
click node_files "https://github.com/si-mong/podium/blob/main/backend/app/services/storage.py"
click node_preprocess "https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step1_preprocess.py"
click node_voice "https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step3_voice_analysis.py"
click node_voice_tools "https://github.com/si-mong/podium/blob/main/backend/app/pipeline/voice/analyze.py"
click node_video "https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step2_video_analysis.py"
click node_chunking "https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step2_chunking.py"
click node_segments "https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step4_segmentation.py"
click node_aggregation "https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step4_aggregate.py"
click node_db "https://github.com/si-mong/podium/blob/main/backend/app/core/database.py"
click node_models "https://github.com/si-mong/podium/blob/main/backend/app/models/session.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_web toneBlue
class node_app,node_auth,node_projects,node_sessions,node_schemas toneAmber
class node_preprocess,node_voice,node_voice_tools,node_video,node_chunking,node_segments,node_aggregation toneMint
class node_files,node_db,node_models toneRose
class node_presenter,node_stt_service,node_vlm_service toneIndigo
```

## Components

### Client

- [Web app](https://github.com/si-mong/podium/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`

### API and sessions

- [FastAPI app](https://github.com/si-mong/podium/blob/main/backend/app/main.py): `backend/app/main.py`
- [Account access](https://github.com/si-mong/podium/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Project API](https://github.com/si-mong/podium/blob/main/backend/app/api/projects.py): `backend/app/api/projects.py`
- [Session API](https://github.com/si-mong/podium/blob/main/backend/app/api/sessions.py): `backend/app/api/sessions.py`
- [API schemas](https://github.com/si-mong/podium/blob/main/backend/app/schemas/session.py): `backend/app/schemas/session.py`

### Presentation analysis

- [Media preprocessing](https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step1_preprocess.py): `backend/app/pipeline/step1_preprocess.py`
- [Voice and STT](https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step3_voice_analysis.py): `backend/app/pipeline/step3_voice_analysis.py`
- [Voice analysis tools](https://github.com/si-mong/podium/blob/main/backend/app/pipeline/voice/analyze.py): `backend/app/pipeline/voice/analyze.py`
- [Motion and VLM](https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step2_video_analysis.py): `backend/app/pipeline/step2_video_analysis.py`
- [Smart chunking](https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step2_chunking.py): `backend/app/pipeline/step2_chunking.py`
- [Semantic segments](https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step4_segmentation.py): `backend/app/pipeline/step4_segmentation.py`
- [Segment metrics](https://github.com/si-mong/podium/blob/main/backend/app/pipeline/step4_aggregate.py): `backend/app/pipeline/step4_aggregate.py`

### Persistence

- [Session files](https://github.com/si-mong/podium/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`
- [Relational database](https://github.com/si-mong/podium/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Domain records](https://github.com/si-mong/podium/blob/main/backend/app/models/session.py): `backend/app/models/session.py`

### Other components

- **Presenter**
- **Speech recognition**
- **Vision model**

## Connections

- Presenter → Web app: uses
- Web app → FastAPI app: requests API
- FastAPI app → Account access: dispatches
- FastAPI app → Project API: dispatches
- FastAPI app → Session API: dispatches
- Session API → API schemas: formats responses
- Session API → Session files: stores media
- Session API → Media preprocessing: runs preprocessing
- Media preprocessing → Session files: reads and writes
- Session API → Motion and VLM: runs motion analysis
- Motion and VLM → Smart chunking: plans chunks
- Motion and VLM → Vision model: analyzes video
- Session API → Voice and STT: runs voice analysis
- Voice and STT → Voice analysis tools: uses analysis
- Voice analysis tools → Speech recognition: transcribes speech
- Session API → Semantic segments: runs segmentation
- Session API → Segment metrics: aggregates segment metrics
- Session API → Relational database: reads and writes
- Account access → Relational database: reads and writes
- Project API → Relational database: reads and writes
- Relational database → Domain records: persists