41 lines
2.3 KiB
Markdown
41 lines
2.3 KiB
Markdown
# 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.
|
|
- **Lookup Hierarchy:** Implemented `ROW_NUMBER() OVER` logic for tiered overrides (Object > Account > Global).
|
|
- **Vision Comparison:** Discovered `load_site_obj` returns Random IDs for accounts; comparison in router must use `account_id_random` strings for reliable 403 authorization.
|
|
|
|
## 🤝 Coordination & Continuity
|
|
- **Handshake:** Use the `message` tool to notify the Frontend Agent of API changes.
|
|
- **Active Tasks:** Track your progress in `documentation/TODO__Agents.md`.
|
|
- **Lookup Milestone:** Batch 1 (Country, Subdivision, Timezone) complete. V3.1 goal set for Batch 2 and Novi-Mailman bridge.
|
|
- **Learning:** Review `ARCH__V3_CORE_STANDARDS.md` for V4 lifecycle field migration planning.
|