OSIT-AE-API-FastAPI/documentation/ARCH__V3_DEVELOPMENT_STANDARDS.md

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.

Field Evolution Checklist

When a table or view gains, loses, or renames fields, keep the API contract and search registry in sync:

1. Update the Pydantic model in app/models/ first so CRUD serialization matches the new shape.
2. Update the SQL view or table projection so GET and SEARCH responses actually return the field.
3. Update searchable_fields in app/object_definitions/ only for fields that should be searchable.
4. Add write-only, virtual, or view-only fields to fields_to_exclude_from_db when they must not be persisted.
5. Run the schema/search E2E tests that cover the object type before handing the change off.

For archive_content, the public field set now includes external_id and code, and future additions should follow the same order of operations.

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.