¶ 🦦 OAPI — Otter API System
OAPI is a high-performance, asynchronous orchestration API built with Rust. It serves as the backbone logic for the Antre des Loutres community, handling complex image generation, real-time infrastructure monitoring, and external API integration.
¶ Core Features
¶ Dynamic Image Generation
Generate high-fidelity profile summary cards for Discord and Minecraft.
- Smart Caching: Uses SHA-256 state hashing to avoid redundant generation.
- Real-time Stats: Aggregates messaging activity, voice time, and Minecraft gameplay (playtime, distance, blocks).
- Rich Aesthetics: Custom font rendering, dynamic color pills, and automated avatar retrieval (Discord & Minecraft heads).
¶ Infrastructure Monitoring
Real-time health tracking for the entire community ecosystem.
- Multi-protocol: Supports HTTP(S) and Minecraft (TCP/SLP) status pings.
- Concurrent Checks: All services are polled in parallel for sub-second response times.
- Live Dashboard: A minimalist, modern web interface included.
¶ PocketBase Integration
A robust data layer powered by PocketBase.
- Admin Auth: Secure and automated administrative access to collections.
- Exhaustive Fetching: Custom pagination logic to retrieve complete historical data.
- Automatic Documentation: Fully compliant OpenAPI 3.0 spec generated via
utoipa.
¶ 🏗 Architecture
OAPI follows a strictly decoupled, layered architecture to ensure maintainability and testability:
| Layer | Responsibility |
|---|---|
| Handlers | HTTP entry points, parameter extraction, and status codes. |
| Actions | Use-case orchestration and external data fetching. |
| Services | Pure business logic and computationally intensive tasks. |
| Models | Strictly typed DTOs and OpenAPI schema definitions. |
| Utils | Generic HTTP fetchers, formatters, and global constants. |
¶ Configuration
The system uses a hierarchical YAML configuration management system.
default_config.yaml: The source of truth. Contains all default values and mandatory structure. (Committed to Git).config.yaml: Local overrides for environment-specific settings (local URLs, secret keys). (Ignored by Git).
On first run, the application automatically generates a config.yaml template if it is missing.
¶ Getting Started
¶ Prerequisites
- Rust (latest stable)
- A terminal with
cargoaccess
¶ Installation & Run
# Clone the repository
git clone https://github.com/matheo-1712/OAPI.git
cd OAPI
# Run in development mode
cargo run
¶ Accessing the API
- Swagger UI: http://localhost:3000/swagger-ui
- Monitoring Dashboard: http://localhost:3000/monitoring.html
¶ 🛠 Development & Quality
We maintain a Zero Warnings Policy. Every contribution must pass strict CI/CD checks.
¶ Pre-commit Workflow
Before pushing, ensure your code meets the quality standards:
# Format code
cargo fmt
# Check for lints and warnings
cargo clippy --all-targets --all-features -- -D warnings
# Run all tests
cargo test --all-features
¶ Documentation
Deep dives into specific modules:
- 📖 Architecture Overview (EN)
- 📡 Monitoring System (EN)
- 🖼 Image Generation Engine (EN)
- ⚙️ Configuration Management (EN)
- 🔌 PocketBase Integration (EN)
¶ Tech Stack
- Axum: Asynchronous web framework.
- Tokio: Multi-threaded runtime.
- Utoipa: Automatic OpenAPI documentation.
- Image-rs: Native image processing.
- Reqwest: Type-safe HTTP client.
- Tracing: Structured diagnostic logging.
Built by matheo-1712