# ngaboelyse/ubumweconect architecture

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

- Interactive diagram: https://gitdiagram.com/ngaboelyse/ubumweconect
- Repository: https://github.com/ngaboelyse/ubumweconect

## Overview

Ubumwe Connect is a multilingual social messaging and calling API. Users authenticate and manage profiles, then exchange conversations, files, and real-time events; separate routes support calls and translation. The main app mounts these API and WebSocket entry points, while services provide authentication, translation, voice, files, and notifications over shared persistence. The README is empty, so capabilities are inferred from the backend tree and source index. The Windows files show a native Flutter runner shell, but no application UI source is present.

Main entry points: [`backend/app/main.py`](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/main.py) (API App), [`backend/app/routers/conversations.py`](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/conversations.py) (Conversation Routes), [`backend/app/services/auth_service.py`](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/auth_service.py) (Authentication), [`backend/app/services/translation_service.py`](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/translation_service.py) (Translation Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Runtime"]
  node_main["API App<br/>[main.py]"]
  node_config["Settings<br/>[config.py]"]
  node_database["Database Sessions<br/>[database.py]"]
end

subgraph group_identity["Identity And Profiles"]
  node_user_store[("User Records<br/>[user.py]")]
  node_auth_routes["Auth Routes<br/>[auth.py]"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
  node_auth_guard["Auth Guard<br/>[auth_middleware.py]"]
  node_user_routes["Profile Routes<br/>[users.py]"]
end

subgraph group_communication["Messaging And Calls"]
  node_conversations["Conversation Routes<br/>[conversations.py]"]
  node_chat_store[("Chat Records<br/>[chat.py]")]
  node_websocket_handlers["WebSocket Events<br/>[handlers.py]"]
  node_connection_manager["Connection Manager<br/>[manager.py]"]
  node_call_routes["Call Routes<br/>[calls.py]"]
  node_call_store[("Call Records<br/>[call.py]")]
  node_notifications["Notifications"]
end

subgraph group_language["Language And Media"]
  node_translation_routes["Translation Routes<br/>[translation.py]"]
  node_translation_service["Translation Engine"]
  node_translation_store[("Translation Cache<br/>[translation.py]")]
  node_voice_service["Voice Services<br/>[voice_service.py]"]
  node_file_service["File Storage Service<br/>[file_service.py]"]
end

node_client(("API Client"))
node_openai["OpenAI"]
node_s3[("AWS S3")]
node_windows_runner["Windows Runner<br/>[win32_window.h]"]

node_client -->|"sends requests"| node_main
node_main -->|"configures"| node_config
node_main -->|"starts database"| node_database
node_main -->|"mounts routes"| node_auth_routes
node_main -->|"mounts routes"| node_user_routes
node_main -->|"mounts routes"| node_conversations
node_main -->|"mounts routes"| node_call_routes
node_main -->|"mounts routes"| node_translation_routes
node_main -->|"routes WebSocket"| node_websocket_handlers
node_auth_routes -->|"calls"| node_auth_service
node_auth_routes -->|"uses sessions"| node_database
node_auth_service -->|"queries users"| node_user_store
node_auth_service -->|"uses settings"| node_config
node_auth_service -.->|"uses Firebase auth"| node_openai
node_auth_guard -->|"decodes tokens"| node_auth_service
node_auth_guard -->|"gets sessions"| node_database
node_auth_guard -->|"checks user"| node_user_store
node_user_routes -->|"uploads files"| node_file_service
node_user_routes -->|"reads profiles"| node_user_store
node_conversations -->|"reads and writes"| node_chat_store
node_conversations -->|"translates messages"| node_translation_service
node_conversations -->|"uploads attachments"| node_file_service
node_conversations -->|"sends notifications"| node_notifications
node_conversations -->|"dispatches events"| node_connection_manager
node_websocket_handlers -->|"dispatches events"| node_connection_manager
node_websocket_handlers -->|"validates tokens"| node_auth_service
node_websocket_handlers -->|"updates status"| node_database
node_call_routes -->|"reads and writes"| node_call_store
node_call_routes -->|"sends call signals"| node_connection_manager
node_call_routes -->|"sends notifications"| node_notifications
node_translation_routes -->|"translates text"| node_translation_service
node_translation_routes -->|"handles voice"| node_voice_service
node_translation_service -->|"caches translations"| node_translation_store
node_translation_service -->|"requests translations"| node_openai
node_voice_service -->|"uses translation"| node_translation_service
node_voice_service -->|"uses file service"| node_file_service
node_file_service -->|"uploads and deletes"| node_s3
node_database -->|"reads connection settings"| node_config
node_windows_runner -.->|"hosts app shell"| node_client

click node_main "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/main.py"
click node_config "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/config.py"
click node_database "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/database.py"
click node_user_store "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/models/user.py"
click node_auth_routes "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/auth.py"
click node_auth_service "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/auth_service.py"
click node_auth_guard "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/middleware/auth_middleware.py"
click node_user_routes "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/users.py"
click node_conversations "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/conversations.py"
click node_chat_store "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/models/chat.py"
click node_websocket_handlers "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/websocket/handlers.py"
click node_connection_manager "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/websocket/manager.py"
click node_call_routes "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/calls.py"
click node_call_store "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/models/call.py"
click node_notifications "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/notification_service.py"
click node_translation_routes "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/translation.py"
click node_translation_service "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/translation_service.py"
click node_translation_store "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/models/translation.py"
click node_voice_service "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/voice_service.py"
click node_file_service "https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/file_service.py"
click node_windows_runner "https://github.com/ngaboelyse/ubumweconect/blob/master/frontend/windows/runner/win32_window.h"

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_main,node_config,node_database,node_client toneBlue
class node_user_store,node_auth_routes,node_auth_service,node_auth_guard,node_user_routes,node_s3 toneAmber
class node_conversations,node_chat_store,node_websocket_handlers,node_connection_manager,node_call_routes,node_call_store,node_notifications toneMint
class node_translation_routes,node_translation_service,node_translation_store,node_voice_service,node_file_service toneRose
class node_openai toneIndigo
class node_windows_runner toneTeal
```

## Components

### API Runtime

- [API App](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/main.py): `backend/app/main.py`
- [Settings](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/config.py): `backend/app/config.py`
- [Database Sessions](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/database.py): `backend/app/database.py`

### Identity And Profiles

- [User Records](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/models/user.py): `backend/app/models/user.py`
- [Auth Routes](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Authentication](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Auth Guard](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/middleware/auth_middleware.py): `backend/app/middleware/auth_middleware.py`
- [Profile Routes](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/users.py): `backend/app/routers/users.py`

### Messaging And Calls

- [Conversation Routes](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/conversations.py): `backend/app/routers/conversations.py`
- [Chat Records](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/models/chat.py): `backend/app/models/chat.py`
- [WebSocket Events](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/websocket/handlers.py): `backend/app/websocket/handlers.py`
- [Connection Manager](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/websocket/manager.py): `backend/app/websocket/manager.py`
- [Call Routes](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/calls.py): `backend/app/routers/calls.py`
- [Call Records](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/models/call.py): `backend/app/models/call.py`
- [Notifications](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`

### Language And Media

- [Translation Routes](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/routers/translation.py): `backend/app/routers/translation.py`
- [Translation Engine](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/translation_service.py): `backend/app/services/translation_service.py`
- [Translation Cache](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/models/translation.py): `backend/app/models/translation.py`
- [Voice Services](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/voice_service.py): `backend/app/services/voice_service.py`
- [File Storage Service](https://github.com/ngaboelyse/ubumweconect/blob/master/backend/app/services/file_service.py): `backend/app/services/file_service.py`

### Other components

- **API Client**
- **OpenAI**
- **AWS S3**
- [Windows Runner](https://github.com/ngaboelyse/ubumweconect/blob/master/frontend/windows/runner/win32_window.h): `frontend/windows/runner/win32_window.h`

## Connections

- API Client → API App: sends requests (evidence: `backend/app/main.py`)
- API App → Settings: configures (evidence: `backend/app/main.py`)
- API App → Database Sessions: starts database (evidence: `backend/app/main.py`)
- API App → Auth Routes: mounts routes (evidence: `backend/app/main.py`)
- API App → Profile Routes: mounts routes (evidence: `backend/app/main.py`)
- API App → Conversation Routes: mounts routes (evidence: `backend/app/main.py`)
- API App → Call Routes: mounts routes (evidence: `backend/app/main.py`)
- API App → Translation Routes: mounts routes (evidence: `backend/app/main.py`)
- API App → WebSocket Events: routes WebSocket (evidence: `backend/app/main.py`)
- Auth Routes → Authentication: calls (evidence: `backend/app/routers/auth.py`)
- Auth Routes → Database Sessions: uses sessions (evidence: `backend/app/routers/auth.py`)
- Authentication → User Records: queries users (evidence: `backend/app/services/auth_service.py`)
- Authentication → Settings: uses settings (evidence: `backend/app/services/auth_service.py`)
- Authentication → OpenAI: uses Firebase auth
- Auth Guard → Authentication: decodes tokens (evidence: `backend/app/middleware/auth_middleware.py`)
- Auth Guard → Database Sessions: gets sessions (evidence: `backend/app/middleware/auth_middleware.py`)
- Auth Guard → User Records: checks user (evidence: `backend/app/middleware/auth_middleware.py`)
- Profile Routes → File Storage Service: uploads files (evidence: `backend/app/routers/users.py`)
- Profile Routes → User Records: reads profiles (evidence: `backend/app/routers/users.py`)
- Conversation Routes → Chat Records: reads and writes (evidence: `backend/app/routers/conversations.py`)
- Conversation Routes → Translation Engine: translates messages (evidence: `backend/app/routers/conversations.py`)
- Conversation Routes → File Storage Service: uploads attachments (evidence: `backend/app/routers/conversations.py`)
- Conversation Routes → Notifications: sends notifications (evidence: `backend/app/routers/conversations.py`)
- Conversation Routes → Connection Manager: dispatches events (evidence: `backend/app/routers/conversations.py`)
- WebSocket Events → Connection Manager: dispatches events (evidence: `backend/app/websocket/handlers.py`)
- WebSocket Events → Authentication: validates tokens (evidence: `backend/app/websocket/handlers.py`)
- WebSocket Events → Database Sessions: updates status (evidence: `backend/app/websocket/handlers.py`)
- Call Routes → Call Records: reads and writes (evidence: `backend/app/routers/calls.py`)
- Call Routes → Connection Manager: sends call signals (evidence: `backend/app/routers/calls.py`)
- Call Routes → Notifications: sends notifications (evidence: `backend/app/routers/calls.py`)
- Translation Routes → Translation Engine: translates text (evidence: `backend/app/routers/translation.py`)
- Translation Routes → Voice Services: handles voice (evidence: `backend/app/routers/translation.py`)
- Translation Engine → Translation Cache: caches translations (evidence: `backend/app/services/translation_service.py`)
- Translation Engine → OpenAI: requests translations (evidence: `backend/app/services/translation_service.py`)
- Voice Services → Translation Engine: uses translation (evidence: `backend/app/services/voice_service.py`)
- Voice Services → File Storage Service: uses file service (evidence: `backend/app/services/voice_service.py`)
- File Storage Service → AWS S3: uploads and deletes (evidence: `backend/app/services/file_service.py`)
- Database Sessions → Settings: reads connection settings (evidence: `backend/app/database.py`)
- Windows Runner → API Client: hosts app shell
