860cf80a4e
- 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.
48 lines
2.7 KiB
Markdown
48 lines
2.7 KiB
Markdown
# Aether V3 Development Standards & Strategy
|
|
|
|
This document serves as the master guide for the Aether API V3. It combines core architectural principles with the finalized infrastructure standards established in January 2026.
|
|
|
|
## 1. Core Principles
|
|
|
|
- **`id_random` Primary**: `id_random` (URL-safe string) is the only identifier exposed to clients. Internal integer `id` is a private implementation detail.
|
|
- **Singular naming**: All object types and prefixes use singular form (e.g., `journal`, not `journals`).
|
|
- **Inheritance**: All models must inherit from `CoreObject` to ensure consistent base fields.
|
|
- **Separation of Concerns**: Business logic lives in `app/methods/`, CRUD helpers in `app/lib_sql_crud.py`, and routing in `app/routers/`.
|
|
|
|
## 2. Infrastructure Standards
|
|
|
|
Finalized Jan 15, 2026, to ensure boot stability.
|
|
|
|
### Application Entry Point (`app/main.py`)
|
|
- **Registry Pattern**: All routers are registered via `app/routers/registry.py`.
|
|
- **Lifespan Management**: All startup tasks (logging setup, DB bootstrap, engine refresh) MUST reside within the `@contextlib.asynccontextmanager` lifespan.
|
|
- **No Top-Level Logic**: No SQL queries or heavy initialization should execute at the module level.
|
|
|
|
### Database Layering
|
|
- **`lib_sql_core.py`**: The foundational "Source of Truth" for the SQLAlchemy engine and global `db` connection.
|
|
- **`lib_sql_crud.py`**: High-level logic for `sql_insert`, `sql_select`, etc.
|
|
- **`db_sql.py`**: A backward-compatible facade. code should import from here.
|
|
|
|
### Logging
|
|
- **Explicit Setup**: `setup_logging(settings)` must be called during the lifespan startup.
|
|
- **`lib_log_v3.py`**: New home for logging configuration and the `logger_reset` decorator.
|
|
|
|
## 3. V3 CRUD Strategy
|
|
|
|
### URL Structure
|
|
- **Top-Level**: `/v3/crud/{obj_type}/`
|
|
- **Nested**: `/v3/crud/{parent_type}/{parent_id_random}/{obj_type}/` (Enforces parent ownership).
|
|
|
|
### Search API
|
|
- **POST Based**: Complex filtering is handled via `POST /search` with a JSON body containing `and`, `or`, and `not` logic.
|
|
- **Hybrid Filtering**: (Proposed) Query parameters should append simple standard filters (e.g., `?enabled=true`) to the complex body logic.
|
|
|
|
### Response Views (Proposed)
|
|
- Implement a `view` parameter (e.g., `?view=rich`) to allow clients to request joined data without using legacy `use_alt_tbl` flags.
|
|
|
|
## 4. Stability Rules
|
|
|
|
1. **Baby Step Testing**: Restart Docker and verify root health after *every* modular change.
|
|
2. **Avoid Shadowing**: Never name a module part of the `app.` package the same as a common instance variable (e.g., avoid `app.middleware` package if you use `app = FastAPI()`).
|
|
3. **Deferred Imports**: Use `from app.db_sql import ...` *inside* functions in library modules to prevent circular dependency traps.
|