The Aether API is a high-performance, multi-tenant backend infrastructure built using the Python FastAPI framework. It serves as the central data and logic hub for the Aether Platform, supporting both legacy applications and modern V3/V4 standards.

🏗️ Architecture Overview

The API is currently in a transitional state between legacy (V1/V2) patterns and the modern V3 CRUD Architecture.

V3 CRUD (Modern)

Path: /v3/crud/
Core Principles:
- id_random Primary: All public communication uses URL-safe string IDs. Internal integer IDs are hidden.
- Nested URL Structure: Enforces parent-child relationships (e.g., /v3/crud/journal/{id}/entry/).
- Nested Advanced Search: Full support for POST-based search on nested objects.
- Granular Dependencies: Uses specialized FastAPI dependencies for Account Context, Pagination, Filtering, and Serialization.
- Advanced Search: POST-based search with recursive logic and standardized operators.
- Schema Discovery: Dynamic introspection of database and Pydantic models via /v3/crud/{obj_type}/schema.

V3 Actions

Path: /v3/action/
Handles complex binary operations and atomic business logic separately from standard metadata CRUD.
Key Features:
- Atomic Event Uploads: Marriage of physical storage and complex event relations in one request.
- Content-Addressable Downloads: Direct file retrieval by SHA256 hash for high-performance local caching.
- Intelligent ID Resolution: Standard download endpoints now automatically resolve container IDs (e.g., event_file) to underlying binaries.

Legacy API (V1/V2)

Path: /, /api/, /crud/, /v2/crud/
Maintained for backward compatibility but currently being systematically audited and deprecated.
Deprecation System: Accessing legacy routes triggers a !!! DEPRECATED ROUTE ACCESSED warning in logs.

🛠️ Core Technologies

Framework: FastAPI (v0.95.1)
Database: MariaDB (Remote Master) + SQLAlchemy (v1.4.52)
Caching/ID Resolution: Redis
Security: JWT (JSON Web Tokens) + API Key Machine Authorization
Logging: Structured logging with module-level isolation and rotation.

🚀 Getting Started

Local Development

Environment: Requires Python 3.9+.

Setup:

virtualenv environment
source environment/bin/activate
pip install -r requirements.txt

Run:

uvicorn app.main:app --host 0.0.0.0 --port 5005 --reload

Documentation: GUIDE__LOCAL_DEVELOPMENT.md

Deployment

The API is deployed via Docker Compose within the Aether Docker Environment (aether_container_env).
Configuration (Docker): All settings (Database, SMTP, Ports) are managed via the master .env file in the aether_container_env/ directory. No local .env file is required in this repository.
Manual Deployment: GUIDE__DEPLOYMENT_MANUAL.md

📂 Documentation Index

Architecture & Standards

V3 Core Architecture: Modular structure and boot sequence.
V3 Development Standards: ID Vision, inheritance, and naming rules.
Unified Agent Arch: Vision for cross-stack AI agent awareness.

Integration Guides

V3 Frontend API Guide: How to use the V3 CRUD and Search endpoints.
Frontend Code Samples: TypeScript snippets for common API calls.

Security

Project Security Hardening: Path towards cryptographic JWT verification.

🧪 Testing Suite

The project maintains an exhaustive test suite under the tests/ directory.

Unit Tests: tests/unit/ (Mocked logic).
Integration Tests: tests/integration/ (Local DB/Redis connectivity).
E2E Tests: tests/e2e/ (Network-based API validation).
Documentation: tests/README.md

🚧 Current Status & Work in Progress

Active Workstreams

[Backend] API Deprecation: Systematic pruning of orphaned routers and methods (ID: 111523094).
[ID Vision]: Phase 2 complete. String-ID standardization extended to Page, Post, Person, Journal, Contact, and User models.
[V3 Migration]: Implementation of atomic event actions and hash-based retrieval for high-performance Launcher caching complete.

Known Bugs / Issues

**Badge Rendering:**Corrupted numeric id fields in event_badge_template table causing template load failures in Svelte 5 views.
Websockets: Legacy websockets.py and websockets_redis.py require unification and stability improvements.
Intermittent Timeouts: Some E2E tests occasionally reproduce 403s/Timeouts on nested GET calls (investigating).

📜 Release Snapshot

Current Baseline: release/2026-01-28-v3_prod-snapshot (Stable v3.0.99).