Documentation Standardisation & Unit Test Stabilization
- Overhauled README.md to serve as a unified system index and WIP tracker. - Standardized documentation filenames (ARCH__, GUIDE__, PLAN__) for better discoverability. - Archived completed project plans and scopes. - Fixed regressions in unit tests (errors, models, email) caused by V3 architectural updates. - Ensured unit tests remain non-destructive and environment-independent via mocking.
This commit is contained in:
Scott Idem
104
README.md
104
README.md
@@ -1,2 +1,102 @@
|
||||
# Aether API Python FastAPI
|
||||
The Aether API was created and is being developed by Scott Idem using the Python FastAPI framework.
|
||||
# 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).
|
||||
Reference in New Issue
Block a user