Colo.ai - Main API Service

The core backend service for the Colo.ai platform, built with FastAPI. It handles authentication, data management, and orchestration between the web frontend and ML services.

FastAPI backend for Colo.ai clinical workflows: authentication, clinics, users, patients, studies, image upload, AI analysis, and PDF reports.

Tech Stack

• Framework: FastAPI (Python 3.12)
• Database: PostgreSQL with SQLAlchemy 2.0 (Async)
• Migrations: Alembic
• Cache: Redis
• Storage: MinIO (S3 compatible)
• Reporting: WeasyPrint for PDF generation

Requirements

• Docker and Docker Compose
• Python 3.10+ for local checks outside Docker
• GNU Make for the shortcuts in Makefile

Repository Structure

api.colo.ai/
├── alembic/              # Database migration scripts
├── app/
│   ├── api/              # API Routes (v1)
│   ├── core/             # Config, Security, S3, Logging
│   ├── db/               # Session management and Models
│   ├── main.py           # Application entry point
│   └── models/           # SQLAlchemy models
├── docker-compose.yml    # Production infrastructure
├── docker-compose.dev.yml # Local development infrastructure
├── pyproject.toml        # Build configuration
└── requirements.txt      # Project dependencies

Environment

Copy the example file and set real secrets:

cp .env.example .env

Required production-like variables:

• POSTGRES_PASSWORD
• SECRET_KEY
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• BACKEND_CORS_ORIGINS

The default .env.example values are for local development only.

Docker Workflow

Validate configuration:

make compose-config

Build and start the full stack:

make up-build

Run database migrations:

make migrate

Check service health:

make smoke

Useful commands:

make ps
make logs-app
make down

The API is exposed at http://localhost:8080 by docker-compose.yml. Swagger UI is available at http://localhost:8080/docs.

Local Development

1. Infrastructure

Start the required services (DB, Redis, S3) using Docker:

docker compose -f docker-compose.dev.yml up -d

2. Application Setup

It is recommended to use a virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Database Migrations

Apply migrations to set up the database schema:

alembic upgrade head

4. Running the Service

uvicorn app.main:app --reload

The API will be available at http://localhost:8000. Documentation (Swagger UI) is available at http://localhost:8000/docs.

Run checks:

make compile
make test
make openapi

Key Features

• Async Database Operations: Efficiently handles multiple requests using asyncpg.
• S3 Integration: Abstracted storage layer for medical images.
• Structured Logging: JSON-ready logs for production monitoring.
• CORS Support: Configured for seamless frontend integration.
• Health Checks: Endpoint for container orchestration health monitoring.

Deployment Notes

• docker-compose.yml expects explicit secrets and will fail fast if required values are missing.
• Postgres and Redis have health checks; backend waits for them before starting.
• MinIO is started before backend and the API ensures the configured bucket exists on startup.
• Non-admin API users are scoped to their assigned clinic for patients and studies.