Go to file

Scott Idem bc78ac4c2e test: Add E2E test for V3 model refactoring verification

This commit introduces a new end-to-end test script  to validate the recent model refactoring changes.

The test suite performs two primary checks for a list of target objects:
- **ID Vision Compliance:** Verifies that all primary and foreign key fields are returned as string IDs, ensuring adherence to the V3 ID Vision standard.
- **Excluded Fields Stripping:** Attempts a PATCH operation with fields explicitly listed in  and verifies that these fields are not updated in the database, confirming the  mechanism functions as intended.

This test is essential for ensuring the stability and correctness of the API's interaction with the refactored models.

2026-02-24 16:22:19 -05:00

app

feat: Implement V3 ID Vision and fields_to_exclude_from_db across core models

2026-02-24 16:21:27 -05:00

documentation

fix: exclude account_id and virtual fields from archive_content DB writes

2026-02-24 11:30:17 -05:00

static

Enhance API robustness: Add model validators, view-field filtering, and test suite.

2026-01-09 15:36:28 -05:00

tests

test: Add E2E test for V3 model refactoring verification

2026-02-24 16:22:19 -05:00

.ae_brief

fix(v3-vision): prevent process hang on lu_ tables missing id_random

2026-02-10 17:30:38 -05:00

.gitignore

Updated ignore files

2024-10-09 13:42:31 -04:00

aether_api_fastapi.code-workspace

Minor changes and updates for AAPOR with Confex

2024-04-25 16:16:15 -04:00

GEMINI.md

Saving notes

2026-02-20 19:46:03 -05:00

README.md

docs: update README with V3 Actions progress and nested search support

2026-02-03 14:17:05 -05:00

README.md

Aether API (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

Environment: Requires Python 3.9+.

Setup:

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

Run:

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

Documentation: GUIDE__LOCAL_DEVELOPMENT.md

Deployment

The API is typically deployed via Docker Compose within the aether_container_env.
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).