# Gemini Added Memories ## My Role and Operating Principles I am an interactive CLI agent assisting with software engineering tasks for One Sky IT, LLC, primarily on the Aether API project. My core mandates include: - Adhering to project conventions and existing code style. - **Never assuming library/framework availability; always verifying project usage.** - Implementing changes idiomatically and with minimal, high-value comments. - Being proactive, including adding tests for new features/fixes. - **Confirming ambiguity or actions beyond clear scope with the user.** - Prioritizing user control and project conventions. - **Strictly adhering to instructions and utilizing available tools effectively.** - **Awaiting explicit user instructions for significant architectural changes or critical decisions.** ## Project Context - Aether API (FastAPI) - **Owner/Developer:** Scott Idem (user). - **System Name:** Aether (AE). - **Purpose:** Events Presentation Management, Events Badge Printing, Leads, Attendee Tracking, Presentation Launcher, Journals, Archives, Posts. - **Started:** Mid-2018. - **Frontend History:** Python Flask -> Svelte (current: SvelteKit). This explains legacy API calls. - **Current API Version (FastAPI):** Roughly v2.5. - **Target API Version:** v3. ### API Versioning & Strategy - `/crud` (v1): Legacy, still used by some older frontend parts. Defined in `app/routers/api_crud.py`. **Remains untouched.** - `/v2/crud` (v2.5): Modern, preferred, and mostly functional endpoint. Defined in `app/routers/api_crud_v2.py`. **Remains untouched.** - `/v3/crud`: The goal of this project phase. A new, parallel implementation with a refined structure. **Will run alongside v1 and v2.** ### V3 Architectural Goals - **Nested URL Structure:** Enforce hierarchical relationships (e.g., `/v3/crud/{parent_type}/{parent_id}/{child_type}/...`). - **Dedicated Router:** All v3 functionality will reside in `app/routers/api_crud_v3.py`. - **Data-Driven Configuration:** Leverage `obj_type_kv_li` in `app/ae_obj_types_def.py` for object definitions (tables, models). ## Session Learnings & Progress (December 3, 2025) ### Strategy Shift & V3 Development * **Initial Plan Shift:** The strategy shifted from *migrating/replacing* existing v1/v2 routes to *building a new, parallel v3 implementation* from scratch. All existing v1/v2 routes will remain untouched. * **V3 Stub Endpoint (Phase 1 Completed):** Successfully created `app/routers/api_crud_v3.py` and mounted it at `/v3/crud` in `app/main.py` with a working `/health` endpoint. ### V3 CRUD Proof-of-Concept (Journal & Journal Entry - Phase 2 & 3 Completed) Implemented the full CRUD functionality for `journal` (top-level) and `journal_entry` (nested child object), demonstrating the v3 nested URL structure and its underlying logic: * **Top-Level Journal CRUD:** * `GET /v3/crud/journal/{journal_id}` * `GET /v3/crud/journal/` (list, with filtering via `for_obj_type`, `for_obj_id`, and `jp`) * `POST /v3/crud/journal/` * `PATCH /v3/crud/journal/{journal_id}` * `DELETE /v3/crud/journal/{journal_id}` * **Nested Journal Entry CRUD:** * `GET /v3/crud/journal/{journal_id}/journal_entry/` (list) * `POST /v3/crud/journal/{journal_id}/journal_entry/` * `GET /v3/crud/journal/{journal_id}/journal_entry/{entry_id}` * `PATCH /v3/crud/journal/{journal_id}/journal_entry/{entry_id}` * `DELETE /v3/crud/journal/{journal_id}/journal_entry/{entry_id}` ### V3 CRUD Refinements * **Soft-Delete Functionality:** `DELETE` endpoints now support a `method` query parameter (`delete`, `disable`, `hide`) for soft-deleting (setting `enable=False` or `hide=True`) or hard-deleting records, mirroring v2 behavior. * **Optional Delay Parameter:** All v3 CRUD functions include `x_delay_ms` (header) and `delay_ms` (query) parameters for simulating network latency or rate limiting via `time.sleep()`. ### Current Task: Common Parameters Refactoring (Reverted) * **Goal:** Refactor the current monolithic `commons: Common_Route_Params` dependency into smaller, more granular FastAPI dependencies. * **Status:** A full-scale refactoring was attempted, introducing a new `app/lib_general_v3.py` file and modifying `api_crud_v3.py`, `main.py`, and `models/response_models.py`. This resulted in persistent "Worker failed to boot" errors that were difficult to debug without direct log access. The changes were reverted to a known working commit (`98b980cf`) to restore application functionality. ### Operational Learnings * **File Location:** The `GEMINI.md` file must always be located in the project root directory. * **Communication for Major Refactoring:** For significant architectural changes, explicit user approval of a detailed proposal is required before implementation begins. * **Documentation Strategy:** Major proposals will be documented in dedicated Markdown files within the `documentation/` directory to facilitate clear communication and asynchronous feedback. * **Startup Errors & Logging:** The "worker failed to boot" error is highly indicative of an import-time error (e.g., circular dependency, missing module, or misconfiguration). A common cause is the logging configuration in `app/log.py` failing due to an uninitialized setting or file path issue. * **Refactoring Strategy - Incremental Approach Required:** The "big bang" approach to refactoring proved difficult to debug. A more incremental strategy is required for the next attempt: 1. **Isolate Logging:** First, refactor all modules (e.g., `main.py`, `models/response_models.py`) to instantiate their own module-level logger (`logger = logging.getLogger(__name__)`) instead of importing a global `log` instance from `app.log`. This will break potential circular dependencies related to logging. 2. **Introduce Dependencies One-by-One:** Introduce new dependencies from `lib_general_v3.py` one at a time. 3. **Apply to One Endpoint:** Apply each new dependency to a single, simple endpoint (like `health_check`) and confirm the application boots. 4. **Verify at Each Step:** This incremental verification is crucial in an environment without direct, real-time log access. * **Preservation of Work:** The attempted refactoring work has been preserved in `.snapshot` files for future reference. --- ## Learnings from previous session (December 2, 2025): * **Docker Environment Challenges:** Debugging issues in a Dockerized FastAPI environment when running locally (outside the container's execution context) is significantly more challenging due to environment mismatches and symlinked executables. Direct `uvicorn` execution for debugging is not viable in this setup. This necessitates an approach that can either: * Execute Python code snippets directly (e.g., for import validation). * Rely on external tools (like `curl` or `requests` from another script) to interact with the Dockerized API for runtime testing. * Assume that the Docker container provides the authoritative runtime environment, and local checks are primarily for static analysis (syntax, imports). * **Need for Incremental Verification:** Given the complexity of the project and the debugging constraints, future changes must be exceptionally small, incremental, and verified through a robust testing strategy that can be executed, ideally, within the Docker environment or through isolated Python scripts. * **Pydantic `BaseModel` Import:** Simple Pydantic `BaseModel` imports can be forgotten, leading to `NameError`. This highlights the need for automated linting or a minimal test harness that can quickly validate new model definitions in isolation. * **Legacy Code vs. New Code:** When encountering errors, it's crucial to distinguish whether the error is in the new code being introduced or in existing legacy code that might have subtle interactions. The `422 Unprocessable Entity` errors were occurring in the legacy `/crud/` endpoints. This indicates that while our new factory code *itself* didn't cause those specific runtime errors, interactions or an underlying pre-existing issue became apparent when the application was loading. * **`parent_table_name` for Nested CRUD:** The implementation detail of passing `parent_table_name` (or similar context) to child CRUD operations is essential for correctly linking nested resources in the database layer. The router factory's child object creation needs to pass this context explicitly. * **API Endpoint Naming Convention:** The user prefers singular nouns for API endpoints (e.g., `/journal`, `/journal_entry`) over plural forms (e.g., `/journals`, `/journal_entries`). This convention will be followed for all new router creations.