Skip to content

development.md

Latest commit

 

History

History
189 lines (142 loc) · 3.17 KB

development.md

File metadata and controls

189 lines (142 loc) · 3.17 KB
Raw

Development Guide

🛠️ Development Setup

Prerequisites

  • Python 3.11 or later
  • Docker and Docker Compose
  • uv (fast Python package installer)

Initial Setup

  1. Install uv:
pip install uv
  1. Clone the repository:
git clone git@github.com:loguntsovae/asyncflow.git
cd asyncflow
  1. Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Install dependencies (with dev tools):
# Install base dependencies
uv pip install -e .
# Install development dependencies
uv pip install -e ".[dev]"
  1. Copy environment example and adjust:
cp .env.example .env
# Edit .env with your settings

🚀 Development Workflow

Running Services Locally

  1. Start all services:
make up
  1. Start specific service:
docker compose up api_gateway
  1. View logs:
make logs
# Or for specific service:
docker compose logs -f api_gateway

Quality Checks

Run all checks:

make qa  # Runs format, lint, typecheck, and test

Individual checks:

make format     # Format code with ruff
make lint       # Check code with ruff
make typecheck  # Run mypy type checking
make test       # Run pytest suite

Testing

Run tests:

# All tests
pytest

# Specific test file
pytest src/tests/test_orders_api.py

# With coverage
pytest --cov=src

Adding Dependencies

  1. Add runtime dependency:
uv pip install package_name
  1. Add development dependency:
uv pip install --group dev package_name
  1. Update pyproject.toml accordingly:
[project]
dependencies = [
    "package_name>=1.0.0,<2.0"
]

[dependency-groups]
dev = [
    "dev-package>=1.0.0,<2.0"
]

📦 Building and Deployment

Building Docker Images

# Build all services
docker compose build

# Build specific service
docker compose build api_gateway

Running Tests in Docker

# Build test image
docker build -t asyncflow-test -f order_service/Dockerfile .

# Run tests
docker run --rm asyncflow-test pytest

Production Deployment

  1. Set production configuration:
cp .env.example .env.prod
# Edit .env.prod with production settings
  1. Deploy with Docker Compose:
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

🔍 Monitoring & Debugging

Metrics

Access service metrics:

Health Checks

Check service health:

Logging

View structured logs:

# All services
docker compose logs -f | jq .

# Specific service
docker compose logs -f api_gateway | jq .

📚 Documentation

⚡ Performance Tips

  1. Use uv for faster dependency installation
  2. Keep Docker images minimal with multi-stage builds
  3. Enable response compression for larger payloads
  4. Use connection pooling for database and HTTP clients
  5. Monitor and optimize based on metrics