OSIT-AE-API-FastAPI/GEMINI.md

Aether Backend Agent Context: Gemini CLI Standard

Role: Aether API Orchestrator (Backend & System Architecture) Location: GEMINI.md (Project Root)

🚨 MANDATORY PROTOCOL

You must follow the safety, testing, and coordination standards defined in: documentation/GUIDE__DEVELOPMENT.md

---

🏗️ Technical Domain: Aether Backend

Stack & Infrastructure

• API Framework: FastAPI (v0.95+)
• Validation: Pydantic V1 (Strict)
• Database: MariaDB + SQLAlchemy (v1.4+)
• ID Standard: "ID Vision" - Public String IDs (id_random) mapping to hidden Internal Integer IDs.
• Communication: RAR Protocol (Request -> Ack -> Result).

V3 CRUD Architecture

• Enforce parallel CRUD and Search under /v3/crud/.
• Registry Pattern: Object definitions in app/object_definitions/, logic in app/methods/.
• Visibility: Use Field(exclude=True) in Pydantic to hide internal paths from public output.

Specialized Logic

• Universal ID Resolution: Resolve container IDs (e.g., event_file) to physical binaries in actions.
• Relational Joins: Prefer SQL INNER JOIN in Views (v_) over duplicating columns in tables.
• Heal-on-Read: Standardize fallback resolution for relational IDs during GET operations.

🧠 Technical Learnings

• Harden root_validator: Ensure pre-validation logic doesn't delete integer IDs during ID Vision resolution.
• Pydantic worker boot failures: Watch for ValueError, NameError, and KeyError during startup.
• Inherited Context: Account context for child objects should be inherited via View joins.

🤝 Coordination & Continuity

• Handshake: Use the message tool to notify the Frontend Agent of API changes.
• Active Tasks: Track your progress in documentation/AGENT_TODO.md.
• Learning: Review ARCH__V3_CORE_STANDARDS.md for V4 lifecycle field migration planning.