Athena Project Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• pyproject.toml
• src/athena_cli/commands/env.py
• src/athena_cli/commands/db.py
• tests/unit/transports/test_health.py

Athena is an osu! bancho-compatible private server implemented as a Python-based modular monolith. The project is designed to address common issues in existing bancho implementations by providing a codebase that is Pythonic, well-partitioned, and ready for horizontal scaling. It focuses on preserving externally observable behavior for stable osu! clients through the Bancho binary protocol and legacy web endpoints, while maintaining clean internal boundaries.
Sources: README.md:1-12, AGENTS.md:20-25

The project is currently in an early-stage proof-of-concept phase. It serves as an architectural experiment to validate the use of hexagonal adapters, command/query use-case splitting, and Unit of Work persistence within a Python environment.
Sources: README.md:14-22

Architectural Design

Athena follows a layered modular monolith architecture utilizing hexagonal adapters. The dependency flow moves from the outer composition layer toward core domain logic and shared primitives.

Layered Dependency Structure

The system enforces a strict dependency direction to ensure maintainability and testability.

The diagram shows the production dependency direction where outer layers import inner layers but never vice versa.
Sources: AGENTS.md:131-140, README.md:36-40

Layer	Responsibility
Composition	Dishka providers and runtime graph construction. Wires dependencies.
Runtime Adapters	Transport-specific logic like Starlette routes and taskiq tasks.
Use-Cases	Business workflows split into Commands (mutation) and Queries (read-only).
Domain	Transport-independent business language, policies, and @dataclass models.
Repositories	Persistence ports and implementations (SQLAlchemy, Memory, Valkey).
Infrastructure	Low-level drivers for PostgreSQL, Valkey, and messaging.
Sources: AGENTS.md:141-155, README.md:42-53

Command / Query Responsibility Segregation (CQRS)

Athena separates workflows based on state mutation.

• Commands: Own business rules, authorization, and mutation workflows. They open a Unit of Work for durable consistency. Sources: AGENTS.md:166-169
• Queries: Read-only display and search workflows. They use query repositories and do not require a Command Unit of Work. Sources: AGENTS.md:170-172

Technology Stack

The project leverages modern Python tooling and infrastructure for high performance and strict type safety.

• Language: Python 3.14+ with strict basedpyright type checking.
• Web Framework: Starlette and FastAPI.
• Persistence: SQLAlchemy 2.0 (asyncpg) for PostgreSQL; valkey-glide for volatile state.
• Background Jobs: taskiq with Redis/Valkey broker.
• Dependency Injection: Dishka.
• Packaging: uv and Nix flakes.
  Sources: AGENTS.md:30-45, pyproject.toml:1-30

Execution Model

Athena operates using a two-process model to balance responsiveness and heavy computation.

The diagram illustrates the separation between the app process (handling I/O) and the worker process (handling heavy logic like PP calculation).
Sources: AGENTS.md:354-360

Transport and Compatibility

Athena supports multiple client families through explicit transport boundaries.

Stable Client Support

Stable clients are supported via two primary families:

1. Bancho Binary Protocol: Uses the Caterpillar library for little-endian packet modeling. Handlers are located in transports/stable/bancho/.
2. Web Legacy: PHP-compatible endpoints for registration, score submission, and beatmap file resolution.
   Sources: README.md:95-101, AGENTS.md:275-285

Lazer and API Boundaries

Lazer clients utilize REST API v2 and SignalR. These are kept independent of the stable compatibility logic to allow their runtime behavior to evolve separately.
Sources: README.md:9-12, AGENTS.md:290-293

Athena CLI

The project includes a management tool (athena) for environment and database operations.

• Environment Management: Generating .env files from schemas and interactive prompts. Sources: src/athena_cli/commands/env.py:33-40
• Database Operations: Creating databases, running migrations via Alembic, and setting up development environments. Sources: src/athena_cli/commands/db.py:28-50

# Example of database setup command implementation
def _setup_database(*, environment: str | None) -> None:
    _ = _create_database(environment=environment)
    _migrate_database(environment=environment)
    typer.echo("Database setup complete.")

Sources: src/athena_cli/commands/db.py:108-111

Development and Quality Assurance

The project enforces high standards for code quality through mandatory checks.

Quality Gates

Command	Purpose
./scripts/ci.sh quality	Runs ruff (lint/format), basedpyright, and import-linter.
./scripts/ci.sh test	Runs the pytest suite.
prek run --all-files	Runs pre-commit hooks.
Sources: AGENTS.md:71-77, README.md:78-88

Health Monitoring

The server provides health endpoints to verify runtime status and infrastructure connectivity.

• GET /: Returns basic version and commit info in text/plain format.
• GET /health: Returns a JSON response indicating the status of PostgreSQL and Valkey connections.
  Sources: tests/unit/transports/test_health.py:12-20, 145-160

Conclusion

Athena represents a modern architectural approach to osu! private server development. By enforcing strict layer boundaries, utilizing a modular monolith structure, and separating command/query responsibilities, it aims to provide a scalable and maintainable alternative to existing implementations. While currently a proof-of-concept, its foundational structure supports horizontal scaling and multi-client compatibility through well-defined transport adapters.
Sources: README.md:14-25, AGENTS.md:131-135