Contributing
=============

Guidelines for contributing to the Co-design Platform backend.

Development Setup
------------------

.. code-block:: bash

   # 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
-------------------

.. code-block:: bash

   # Lint
   ruff check backend/

   # Type check
   mypy backend/

   # Tests
   pytest -v

   # Build Docker image
   docker compose build backend