# dominux/pentaract architecture

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

- Interactive diagram: https://gitdiagram.com/dominux/pentaract
- Repository: https://github.com/dominux/pentaract

## Overview

1. **High-level shape**
   - Pentaract is a two-part system: a **Rust backend** in `pentaract/` and a **React/Vite frontend** in `ui/`.
   - The backend exposes a REST API, handles authentication, authorization, metadata persistence, and Telegram integration.
   - The frontend is a single-page UI for managing files, storages, workers, and access grants.

2. **Core product boundary**
   - This is not a local filesystem app; it is a **cloud storage abstraction built on top of Telegram**.
   - **Postgres stores metadata**: users, storages, files, chunks, access grants, and worker records.
   - **Telegram stores the actual file data**, split into chunks and uploaded through bot accounts.

3. **Backend layering**
   - The Rust backend follows a typical layered architecture:
     - `routers/` define HTTP endpoints.
     - `services/` hold business logic.
     - `repositories/` encapsulate database access.
     - `models/` represent persisted entities.
     - `schemas/` define request/response payloads.
   - `common/` contains cross-cutting infrastructure such as JWT, password hashing, DB pool, auth middleware, Telegram client code, and shared types.

4. **Main domain subsystems**
   - **Auth/users**: registration, login, token handling, password management, current-user identity.
   - **Storages**: logical storage spaces owned by users; each storage maps to a Telegram channel.
   - **Files/folders**: file tree operations such as create, upload, download, info, delete.
   - **Storage workers**: Telegram bots used as upload/download executors and rate-limit sharding.
   - **Access control**: per-storage permissions for other users, with roles like viewer, editor, admin.

5. **Request flow through the backend**
   - A client request enters a router in `routers/`.
   - Auth middleware in `common/routing/middlewares/auth.rs` validates JWTs and attaches identity/context.
   - The router calls a service, which applies business rules and checks access.
   - The service uses repositories for database reads/writes and Telegram API helpers when file data must be moved.
   - Responses are serialized through `schemas/`.

6. **Persistence boundary**
   - `common/db/` contains the Postgres connection pool and error handling.
   - Repositories are split by aggregate: `users`, `storages`, `files`, `storage_workers`, `access`.
   - The database appears to be used primarily for **state and coordination**, not blob storage.
   - This separation is important: file bytes live in Telegram, while Postgres keeps only the system’s metadata and relationships.

7. **Telegram integration**
   - `common/telegram_api/` wraps Telegram Bot API access and request/response schemas.
   - Storage workers are Telegram bot identities used by the system to interact with Telegram under request limits.
   - Each storage is tied to a Telegram channel, which acts as the durable backing store for chunked file content.

8. **File chunking and storage manager**
   - `storage_manager.rs` and `services/storage_manager.rs` indicate a dedicated orchestration layer for file upload/download.
   - The system splits large files into chunks, uploads chunks separately, and reconstructs them on download.
   - This is the key mechanism that lets the product work around Telegram file-size limits.
   - `models/file_chunks.rs` suggests chunk metadata is tracked explicitly in Postgres for ordered reassembly.

9. **Concurrency and worker scheduling**
   - `common/channels.rs` and `services/storage_workers_scheduler.rs` suggest internal task coordination and background scheduling.
   - The backend likely distributes Telegram operations across available workers to improve throughput and stay within per-bot limits.
   - `WORKERS` and `CHANNEL_CAPACITY` in the environment indicate the server uses a bounded worker/channel model.

10. **Security and access control**
   - Authentication uses JWTs via `common/jwt_manager.rs`.
   - Passwords are managed separately in `common/password_manager.rs`.
   - Access control is a first-class subsystem: `models/access.rs`, `repositories/access.rs`, `schemas/access.rs`, and `routers`/`services` around access management show per-storage permissions are enforced server-side.
   - This is the main authorization boundary between storage owners and shared users.

