Go to file

Scott Idem 0f4b4d2f51 feat: Implement V3 ID Vision and fields_to_exclude_from_db across core models

This commit refactors numerous Pydantic models to align with the V3 ID Vision standard, ensuring that primary and foreign key fields are represented as clean string IDs in the API. It also introduces and populates the  ClassVar in each model to prevent view-only fields and linked objects from being inadvertently written to the database during PATCH/POST operations.

Specifically, this includes:
- Adding  to exclude view-derived or joined fields such as , , nested objects (e.g., , ), and convenience fields (e.g., ).
- Adjusting root validators to correctly map string IDs and strip internal integer IDs for API responses.
- Resolving a KeyError by adding  to .

These changes are crucial for maintaining data integrity and consistency with the V3 API architecture.

2026-02-24 16:21:27 -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

feat: add priority filtering and sort stability to V3 Lookup System

2026-02-20 17:18:21 -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).