Hecate Sentinel

Authentication and Authorization API built with FastAPI.

• Python 3.14+
• PostgreSQL 18+
• uv

Or alternatively:

• Docker and Docker Compose

1. Install dependencies:

uv sync

2. Set up PostgreSQL database and configure environment variables:

cp .env.example .env
# Edit .env with your database credentials

The easiest way to run the service is with Docker Compose.

1. Copy and configure environment variables:

cp .env.example .env
# Edit .env - at minimum set SECRET_KEY

2. Start the services:

docker compose up -d

View logs:

docker compose logs -f api

Stop services:

docker compose down

Stop and remove volumes (reset database):

docker compose down -v

Rebuild after code changes:

docker compose build && docker compose up -d

Start the development server:

uv run uvicorn src.main:app --reload

With custom host and port:

uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000. Interactive docs at http://localhost:8000/docs.

Note: Migrations are automatically applied on startup (upgrade to head).

Migrations are managed with Alembic.

Auto-generate migration from model changes:

uv run alembic revision --autogenerate -m "description of changes"

Create an empty migration:

uv run alembic revision -m "description of changes"

Upgrade to the latest version (head):

uv run alembic upgrade head

Upgrade by one revision:

uv run alembic upgrade +1

Apply a specific migration by revision ID:

uv run alembic upgrade <revision_id>

Downgrade by one revision:

uv run alembic downgrade -1

Downgrade to a specific revision:

uv run alembic downgrade <revision_id>

Downgrade to base (remove all migrations):

uv run alembic downgrade base

Show current revision:

uv run alembic current

Show migration history:

uv run alembic history

Show pending migrations:

uv run alembic history --indicate-current

Tests require a PostgreSQL test database. By default, tests use:

postgresql+asyncpg://hecate:hecate@localhost:5432/hecate_sentinel_test

Override with the TEST_DATABASE_URL environment variable if needed.

uv run pytest

With verbose output:

uv run pytest -v

Core utility tests:

uv run pytest tests/core/ -v

Service tests:

uv run pytest tests/services/ -v

API endpoint tests:

uv run pytest tests/api/ -v

uv run pytest tests/api/test_auth.py -v

uv run pytest tests/api/test_auth.py::TestAuthLogin::test_login_success -v

uv run pytest --cov=src --cov-report=term-missing

Generate HTML coverage report:

uv run pytest --cov=src --cov-report=html

uv run pytest -n auto

hecate-sentinel/
├── alembic/              # Database migrations
│   ├── versions/         # Migration scripts
│   └── env.py            # Alembic configuration
├── src/
│   ├── api/              # API route handlers
│   ├── core/             # Core utilities (security, geoip, etc.)
│   ├── models/           # SQLAlchemy models
│   ├── schemas/          # Pydantic schemas
│   ├── services/         # Business logic services
│   └── main.py           # Application entry point
├── tests/
│   ├── api/              # API endpoint tests
│   ├── core/             # Core utility tests
│   ├── services/         # Service tests
│   └── conftest.py       # Test fixtures
├── alembic.ini           # Alembic settings
├── compose.yaml          # Docker Compose configuration
├── Dockerfile            # Container build instructions
├── pyproject.toml        # Project dependencies
└── pytest.ini            # Pytest configuration