# devlearnsal/varasoft architecture

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

- Interactive diagram: https://gitdiagram.com/devlearnsal/varasoft
- Repository: https://github.com/devlearnsal/varasoft

## Overview

1. **Project shape**
   - VaraSoft is primarily a **Python backend** under `backend/`, built with **FastAPI**, **SQLAlchemy 2.x**, **PostgreSQL**, and **Alembic**.
   - The repo also contains a **Telegram bot client** that talks to the backend over HTTP. There is no active frontend in the tree; `frontend/` is just a placeholder.

2. **Two runtime processes**
   - The backend runs as a FastAPI app via `app.main:app`.
   - The Telegram bot runs as a separate Python process via `app.telegram.bot`.
   - These are independent entry points, which is important for an architecture diagram: one process serves the API, the other acts as an external client.

3. **HTTP API boundary**
   - `backend/app/api/transaction.py` exposes the CRUD surface for transactions:
     - `POST /transactions`
     - `GET /transactions`
     - `GET /transactions/{id}`
     - `PUT /transactions/{id}`
     - `DELETE /transactions/{id}`
   - `backend/app/api/telegram.py` exposes the Telegram ingress endpoint `POST /telegram/message`, which receives forwarded messages from the bot.

4. **Application layering**
   - The code follows a clear layered structure:
     - **API layer** in `app/api`
     - **service layer** in `app/services`
     - **repository layer** in `app/repositories`
     - **domain/persistence models** in `app/models`
     - **request/response schemas** in `app/schemas`
   - For a diagram, the key flow is: **HTTP request → API router → service → repository → database**, with schemas used at the edges.

5. **Transaction subsystem**
   - The core business feature is the **transaction CRUD** implementation.
   - `app/services/transaction_service.py` contains the business logic.
   - `app/repositories/transaction_repository.py` handles database access.
   - `app/schemas/transaction.py` defines the API contracts.
   - This subsystem is the only fully productized REST feature described in the README.

6. **Persistence and database access**
   - `app/database/database.py` and `app/database/base.py` set up the SQLAlchemy engine/session and model base.
   - Persistence is backed by **PostgreSQL** on `localhost:5432` by default.
   - The repository does not appear to use any external queue or cache; the database is the primary state store.

7. **Domain model**
   - The initial data model includes `users`, `categories`, and `transactions`.
   - Corresponding model modules exist in `app/models/user.py`, `category.py`, and `transaction.py`.
   - `app/models/enums.py` and `mixins.py` suggest shared domain types and reusable model behavior.
   - From the README and migration, `users` and `categories` support the transaction model rather than serving as standalone product areas.

8. **Migrations and schema evolution**
   - Alembic is fully wired in `backend/alembic/`.
   - `backend/alembic/versions/8d773e2dfc0d_create_initial_tables.py` is the initial schema migration.
   - The migration boundary matters because schema changes are managed separately from the application code.

9. **Telegram integration**
   - The Telegram bot is not an NLP engine; it is a **client adapter**.
   - `app/telegram/bot.py`, `commands.py`, and `handlers.py` manage the bot runtime and message handling.
   - The bot forwards text messages to the backend over HTTPX, and the backend currently responds without AI processing or transaction creation.
   - This makes Telegram an external ingress path into the backend, not a second business engine.

10. **Telegram service boundary**
    - `app/services/telegram_service.py` and `app/schemas/telegram.py` define the backend-side handling for Telegram messages.
    - This keeps Telegram-specific payload handling separate from transaction logic, which is useful when drawing boundaries between channels and core business operations.

11. **Configuration and operational concerns**
    - `app/core/config.py` centralizes environment-driven settings such as database and Telegram token configuration.
    - `app/core/exceptions.py` likely standardizes error handling across layers.
    - The README and `.env.example` show the system depends on local PostgreSQL and a `TELEGRAM_BOT_TOKEN`.

12. **What is intentionally not central**
    - `backend/app/ai/` exists, but the README explicitly says there is **no natural language processing yet**.
    - `docs/` and `frontend/` are placeholders, so they are not part of the current runtime architecture.

13. **High-level data flow to diagram**
    - **REST clients** talk to FastAPI for transaction CRUD.
    - **Telegram users** talk to the Telegram bot, which forwards messages to the backend over HTTP.
    - The backend persists data in PostgreSQL through SQLAlchemy repositories.
    - Alembic manages the database schema lifecycle outside the runtime request path.

