107 lines
4.9 KiB
Markdown
Executable File
107 lines
4.9 KiB
Markdown
Executable File
# 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**
|
|
1. **Environment:** Requires Python 3.9+.
|
|
2. **Setup:**
|
|
```bash
|
|
virtualenv environment
|
|
source environment/bin/activate
|
|
pip install -r admin/requirements.txt
|
|
```
|
|
3. **Run:**
|
|
```bash
|
|
uvicorn app.main:app --host 0.0.0.0 --port 5005 --reload
|
|
```
|
|
- **Documentation:** [GUIDE__LOCAL_DEVELOPMENT.md](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/GUIDE__DEPLOYMENT_MANUAL.md)
|
|
|
|
---
|
|
|
|
## 📂 Documentation Index
|
|
|
|
### **Architecture & Standards**
|
|
- [V3 Core Architecture](documentation/ARCH__V3_CORE.md): Modular structure and boot sequence.
|
|
- [V3 Development Standards](documentation/ARCH__V3_DEVELOPMENT_STANDARDS.md): ID Vision, inheritance, and naming rules.
|
|
- [Unified Agent Arch](documentation/ARCH__UNIFIED_AGENT.md): Vision for cross-stack AI agent awareness.
|
|
|
|
### **Integration Guides**
|
|
- [V3 Frontend API Guide](documentation/GUIDE__V3_FRONTEND_API.md): How to use the V3 CRUD and Search endpoints.
|
|
- [Frontend Code Samples](documentation/FRONTEND_API_SAMPLES.md): TypeScript snippets for common API calls.
|
|
|
|
### **Security**
|
|
- [Project Security Hardening](documentation/PLAN__SECURITY_HARDENING.md): 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](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). |