Aether API v3.00.x (FastAPI)

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

1. Environment: Requires Python 3.9+.
2. Setup:

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

3. 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, Search, and Action endpoints.
• V3 Frontend Websockets Guide: Websocket integration patterns.
• 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).