11. **Frontend architecture**
   - The UI is a React application structured by pages and reusable components.
   - `src/api/` centralizes HTTP calls, `src/common/auth_guard.js` protects authenticated routes, and `src/layouts/` provides shared page chrome.
   - Pages are grouped by domain: login/register, files, storages, and storage workers.
   - The UI is a thin client over the REST API; it does not appear to own domain state beyond view state and auth session handling.

12. **Deployment model**
   - The repo is container-first: `Dockerfile`, `docker-compose.yml`, and a GitHub Actions workflow build and publish the image.
   - The standard deployment consists of the Pentaract app container plus a separate Postgres container.
   - The README also implies the backend can serve the built UI assets, so the deployed app is effectively a single service backed by a database and Telegram network access.

13. **Key external dependencies**
   - **Postgres**: required persistent database.
   - **Telegram Bot API**: storage backend and worker transport.
   - **Docker**: primary packaging/runtime path.
   - The system is intentionally lightweight on local disk usage; the architecture minimizes dependence on local filesystem storage.

14. **What to show in an architecture diagram**
   - Show three main boundaries: **browser/UI**, **Rust API service**, and **external systems**.
   - Under the Rust service, separate **HTTP routers**, **business services**, **repositories/DB**, and **Telegram integration**.
   - Under external systems, include **Postgres** and **Telegram channels/bots**.
   - Highlight that file bytes move to Telegram, while metadata and permissions stay in Postgres.

