How devlearnsal/varasoft works
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: telegram.py Telegram ingress · main.py FastAPI app · transaction.py Transaction API · transaction_service.py Txn service
Components 17
Runtime processes
Separate Python entry points that run independently.
- REST clients · Consumers of the transaction API.
- Telegram users · People messaging the bot.
Backend app
FastAPI application, business logic, persistence, and Telegram ingress handling.
- FastAPI app · Main backend process exposed by app.main:app.
backend/app/main.py - Transaction API · CRUD endpoints for transactions.
backend/app/api/transaction.py - Telegram ingress · HTTP endpoint for forwarded Telegram messages.
backend/app/api/telegram.py - Txn service · Business logic for transaction workflows.
backend/app/services/transaction_service.py - Telegram service · Backend-side handling for Telegram messages.
backend/app/services/telegram_service.py - Txn repo · Database access for transactions.
backend/app/repositories/transaction_repository.py - Txn schemas · Request and response contracts for transactions.
backend/app/schemas/transaction.py - Telegram schemas · Contracts for Telegram payloads.
backend/app/schemas/telegram.py - Domain models · Users, categories, transactions, enums, and mixins.
backend/app/models - DB core · Engine, session, and declarative base wiring.
backend/app/database/database.py
Persistence
Database schema and migration boundary.
- PostgreSQL · Primary persistent store on localhost:5432.
- Alembic · Schema evolution and migration scripts.
backend/alembic
Telegram client
Bot process that forwards messages to the backend.
- Telegram bot · Separate Python process started from app.telegram.bot.
backend/app/telegram/bot.py - Bot handlers · Commands and message handling for the bot process.
backend/app/telegram/handlers.py - HTTPX client · Forwards Telegram messages to the backend over HTTP.
backend/app/telegram/commands.py
Connections 18
- 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.