# norvinka306key/be_blizhe architecture

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

- Interactive diagram: https://gitdiagram.com/norvinka306key/be_blizhe
- Repository: https://github.com/norvinka306key/be_blizhe

## Overview

Riado is a FastAPI backend for a couples app. Its clearest evidenced workflow is a client request entering a registered API route, invoking authentication or calendar services, and accessing PostgreSQL through repositories managed by a per-request Unit of Work. Authentication validates credentials and issues cookie-carried JWTs; the README also documents refresh, logout, and profile retrieval. The tree and router registration establish additional product areas—spaces, ideas, diary, shared todos, tasks, uploads, and realtime—but their internal flows are not fully sampled, so those links are marked unverified where appropriate.

Main entry points: [`main.py`](https://github.com/norvinka306key/be_blizhe/blob/main/main.py) (FastAPI app), [`src/repositories/uow.py`](https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/uow.py) (Unit of Work), [`src/services/auth_service.py`](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/auth_service.py) (Authentication), [`src/services/calendar_service.py`](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/calendar_service.py) (Calendar logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth_api["Auth routes<br/>[auth.py]"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
  node_jwt["JWT sessions<br/>[jwt_service.py]"]
end

subgraph group_domain["Couple features"]
  node_calendar_api["Calendar routes<br/>[calendar.py]"]
  node_calendar_service["Calendar logic"]
  node_spaces["Shared spaces<br/>[space_service.py]"]
  node_ideas["Ideas<br/>[ideas_service.py]"]
  node_diary["Diary<br/>[diary_service.py]"]
  node_tasks_api["Relationship tasks"]
  node_tasks["Task logic"]
  node_todos["Shared todos"]
  node_uploads["Media uploads<br/>[media_service.py]"]
end

subgraph group_persistence["Persistence"]
  node_auth_repo["Account data<br/>[auth_repository.py]"]
  node_session_repo["Refresh sessions"]
  node_calendar_repo["Calendar data"]
  node_uow["Unit of Work<br/>[uow.py]"]
  node_postgres[("PostgreSQL<br/>[client.py]")]
  node_executor["SQL executor<br/>[executor.py]"]
end

subgraph group_realtime["Realtime"]
  node_realtime_middleware["Realtime middleware<br/>[realtime.py]"]
  node_realtime_service["Realtime service"]
end

node_client(("Client"))
node_redis[("Redis")]

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_auth_api
node_app -->|"registers routes"| node_calendar_api
node_app -->|"registers routes"| node_tasks_api
node_auth_api -->|"calls"| node_auth_service
node_auth_service -->|"issues tokens"| node_jwt
node_auth_service -->|"reads and creates users"| node_auth_repo
node_auth_service -->|"uses sessions"| node_session_repo
node_calendar_api -->|"calls"| node_calendar_service
node_calendar_service -->|"reads and writes"| node_calendar_repo
node_tasks_api -->|"calls"| node_tasks
node_auth_service -->|"uses"| node_uow
node_calendar_service -->|"uses"| node_uow
node_tasks -->|"uses"| node_uow
node_uow -->|"constructs"| node_auth_repo
node_uow -->|"constructs"| node_session_repo
node_uow -->|"constructs"| node_calendar_repo
node_uow -->|"acquires connection"| node_postgres
node_uow -->|"creates"| node_executor
node_executor -->|"executes queries"| node_postgres
node_app -->|"installs"| node_realtime_middleware
node_realtime_middleware -->|"dispatches events"| node_realtime_service
node_app -->|"initializes"| node_realtime_service
node_app -->|"connects"| node_redis
node_realtime_service -.->|"uses"| node_redis
node_app -.->|"routes to"| node_spaces
node_app -.->|"routes to"| node_ideas
node_app -.->|"routes to"| node_diary
node_app -.->|"routes to"| node_todos
node_app -.->|"routes to"| node_uploads

click node_app "https://github.com/norvinka306key/be_blizhe/blob/main/main.py"
click node_auth_api "https://github.com/norvinka306key/be_blizhe/blob/main/src/api/v1/auth.py"
click node_auth_service "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/auth_service.py"
click node_jwt "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/jwt_service.py"
click node_auth_repo "https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/auth_repository.py"
click node_session_repo "https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/session_repository.py"
click node_calendar_api "https://github.com/norvinka306key/be_blizhe/blob/main/src/api/v1/calendar.py"
click node_calendar_service "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/calendar_service.py"
click node_calendar_repo "https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/calendar_repository.py"
click node_spaces "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/space_service.py"
click node_ideas "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/ideas_service.py"
click node_diary "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/diary_service.py"
click node_tasks_api "https://github.com/norvinka306key/be_blizhe/blob/main/src/api/v1/relationship_tasks.py"
click node_tasks "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/relationship_tasks_service.py"
click node_todos "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/shared_todos_service.py"
click node_uploads "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/media_service.py"
click node_uow "https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/uow.py"
click node_postgres "https://github.com/norvinka306key/be_blizhe/blob/main/src/infrastructure/postgres/client.py"
click node_executor "https://github.com/norvinka306key/be_blizhe/blob/main/src/infrastructure/postgres/executor.py"
click node_realtime_middleware "https://github.com/norvinka306key/be_blizhe/blob/main/src/middleware/realtime.py"
click node_realtime_service "https://github.com/norvinka306key/be_blizhe/blob/main/src/services/realtime_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_auth_api,node_auth_service,node_jwt,node_client toneBlue
class node_calendar_api,node_calendar_service,node_spaces,node_ideas,node_diary,node_tasks_api,node_tasks,node_todos,node_uploads,node_redis toneAmber
class node_auth_repo,node_session_repo,node_calendar_repo,node_uow,node_postgres,node_executor toneMint
class node_realtime_middleware,node_realtime_service toneRose
```

## Components

### API and access

- [FastAPI app](https://github.com/norvinka306key/be_blizhe/blob/main/main.py): `main.py`
- [Auth routes](https://github.com/norvinka306key/be_blizhe/blob/main/src/api/v1/auth.py): `src/api/v1/auth.py`
- [Authentication](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/auth_service.py): `src/services/auth_service.py`
- [JWT sessions](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/jwt_service.py): `src/services/jwt_service.py`

### Couple features

- [Calendar routes](https://github.com/norvinka306key/be_blizhe/blob/main/src/api/v1/calendar.py): `src/api/v1/calendar.py`
- [Calendar logic](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/calendar_service.py): `src/services/calendar_service.py`
- [Shared spaces](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/space_service.py): `src/services/space_service.py`
- [Ideas](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/ideas_service.py): `src/services/ideas_service.py`
- [Diary](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/diary_service.py): `src/services/diary_service.py`
- [Relationship tasks](https://github.com/norvinka306key/be_blizhe/blob/main/src/api/v1/relationship_tasks.py): `src/api/v1/relationship_tasks.py`
- [Task logic](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/relationship_tasks_service.py): `src/services/relationship_tasks_service.py`
- [Shared todos](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/shared_todos_service.py): `src/services/shared_todos_service.py`
- [Media uploads](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/media_service.py): `src/services/media_service.py`

### Persistence

- [Account data](https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/auth_repository.py): `src/repositories/auth_repository.py`
- [Refresh sessions](https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/session_repository.py): `src/repositories/session_repository.py`
- [Calendar data](https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/calendar_repository.py): `src/repositories/calendar_repository.py`
- [Unit of Work](https://github.com/norvinka306key/be_blizhe/blob/main/src/repositories/uow.py): `src/repositories/uow.py`
- [PostgreSQL](https://github.com/norvinka306key/be_blizhe/blob/main/src/infrastructure/postgres/client.py): `src/infrastructure/postgres/client.py`
- [SQL executor](https://github.com/norvinka306key/be_blizhe/blob/main/src/infrastructure/postgres/executor.py): `src/infrastructure/postgres/executor.py`

### Realtime

- [Realtime middleware](https://github.com/norvinka306key/be_blizhe/blob/main/src/middleware/realtime.py): `src/middleware/realtime.py`
- [Realtime service](https://github.com/norvinka306key/be_blizhe/blob/main/src/services/realtime_service.py): `src/services/realtime_service.py`

### Other components

- **Client**
- **Redis**

## Connections

- Client → FastAPI app: sends requests (evidence: `main.py`)
- FastAPI app → Auth routes: registers routes
- FastAPI app → Calendar routes: registers routes
- FastAPI app → Relationship tasks: registers routes
- Auth routes → Authentication: calls (evidence: `src/api/v1/auth.py`)
- Authentication → JWT sessions: issues tokens (evidence: `src/services/auth_service.py`)
- Authentication → Account data: reads and creates users (evidence: `src/services/auth_service.py`)
- Authentication → Refresh sessions: uses sessions (evidence: `src/services/auth_service.py`)
- Calendar routes → Calendar logic: calls (evidence: `src/api/v1/calendar.py`)
- Calendar logic → Calendar data: reads and writes (evidence: `src/services/calendar_service.py`)
- Relationship tasks → Task logic: calls (evidence: `src/api/v1/relationship_tasks.py`)
- Authentication → Unit of Work: uses (evidence: `src/services/auth_service.py`)
- Calendar logic → Unit of Work: uses (evidence: `src/services/calendar_service.py`)
- Task logic → Unit of Work: uses (evidence: `src/services/relationship_tasks_service.py`)
- Unit of Work → Account data: constructs (evidence: `src/repositories/uow.py`)
- Unit of Work → Refresh sessions: constructs (evidence: `src/repositories/uow.py`)
- Unit of Work → Calendar data: constructs (evidence: `src/repositories/uow.py`)
- Unit of Work → PostgreSQL: acquires connection (evidence: `src/repositories/uow.py`)
- Unit of Work → SQL executor: creates (evidence: `src/repositories/uow.py`)
- SQL executor → PostgreSQL: executes queries (evidence: `src/infrastructure/postgres/executor.py`)
- FastAPI app → Realtime middleware: installs (evidence: `main.py`)
- Realtime middleware → Realtime service: dispatches events (evidence: `src/middleware/realtime.py`)
- FastAPI app → Realtime service: initializes (evidence: `main.py`)
- FastAPI app → Redis: connects (evidence: `main.py`)
- Realtime service → Redis: uses
- FastAPI app → Shared spaces: routes to
- FastAPI app → Ideas: routes to
- FastAPI app → Diary: routes to
- FastAPI app → Shared todos: routes to
- FastAPI app → Media uploads: routes to
