Lazer and Public APIs
Relevant source files
The following files were used as context for generating this wiki page:
Lazer and Public APIs represent modern transport boundaries within the Athena project. While the legacy stable client is supported through binary protocols and PHP-compatible endpoints, Lazer clients interact with the server via REST API v2 and SignalR. Public and Admin APIs provide Athena-specific endpoints for external integrations and administrative control. These components are strictly isolated from core domain logic to ensure that transport-specific wire formats and requirements do not leak into the business rules.
Sources: README.md:12-16, AGENTS.md:54-56
Architecture and Integration
The API infrastructure follows a hexagonal architecture where transports act as adapters. The lazer and api families are located under src/osu_server/transports/. They are responsible for parsing incoming requests, mapping them to domain-specific command/query inputs, invoking the relevant services, and serializing responses.
The following diagram illustrates the position of Lazer and Public APIs within the layered modular monolith:
This diagram shows the dependency flow where transport adapters call into the use-case layer.
Sources: AGENTS.md:95-103, README.md:43-52
Lazer Transport Family
The Lazer client family is split into two primary communication channels:
- REST API v2: Handles standard request-response cycles, such as retrieving beatmap metadata or user profiles.
- SignalR: Manages real-time state and notifications through persistent connections.
Local mappers within the transports/lazer/ package handle the conversion between Lazer-specific wire types and internal domain objects. This ensures that Pydantic models used for API I/O stay within the transport boundary and do not enter the domain layer.
Sources: AGENTS.md:211-212, src/osu_server/transports/lazer/api/mappers/init.py
Athena Public and Admin APIs
The project exposes first-party APIs under the api transport family:
- Public API: Intended for third-party integrations and client-agnostic features.
- Admin API: Provides endpoints for server management, user moderation, and configuration overrides.
Sources: AGENTS.md:213-214
Boundary and Isolation Rules
Athena enforces strict isolation between different transport families through import-linter. This prevents the Lazer implementation from depending on Stable-specific logic and vice versa.
Interaction constraints
The following table summarizes the mandatory isolation rules enforced at the architectural level:
| Source Module | Forbidden Modules | Reason |
|---|---|---|
osu_server.transports.lazer | osu_server.transports.stable, osu_server.transports.api | Prevent cross-client logic leakage. |
osu_server.transports.api | osu_server.transports.stable, osu_server.transports.lazer | Keep first-party APIs independent of specific clients. |
osu_server.transports.* | sqlalchemy, osu_server.repositories.sqlalchemy | Transports must not touch the DB directly; they must use services. |
osu_server.services | osu_server.transports | Use cases must remain transport-agnostic. |
Sources: pyproject.toml:153-157, tests/unit/test_architecture_boundary_contract.py:100-112
Data Flow for API Requests
When a Lazer client sends a request, it follows a specific execution path through the system:
This diagram demonstrates how transport-specific JSON is converted into domain commands before reaching persistence.
Sources: AGENTS.md:129-138, README.md:43-52
Technical Implementation Details
Configuration and Routing
APIs are configured via the AppConfig class, which uses pydantic-settings to load environment variables. Key routing configurations such as the server domain and host are managed here.
| Configuration Field | Type | Default | Description |
|---|---|---|---|
domain | str | athena.localhost | The base domain for API routing. |
server_host | str | 0.0.0.0 | The host address the server binds to. |
server_port | int | 8000 | The port for HTTP/REST traffic. |
max_request_body_size | int | 1,048,576 | Limit for API payload sizes (1MB). |
Sources: src/osu_server/config.py:38-48
Dependency Injection
Athena uses Dishka for dependency injection. Transport routes (Starlette/FastAPI) resolve their required services through the Dishka container. This allows the API layer to remain thin, focusing only on I/O while the business logic is injected at runtime.
Sources: AGENTS.md:73-77, pyproject.toml:23-24
Summary
The Lazer and Public APIs are essential transport adapters that bridge external clients with Athena's core business logic. By utilizing Starlette/FastAPI for routing and Pydantic for validation, the project maintains a modern, type-safe API surface. Strict structural boundaries ensure that Lazer-specific requirements, such as SignalR hubs and REST v2 mappers, remain isolated from the stable client compatibility layer and the underlying domain entities.
Sources: AGENTS.md:211-219, README.md:120-123