# 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/`).
    - **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 (uploads, streaming downloads) separately from standard metadata CRUD.

### **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]:** Transitioning Launcher file caching to V3 CRUD (ID: 173518010).

### **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 v4.9.0).