# lisenhuang/bantera-backend architecture

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

- Interactive diagram: https://gitdiagram.com/lisenhuang/bantera-backend
- Repository: https://github.com/lisenhuang/bantera-backend

## Overview

Bantera is a .NET REST API for a language-learning platform. Users authenticate, manage profiles and videos, and generate AI practice audio; administrators manage platform operations and inspect generation diagnostics. The API also provides chat and an MCP interface. The graph preserves these documented product branches. Some source excerpts are partial, so unsampled internal call relationships are omitted unless documented in the README or supported by the SOURCE INDEX.

Main entry points: [`BanteraApi/Program.cs`](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Program.cs) (REST API routes), [`BanteraApi/Database/AppDbContext.cs`](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Database/AppDbContext.cs) (PostgreSQL data), [`BanteraApi/Gemini/GeminiService.cs`](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Gemini/GeminiService.cs) (Dialogue and speech), [`BanteraApi/Chat/ChatService.cs`](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Chat/ChatService.cs) (Chat service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and accounts"]
  node_auth["Authentication<br/>[AuthService.cs]"]
  node_profile["Profile and avatars<br/>[ProfileService.cs]"]
  node_account["Account deletion"]
end

subgraph group_learning["Learning content"]
  node_videos["Video management<br/>[VideoService.cs]"]
  node_storage["Object storage"]
end

subgraph group_ai_audio["AI audio generation"]
  node_gemini["Dialogue and speech<br/>[GeminiService.cs]"]
  node_duration["Duration planning"]
  node_alignment["Word alignment"]
  node_timing["Audio timing"]
  node_diagnostics["Pipeline diagnostics"]
end

subgraph group_community["Chat and activity"]
  node_chat["Chat service<br/>[ChatService.cs]"]
  node_realtime["Realtime chat"]
  node_push["Push notifications"]
  node_activity["User activity"]
end

subgraph group_operations["Admin and integrations"]
  node_mcp["MCP tools and OAuth<br/>[McpEndpoints.cs]"]
  node_admin_ops["Admin operations<br/>[AdminService.cs]"]
  node_database[("PostgreSQL data<br/>[AppDbContext.cs]")]
end

node_user(("Platform user"))
node_admin(("Administrator"))
node_api["REST API routes<br/>[Program.cs]"]
node_gemini_provider{{"Google Gemini"}}
node_revai_provider{{"Rev.ai"}}
node_r2_provider[("Cloudflare R2")]

node_user -->|"uses"| node_api
node_admin -->|"uses"| node_api
node_api -->|"routes auth"| node_auth
node_api -->|"routes video requests"| node_videos
node_api -->|"routes profile requests"| node_profile
node_api -->|"routes deletion"| node_account
node_api -->|"starts generation"| node_gemini
node_api -.->|"routes chat"| node_chat
node_api -.->|"routes MCP"| node_mcp
node_api -->|"routes admin"| node_admin_ops
node_auth -->|"reads and writes"| node_database
node_auth -->|"sets new avatar"| node_profile
node_videos -->|"reads and writes"| node_database
node_videos -->|"stores media"| node_storage
node_storage -->|"stores objects"| node_r2_provider
node_gemini -->|"requests dialogue and speech"| node_gemini_provider
node_gemini -.->|"plans duration"| node_duration
node_gemini -->|"tries alignment"| node_alignment
node_gemini -->|"records events"| node_diagnostics
node_alignment -->|"requests alignment"| node_revai_provider
node_timing -.->|"requests timing"| node_gemini_provider
node_chat -->|"reads and writes"| node_database
node_chat -->|"publishes updates"| node_realtime
node_chat -->|"sends notifications"| node_push
node_push -.->|"reads push tokens"| node_database
node_activity -.->|"records activity"| node_database
node_mcp -.->|"accesses app data"| node_database
node_admin_ops -.->|"manages records"| node_database
node_diagnostics -->|"writes events"| node_database
node_account -->|"deletes records"| node_database
node_account -->|"deletes user objects"| node_storage

click node_api "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Program.cs"
click node_auth "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Auth/AuthService.cs"
click node_profile "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Profile/ProfileService.cs"
click node_account "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Account/AccountDeletionService.cs"
click node_videos "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Videos/VideoService.cs"
click node_storage "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Storage/R2StorageService.cs"
click node_gemini "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Gemini/GeminiService.cs"
click node_duration "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Gemini/HistoricalDialogueDurationPlanner.cs"
click node_alignment "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/RevAi/RevAiAlignmentService.cs"
click node_timing "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Gemini/AiAudioTimingService.cs"
click node_diagnostics "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/AiAudioDiagnostics/AiPipelineEventRecorder.cs"
click node_chat "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Chat/ChatService.cs"
click node_realtime "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Chat/ChatRealtimeService.cs"
click node_push "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Chat/ChatPushNotificationService.cs"
click node_activity "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Activity/UserActivityRecorder.cs"
click node_mcp "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Mcp/McpEndpoints.cs"
click node_admin_ops "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Admin/AdminService.cs"
click node_database "https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Database/AppDbContext.cs"

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_auth,node_profile,node_account,node_user toneBlue
class node_videos,node_storage,node_r2_provider toneAmber
class node_gemini,node_duration,node_alignment,node_timing,node_diagnostics,node_api toneMint
class node_chat,node_realtime,node_push,node_activity toneRose
class node_mcp,node_admin_ops,node_database,node_admin,node_gemini_provider,node_revai_provider toneIndigo
```

## Components

### Identity and accounts

- [Authentication](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Auth/AuthService.cs): `BanteraApi/Auth/AuthService.cs`
- [Profile and avatars](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Profile/ProfileService.cs): `BanteraApi/Profile/ProfileService.cs`
- [Account deletion](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Account/AccountDeletionService.cs): `BanteraApi/Account/AccountDeletionService.cs`

### Learning content

- [Video management](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Videos/VideoService.cs): `BanteraApi/Videos/VideoService.cs`
- [Object storage](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Storage/R2StorageService.cs): `BanteraApi/Storage/R2StorageService.cs`

### AI audio generation

- [Dialogue and speech](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Gemini/GeminiService.cs): `BanteraApi/Gemini/GeminiService.cs`
- [Duration planning](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Gemini/HistoricalDialogueDurationPlanner.cs): `BanteraApi/Gemini/HistoricalDialogueDurationPlanner.cs`
- [Word alignment](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/RevAi/RevAiAlignmentService.cs): `BanteraApi/RevAi/RevAiAlignmentService.cs`
- [Audio timing](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Gemini/AiAudioTimingService.cs): `BanteraApi/Gemini/AiAudioTimingService.cs`
- [Pipeline diagnostics](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/AiAudioDiagnostics/AiPipelineEventRecorder.cs): `BanteraApi/AiAudioDiagnostics/AiPipelineEventRecorder.cs`

### Chat and activity

- [Chat service](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Chat/ChatService.cs): `BanteraApi/Chat/ChatService.cs`
- [Realtime chat](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Chat/ChatRealtimeService.cs): `BanteraApi/Chat/ChatRealtimeService.cs`
- [Push notifications](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Chat/ChatPushNotificationService.cs): `BanteraApi/Chat/ChatPushNotificationService.cs`
- [User activity](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Activity/UserActivityRecorder.cs): `BanteraApi/Activity/UserActivityRecorder.cs`

### Admin and integrations

- [MCP tools and OAuth](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Mcp/McpEndpoints.cs): `BanteraApi/Mcp/McpEndpoints.cs`
- [Admin operations](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Admin/AdminService.cs): `BanteraApi/Admin/AdminService.cs`
- [PostgreSQL data](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Database/AppDbContext.cs): `BanteraApi/Database/AppDbContext.cs`

### Other components

- **Platform user**
- **Administrator**
- [REST API routes](https://github.com/lisenhuang/bantera-backend/blob/main/BanteraApi/Program.cs): `BanteraApi/Program.cs`
- **Google Gemini**
- **Rev.ai**
- **Cloudflare R2**

## Connections

- Platform user → REST API routes: uses (evidence: `README.md`)
- Administrator → REST API routes: uses (evidence: `README.md`)
- REST API routes → Authentication: routes auth (evidence: `README.md`)
- REST API routes → Video management: routes video requests (evidence: `README.md`)
- REST API routes → Profile and avatars: routes profile requests (evidence: `BanteraApi/Program.cs`)
- REST API routes → Account deletion: routes deletion (evidence: `BanteraApi/Program.cs`)
- REST API routes → Dialogue and speech: starts generation (evidence: `README.md`)
- REST API routes → Chat service: routes chat (evidence: `BanteraApi/Program.cs`)
- REST API routes → MCP tools and OAuth: routes MCP
- REST API routes → Admin operations: routes admin (evidence: `README.md`)
- Authentication → PostgreSQL data: reads and writes (evidence: `BanteraApi/Auth/AuthService.cs`)
- Authentication → Profile and avatars: sets new avatar (evidence: `BanteraApi/Auth/AuthService.cs`)
- Video management → PostgreSQL data: reads and writes (evidence: `BanteraApi/Videos/VideoService.cs`)
- Video management → Object storage: stores media (evidence: `BanteraApi/Videos/VideoService.cs`)
- Object storage → Cloudflare R2: stores objects (evidence: `BanteraApi/Storage/R2StorageService.cs`)
- Dialogue and speech → Google Gemini: requests dialogue and speech (evidence: `BanteraApi/Gemini/GeminiService.cs`)
- Dialogue and speech → Duration planning: plans duration
- Dialogue and speech → Word alignment: tries alignment (evidence: `README.md`)
- Dialogue and speech → Pipeline diagnostics: records events (evidence: `BanteraApi/Gemini/GeminiService.cs`)
- Word alignment → Rev.ai: requests alignment (evidence: `BanteraApi/RevAi/RevAiAlignmentService.cs`)
- Audio timing → Google Gemini: requests timing
- Chat service → PostgreSQL data: reads and writes (evidence: `BanteraApi/Chat/ChatService.cs`)
- Chat service → Realtime chat: publishes updates (evidence: `BanteraApi/Chat/ChatService.cs`)
- Chat service → Push notifications: sends notifications (evidence: `BanteraApi/Chat/ChatService.cs`)
- Push notifications → PostgreSQL data: reads push tokens
- User activity → PostgreSQL data: records activity
- MCP tools and OAuth → PostgreSQL data: accesses app data
- Admin operations → PostgreSQL data: manages records
- Pipeline diagnostics → PostgreSQL data: writes events (evidence: `BanteraApi/AiAudioDiagnostics/AiPipelineEventRecorder.cs`)
- Account deletion → PostgreSQL data: deletes records (evidence: `BanteraApi/Account/AccountDeletionService.cs`)
- Account deletion → Object storage: deletes user objects (evidence: `BanteraApi/Account/AccountDeletionService.cs`)