Main entry points: [`backend/app/api/telegram.py`](https://github.com/devlearnsal/varasoft/blob/main/backend/app/api/telegram.py) (Telegram ingress), [`backend/app/main.py`](https://github.com/devlearnsal/varasoft/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/api/transaction.py`](https://github.com/devlearnsal/varasoft/blob/main/backend/app/api/transaction.py) (Transaction API), [`backend/app/services/transaction_service.py`](https://github.com/devlearnsal/varasoft/blob/main/backend/app/services/transaction_service.py) (Txn service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime processes"]
  node_rest_clients(("REST clients<br/>external client"))
  node_telegram_users(("Telegram users<br/>external user"))
end

subgraph group_backend["Backend app"]
  node_fastapi_app["FastAPI app<br/>api runtime<br/>[main.py]"]
  node_transaction_api["Transaction API<br/>router<br/>[transaction.py]"]
  node_telegram_api["Telegram ingress<br/>router<br/>[telegram.py]"]
  node_transaction_service["Txn service"]
  node_telegram_service["Telegram service"]
  node_transaction_repo["Txn repo"]
  node_schemas_txn["Txn schemas<br/>[transaction.py]"]
  node_schemas_telegram["Telegram schemas<br/>[telegram.py]"]
  node_models[("Domain models<br/>sqlalchemy models")]
  node_db_core[("DB core<br/>sqlalchemy setup<br/>[database.py]")]
end

subgraph group_data["Persistence"]
  node_postgres[("PostgreSQL<br/>database")]
  node_alembic["Alembic<br/>migration system"]
end

subgraph group_client["Telegram client"]
  node_bot_runtime["Telegram bot<br/>bot runtime<br/>[bot.py]"]
  node_bot_handlers["Bot handlers<br/>bot logic<br/>[handlers.py]"]
  node_http_client["HTTPX client<br/>outbound adapter<br/>[commands.py]"]
end

node_rest_clients -->|"HTTP requests"| node_fastapi_app
node_telegram_users -->|"messages"| node_bot_runtime
node_bot_runtime -->|"dispatch"| node_bot_handlers
node_bot_handlers -->|"forward"| node_http_client
node_http_client -->|"POST /telegram/message"| node_telegram_api
node_fastapi_app -->|"mounts"| node_transaction_api
node_fastapi_app -->|"mounts"| node_telegram_api
node_transaction_api -->|"calls"| node_transaction_service
node_telegram_api -->|"calls"| node_telegram_service
node_transaction_api -->|"validates"| node_schemas_txn
node_telegram_api -->|"validates"| node_schemas_telegram
node_transaction_service -->|"uses"| node_transaction_repo
node_transaction_service -->|"maps"| node_schemas_txn
node_transaction_repo -->|"sessions"| node_db_core
node_db_core -->|"persists"| node_postgres
node_db_core -->|"maps"| node_models
node_alembic -.->|"migrates"| node_postgres
node_alembic -.->|"tracks schema"| node_models

click node_fastapi_app "https://github.com/devlearnsal/varasoft/blob/main/backend/app/main.py"
click node_transaction_api "https://github.com/devlearnsal/varasoft/blob/main/backend/app/api/transaction.py"
click node_telegram_api "https://github.com/devlearnsal/varasoft/blob/main/backend/app/api/telegram.py"
click node_transaction_service "https://github.com/devlearnsal/varasoft/blob/main/backend/app/services/transaction_service.py"
click node_telegram_service "https://github.com/devlearnsal/varasoft/blob/main/backend/app/services/telegram_service.py"
click node_transaction_repo "https://github.com/devlearnsal/varasoft/blob/main/backend/app/repositories/transaction_repository.py"
click node_schemas_txn "https://github.com/devlearnsal/varasoft/blob/main/backend/app/schemas/transaction.py"
click node_schemas_telegram "https://github.com/devlearnsal/varasoft/blob/main/backend/app/schemas/telegram.py"
click node_models "https://github.com/devlearnsal/varasoft/tree/main/backend/app/models"
click node_db_core "https://github.com/devlearnsal/varasoft/blob/main/backend/app/database/database.py"
click node_alembic "https://github.com/devlearnsal/varasoft/tree/main/backend/alembic"
click node_bot_runtime "https://github.com/devlearnsal/varasoft/blob/main/backend/app/telegram/bot.py"
click node_bot_handlers "https://github.com/devlearnsal/varasoft/blob/main/backend/app/telegram/handlers.py"
click node_http_client "https://github.com/devlearnsal/varasoft/blob/main/backend/app/telegram/commands.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_rest_clients,node_telegram_users toneBlue
class node_fastapi_app,node_transaction_api,node_telegram_api,node_transaction_service,node_telegram_service,node_transaction_repo,node_schemas_txn,node_schemas_telegram,node_models,node_db_core toneAmber
class node_postgres,node_alembic toneMint
class node_bot_runtime,node_bot_handlers,node_http_client toneRose
```

## Components

### Runtime processes

Separate Python entry points that run independently.

- **REST clients**: external client · Consumers of the transaction API.
- **Telegram users**: external user · People messaging the bot.

### Backend app

FastAPI application, business logic, persistence, and Telegram ingress handling.

- [FastAPI app](https://github.com/devlearnsal/varasoft/blob/main/backend/app/main.py): api runtime · Main backend process exposed by app.main:app. · `backend/app/main.py`
- [Transaction API](https://github.com/devlearnsal/varasoft/blob/main/backend/app/api/transaction.py): router · CRUD endpoints for transactions. · `backend/app/api/transaction.py`
- [Telegram ingress](https://github.com/devlearnsal/varasoft/blob/main/backend/app/api/telegram.py): router · HTTP endpoint for forwarded Telegram messages. · `backend/app/api/telegram.py`
- [Txn service](https://github.com/devlearnsal/varasoft/blob/main/backend/app/services/transaction_service.py): service · Business logic for transaction workflows. · `backend/app/services/transaction_service.py`
- [Telegram service](https://github.com/devlearnsal/varasoft/blob/main/backend/app/services/telegram_service.py): service · Backend-side handling for Telegram messages. · `backend/app/services/telegram_service.py`
- [Txn repo](https://github.com/devlearnsal/varasoft/blob/main/backend/app/repositories/transaction_repository.py): repository · Database access for transactions. · `backend/app/repositories/transaction_repository.py`
- [Txn schemas](https://github.com/devlearnsal/varasoft/blob/main/backend/app/schemas/transaction.py): schema · Request and response contracts for transactions. · `backend/app/schemas/transaction.py`
- [Telegram schemas](https://github.com/devlearnsal/varasoft/blob/main/backend/app/schemas/telegram.py): schema · Contracts for Telegram payloads. · `backend/app/schemas/telegram.py`
- [Domain models](https://github.com/devlearnsal/varasoft/tree/main/backend/app/models): sqlalchemy models · Users, categories, transactions, enums, and mixins. · `backend/app/models`
- [DB core](https://github.com/devlearnsal/varasoft/blob/main/backend/app/database/database.py): sqlalchemy setup · Engine, session, and declarative base wiring. · `backend/app/database/database.py`

### Persistence

Database schema and migration boundary.

- **PostgreSQL**: database · Primary persistent store on localhost:5432.
- [Alembic](https://github.com/devlearnsal/varasoft/tree/main/backend/alembic): migration system · Schema evolution and migration scripts. · `backend/alembic`

### Telegram client

Bot process that forwards messages to the backend.

- [Telegram bot](https://github.com/devlearnsal/varasoft/blob/main/backend/app/telegram/bot.py): bot runtime · Separate Python process started from app.telegram.bot. · `backend/app/telegram/bot.py`
- [Bot handlers](https://github.com/devlearnsal/varasoft/blob/main/backend/app/telegram/handlers.py): bot logic · Commands and message handling for the bot process. · `backend/app/telegram/handlers.py`
- [HTTPX client](https://github.com/devlearnsal/varasoft/blob/main/backend/app/telegram/commands.py): outbound adapter · Forwards Telegram messages to the backend over HTTP. · `backend/app/telegram/commands.py`

## Connections

- REST clients → FastAPI app: HTTP requests · Clients call the backend API.
- Telegram users → Telegram bot: messages · Users interact with the bot.
- Telegram bot → Bot handlers: dispatch · The bot process routes commands and messages.
- Bot handlers → HTTPX client: forward · Handlers send Telegram messages to the backend.
- HTTPX client → Telegram ingress: POST /telegram/message · Outbound HTTP call into the backend.
- FastAPI app → Transaction API: mounts · Main app registers transaction routes.
- FastAPI app → Telegram ingress: mounts · Main app registers Telegram ingress routes.
- Transaction API → Txn service: calls · CRUD routes delegate to service logic.
- Telegram ingress → Telegram service: calls · Ingress handler delegates to Telegram service.
- Transaction API → Txn schemas: validates · API boundary uses transaction schemas.
- Telegram ingress → Telegram schemas: validates · API boundary uses Telegram schemas.
- Txn service → Txn repo: uses · Business logic reads and writes through the repository.
- Txn service → Txn schemas: maps · Service works with transaction contracts.
- Txn repo → DB core: sessions · Repository uses SQLAlchemy session and engine wiring.
- DB core → PostgreSQL: persists · SQLAlchemy connects to PostgreSQL.
- DB core → Domain models: maps · Declarative base binds ORM models.
- Alembic → PostgreSQL: migrates · Alembic manages schema changes in the database.
- Alembic → Domain models: tracks schema · Migrations evolve the persisted model structure.