How dominux/pentaract works
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: App.jsx React app · services Services · routers Routers · repositories Repositories
Components 20
UI
React/Vite single-page client
- Browser · Users interact with the web UI here
ui/src - React app · Application shell and route composition
ui/src/App.jsx - API client · Centralized REST calls and request handling
ui/src/api - Auth guard · Protects authenticated UI routes
ui/src/common/auth_guard.js - Domain pages · Files, storages, workers, login and register screens
ui/src/pages - Shared UI · Reusable dialogs, lists, headers and access widgets
ui/src/components
Rust API
HTTP service with business logic and persistence
- App server · Bootstraps configuration, routing and runtime
pentaract/src/main.rs - Routers · Auth, users, storages, files and worker routes
pentaract/src/routers - Auth middleware · Validates JWTs and attaches request identity
pentaract/src/common/routing/middlewares/auth.rs - Services · Applies rules for auth, users, storages and files
pentaract/src/services - Storage manager · Coordinates chunking, upload and download workflows
pentaract/src/services/storage_manager.rs - Worker scheduler · Distributes Telegram operations across storage workers
pentaract/src/services/storage_workers_scheduler.rs - Repositories · Users, storages, files, access and worker persistence
pentaract/src/repositories - DB pool · Shared Postgres connection and error handling
pentaract/src/common/db - Models · Persisted users, storages, files, chunks and grants
pentaract/src/models - Schemas · Request and response shapes for the REST API
pentaract/src/schemas - Telegram API · Bot API wrapper used for file transfer and worker control
pentaract/src/common/telegram_api - Common infra · JWT, password hashing, channels and shared types
pentaract/src/common
External
Runtime dependencies outside the repo
- Postgres · Stores metadata, permissions, chunk records and coordination state
- Telegram · Channels and bot accounts hold the actual file data
Connections 22
- 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