Main entry points: [`ui/src/App.jsx`](https://github.com/dominux/pentaract/blob/main/ui/src/App.jsx) (React app), [`pentaract/src/services`](https://github.com/dominux/pentaract/tree/main/pentaract/src/services) (Services), [`pentaract/src/routers`](https://github.com/dominux/pentaract/tree/main/pentaract/src/routers) (Routers), [`pentaract/src/repositories`](https://github.com/dominux/pentaract/tree/main/pentaract/src/repositories) (Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["UI"]
  node_browser(("Browser<br/>client"))
  node_ui_app["React app<br/>spa<br/>[App.jsx]"]
  node_ui_api["API client<br/>http client"]
  node_ui_guard["Auth guard<br/>route guard<br/>[auth_guard.js]"]
  node_ui_pages["Domain pages<br/>views"]
  node_ui_components["Shared UI<br/>components"]
end

subgraph group_backend["Rust API"]
  node_server_main["App server<br/>rust service<br/>[main.rs]"]
  node_http_routers["Routers<br/>http endpoints"]
  node_auth_mw["Auth middleware<br/>jwt middleware<br/>[auth.rs]"]
  node_domain_services["Services<br/>business logic"]
  node_storage_mgr["Storage manager<br/>orchestration<br/>[storage_manager.rs]"]
  node_worker_sched["Worker scheduler<br/>background scheduler"]
  node_repos["Repositories<br/>db access"]
  node_db_pool[("DB pool<br/>postgres pool")]
  node_models["Models<br/>entities"]
  node_schemas["Schemas<br/>payloads"]
  node_telegram_api["Telegram API<br/>integration"]
  node_shared_common["Common infra<br/>security and plumbing"]
end

subgraph group_external["External"]
  node_postgres[("Postgres<br/>database")]
  node_telegram[("Telegram<br/>storage backend")]
end

node_browser -->|"uses"| node_ui_app
node_ui_app -->|"calls"| node_ui_api
node_ui_app -->|"protects"| node_ui_guard
node_ui_app -->|"renders"| node_ui_pages
node_ui_app -->|"composes"| node_ui_components
node_server_main -->|"mounts"| node_http_routers
node_server_main -->|"initializes"| node_shared_common
node_http_routers -->|"uses"| node_auth_mw
node_http_routers -->|"delegates"| node_domain_services
node_domain_services -->|"reads/writes"| node_repos
node_domain_services -->|"orchestrates"| node_storage_mgr
node_domain_services -->|"coordinates"| node_worker_sched
node_repos -->|"uses"| node_db_pool
node_repos -->|"maps"| node_models
node_http_routers -->|"serializes"| node_schemas
node_domain_services -->|"validates"| node_schemas
node_storage_mgr -->|"uploads/downloads"| node_telegram_api
node_worker_sched -->|"dispatches"| node_telegram_api
node_shared_common -->|"connects"| node_postgres
node_shared_common -->|"authenticates"| node_telegram
node_repos -->|"persists"| node_postgres
node_storage_mgr -->|"stores bytes"| node_telegram

click node_browser "https://github.com/dominux/pentaract/tree/main/ui/src"
click node_ui_app "https://github.com/dominux/pentaract/blob/main/ui/src/App.jsx"
click node_ui_api "https://github.com/dominux/pentaract/tree/main/ui/src/api"
click node_ui_guard "https://github.com/dominux/pentaract/blob/main/ui/src/common/auth_guard.js"
click node_ui_pages "https://github.com/dominux/pentaract/tree/main/ui/src/pages"
click node_ui_components "https://github.com/dominux/pentaract/tree/main/ui/src/components"
click node_server_main "https://github.com/dominux/pentaract/blob/main/pentaract/src/main.rs"
click node_http_routers "https://github.com/dominux/pentaract/tree/main/pentaract/src/routers"
click node_auth_mw "https://github.com/dominux/pentaract/blob/main/pentaract/src/common/routing/middlewares/auth.rs"
click node_domain_services "https://github.com/dominux/pentaract/tree/main/pentaract/src/services"
click node_storage_mgr "https://github.com/dominux/pentaract/blob/main/pentaract/src/services/storage_manager.rs"
click node_worker_sched "https://github.com/dominux/pentaract/blob/main/pentaract/src/services/storage_workers_scheduler.rs"
click node_repos "https://github.com/dominux/pentaract/tree/main/pentaract/src/repositories"
click node_db_pool "https://github.com/dominux/pentaract/tree/main/pentaract/src/common/db"
click node_models "https://github.com/dominux/pentaract/tree/main/pentaract/src/models"
click node_schemas "https://github.com/dominux/pentaract/tree/main/pentaract/src/schemas"
click node_telegram_api "https://github.com/dominux/pentaract/tree/main/pentaract/src/common/telegram_api"
click node_shared_common "https://github.com/dominux/pentaract/tree/main/pentaract/src/common"

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_browser,node_ui_app,node_ui_api,node_ui_guard,node_ui_pages,node_ui_components toneBlue
class node_server_main,node_http_routers,node_auth_mw,node_domain_services,node_storage_mgr,node_worker_sched,node_repos,node_db_pool,node_models,node_schemas,node_telegram_api,node_shared_common toneAmber
class node_postgres,node_telegram toneMint
```

## Components

### UI

React/Vite single-page client

- [Browser](https://github.com/dominux/pentaract/tree/main/ui/src): client · Users interact with the web UI here · `ui/src`
- [React app](https://github.com/dominux/pentaract/blob/main/ui/src/App.jsx): spa · Application shell and route composition · `ui/src/App.jsx`
- [API client](https://github.com/dominux/pentaract/tree/main/ui/src/api): http client · Centralized REST calls and request handling · `ui/src/api`
- [Auth guard](https://github.com/dominux/pentaract/blob/main/ui/src/common/auth_guard.js): route guard · Protects authenticated UI routes · `ui/src/common/auth_guard.js`
- [Domain pages](https://github.com/dominux/pentaract/tree/main/ui/src/pages): views · Files, storages, workers, login and register screens · `ui/src/pages`
- [Shared UI](https://github.com/dominux/pentaract/tree/main/ui/src/components): components · Reusable dialogs, lists, headers and access widgets · `ui/src/components`

### Rust API

HTTP service with business logic and persistence

- [App server](https://github.com/dominux/pentaract/blob/main/pentaract/src/main.rs): rust service · Bootstraps configuration, routing and runtime · `pentaract/src/main.rs`
- [Routers](https://github.com/dominux/pentaract/tree/main/pentaract/src/routers): http endpoints · Auth, users, storages, files and worker routes · `pentaract/src/routers`
- [Auth middleware](https://github.com/dominux/pentaract/blob/main/pentaract/src/common/routing/middlewares/auth.rs): jwt middleware · Validates JWTs and attaches request identity · `pentaract/src/common/routing/middlewares/auth.rs`
- [Services](https://github.com/dominux/pentaract/tree/main/pentaract/src/services): business logic · Applies rules for auth, users, storages and files · `pentaract/src/services`
- [Storage manager](https://github.com/dominux/pentaract/blob/main/pentaract/src/services/storage_manager.rs): orchestration · Coordinates chunking, upload and download workflows · `pentaract/src/services/storage_manager.rs`
- [Worker scheduler](https://github.com/dominux/pentaract/blob/main/pentaract/src/services/storage_workers_scheduler.rs): background scheduler · Distributes Telegram operations across storage workers · `pentaract/src/services/storage_workers_scheduler.rs`
- [Repositories](https://github.com/dominux/pentaract/tree/main/pentaract/src/repositories): db access · Users, storages, files, access and worker persistence · `pentaract/src/repositories`
- [DB pool](https://github.com/dominux/pentaract/tree/main/pentaract/src/common/db): postgres pool · Shared Postgres connection and error handling · `pentaract/src/common/db`
- [Models](https://github.com/dominux/pentaract/tree/main/pentaract/src/models): entities · Persisted users, storages, files, chunks and grants · `pentaract/src/models`
- [Schemas](https://github.com/dominux/pentaract/tree/main/pentaract/src/schemas): payloads · Request and response shapes for the REST API · `pentaract/src/schemas`
- [Telegram API](https://github.com/dominux/pentaract/tree/main/pentaract/src/common/telegram_api): integration · Bot API wrapper used for file transfer and worker control · `pentaract/src/common/telegram_api`
- [Common infra](https://github.com/dominux/pentaract/tree/main/pentaract/src/common): security and plumbing · JWT, password hashing, channels and shared types · `pentaract/src/common`

### External

Runtime dependencies outside the repo

- **Postgres**: database · Stores metadata, permissions, chunk records and coordination state
- **Telegram**: storage backend · Channels and bot accounts hold the actual file data

## Connections

- Browser → React app: uses · Users open the SPA
- React app → API client: calls · UI issues REST requests through the API client
- React app → Auth guard: protects · Authenticated navigation is guarded
- React app → Domain pages: renders · Pages provide the main screens
- React app → Shared UI: composes · Shared widgets are reused across pages
- App server → Routers: mounts · Server wires HTTP endpoints
- App server → Common infra: initializes · Loads shared infrastructure and runtime helpers
- Routers → Auth middleware: uses · Routes enforce authenticated access
- Routers → Services: delegates · Handlers pass requests to business logic
- Services → Repositories: reads/writes · Services persist and query metadata
- Services → Storage manager: orchestrates · File operations flow through the storage manager
- Services → Worker scheduler: coordinates · Worker assignment and scheduling are managed here
- Repositories → DB pool: uses · Repositories execute Postgres access through the pool
- Repositories → Models: maps · Persistence is defined by domain entities
- Routers → Schemas: serializes · Endpoints exchange typed payloads
- Services → Schemas: validates · Service responses and inputs follow API shapes
- Storage manager → Telegram API: uploads/downloads · Chunks are moved through Telegram Bot API
- Worker scheduler → Telegram API: dispatches · Scheduler routes Telegram work to available bots
- Common infra → Postgres: connects · DB pool and errors back the persistence layer
- Common infra → Telegram: authenticates · Telegram client and worker identities target channels
- Repositories → Postgres: persists · Metadata and permissions live in Postgres
- Storage manager → Telegram: stores bytes · File content is chunked into Telegram channels
