eaa18a1d45
Root cause: child model root_validators (Vision ID anti-leakage guard) strip
integer IDs before they can be serialized into the INSERT dict, causing MariaDB
to reject the INSERT with 'Field does not have a default value' (1364).
Fix: re-inject resolved_parent_id into data_to_insert after validated_obj.dict()
in post_child_obj(). This is safe — the integer was already verified against the
DB before model validation.
Affected (were all broken since ~2026-01-27):
- journal/{id}/journal_entry/
- event/{id}/event_session/
- event/{id}/event_person/
- event/{id}/event_registration/
- event/{id}/event_presenter/
- event/{id}/event_presentation/
- event/{id}/event_location/
- event/{id}/event_track/
- event/{id}/event_device/
- event/{id}/event_abstract/
- event/{id}/event_badge/ (different symptom: NULL FK)
Tests: add nested create lifecycle regression tests to test_e2e_v3_demo_parity.py
- POST + Vision check + DELETE for journal/journal_entry and event/event_session
- All 9 checks passing (7s)
Docs: update tests/README.md with accurate demo_parity description and
a 'When to Run Tests' matrix to prevent future gaps in coverage.
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_randomPrimary: 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 ACCESSEDwarning 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
.envfile in theaether_container_env/directory. No local.envfile 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
idfields inevent_badge_templatetable causing template load failures in Svelte 5 views. - Websockets: Legacy
websockets.pyandwebsockets_redis.pyrequire 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).