Contributing

Guidelines for contributing to the Co-design Platform backend.

Development Setup

# Clone
git clone git@gitlab.eurobios.com:esa/codesign/codesign-backend.git
cd codesign-backend/backend

# Virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Start supporting services
docker compose up -d postgres litellm

# Run backend in dev mode
uvicorn backend.api.main:app --reload --port 8000

Code Style

  • Python 3.12+ features encouraged

  • Type hints on all function signatures

  • Async for all I/O operations

  • Pydantic for data validation at API boundaries

  • SQLAlchemy 2.0 style (select statements, not legacy query API)

Branch Strategy

  • main — Production-ready code

  • develop — Integration branch

  • feature/xxx — Feature branches

  • fix/xxx — Bug fix branches

Workflow:

  1. Create feature branch from develop

  2. Implement changes with tests

  3. Run full test suite

  4. Open merge request

  5. Code review + CI pipeline

  6. Merge to develop

Adding a New API Endpoint

  1. Define schema in api/schemas/

  2. Add route in api/routers/

  3. Implement service logic in service/

  4. Add repository methods if new data access needed

  5. Write tests in tests/

Adding a New Agent

  1. Create directory in service/chat/orchestrator/agents/{agent_name}/

  2. Implement agent with prompt template and tools

  3. Register agent in the orchestrator graph

  4. Add routing logic in the router agent

  5. Test with mock LLM responses

Adding a New Template Type

  1. Define SQLAlchemy model in models/

  2. Create repository in database/repositories/

  3. Add template code to the service layer

  4. Create form definition in service/form_templates/definitions/

  5. Add API endpoints if needed

  6. Update the corresponding agent to handle the new template

Running CI Locally

# Lint
ruff check backend/

# Type check
mypy backend/

# Tests
pytest -v

# Build Docker image
docker compose build backend