tgex-backend/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a FastAPI + Telegram Bot backend application for managing Telegram channel integrations. The project uses:

• FastAPI for HTTP API endpoints
• aiogram for Telegram bot functionality
• SQLAlchemy 2.0 (async) for database operations
• PostgreSQL with asyncpg driver
• Alembic for database migrations
• uv for Python package management

Development Commands

Environment Setup

# Install dependencies (using uv)
uv sync

# Start PostgreSQL (via Docker Compose)
docker-compose up -d

# Run database migrations
uv run alembic upgrade head

Running the Application

# Start the FastAPI server
uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

Code Quality

# Run linter (Ruff)
uv run ruff check .

# Format code
uv run ruff format .

# Type checking (mypy with strict mode)
uv run mypy .

Testing

# Run all tests
uv run pytest

# Run a single test file
uv run pytest tests/test_file.py

# Run a specific test
uv run pytest tests/test_file.py::test_function_name

Database Migrations

# Create a new migration
uv run alembic revision --autogenerate -m "description"

# Apply migrations
uv run alembic upgrade head

# Rollback one migration
uv run alembic downgrade -1

Architecture

Layered Architecture

The codebase follows a clean architecture pattern with clear separation of concerns:

1. Domain Layer (src/domain/)

   • SQLAlchemy ORM models that represent database entities
   • All models inherit from domain.Base which provides:
     • Auto-generated id (UUID primary key)
     • Timestamps: created_at, updated_at, deleted_at
     • Automatic table naming (pluralized lowercase class name)
     • Timezone-aware datetime fields

2. Use Case Layer (src/usecase/)

   • Business logic functions organized by feature
   • Each use case is a standalone function
   • Depends on Protocol interfaces (Database, TelegramWriter, JWTEncoder)
   • Use cases are assembled in the Usecase dataclass for dependency injection

3. Adapter Layer (src/adapter/)

   • Concrete implementations of protocol interfaces:
     • Postgres: Database operations (implements Database protocol)
     • Telegram: Telegram bot integration (implements TelegramWriter protocol)
     • JWT: Token encoding/decoding (implements JWTEncoder protocol)

4. Controller Layer (src/controller/)

   • HTTP controllers (src/controller/http/): FastAPI route handlers
   • Telegram callbacks (src/controller/telegram_callback/): Telegram event handlers
   • Controllers call use cases to perform business logic

5. DTO Layer (src/dto/)

   • Pydantic models for request/response validation
   • Separate from domain models to decouple API contracts from database schema

Key Architectural Patterns

Dependency Injection via Protocols:

• Use cases depend on Protocol interfaces, not concrete implementations
• Allows for easy testing and swapping implementations
• See src/usecase/__init__.py for protocol definitions

Transaction Management:

• Database uses context-aware transactions via DatabaseBase.transaction()
• Session stored in ContextVar (_session_ctx) for implicit session access
• Always use async with database.transaction() for database operations
• The session is accessible via database.session within transaction context

Shared Base Classes:

• shared/datebase_base.py: Base database class with connection pooling and migration checking
• shared/telegram_base.py: Base Telegram bot class with polling lifecycle
• shared/logger/: Structured logging with JSON and console formatters

Configuration:

• All config in src/config.py using Pydantic Settings
• Environment variables loaded from .env file
• Nested config via double underscore: DB__URL, TELEGRAM__TOKEN

Application Lifecycle

1. Startup (in src/main.py):

   • Logger initialized
   • Adapters instantiated (Postgres, Telegram, JWT)
   • Usecase dataclass created with adapter dependencies
   • FastAPI lifespan context:
     • Connect to database (includes migration check)
     • Start Telegram bot polling

2. Request Flow:

   • HTTP: FastAPI route → Controller → Usecase → Adapter → Database
   • Telegram: Event → Telegram callback → Usecase → Adapter → Database

3. Shutdown:

   • Stop Telegram bot polling
   • Close database connections

Important Implementation Details

Database Session Management:

• DO NOT create sessions manually
• Use async with database.transaction() which handles begin/commit/rollback
• Access session via database.session property within transaction context
• Session lifecycle is managed by ContextVars for thread-safety

Telegram Bot Integration:

• Bot runs in polling mode (not webhook)
• Routers registered in src/controller/telegram_callback/
• Base class handles graceful shutdown of polling task

Authentication:

• JWT-based authentication for HTTP endpoints
• Login flow: Telegram bot → Login token → JWT access token
• Use get_current_user dependency for protected routes

Code Style:

• Single quotes for strings (configured in Ruff)
• Line length: 120 characters
• Python 3.13+ syntax
• Strict mypy typing enabled