From 3ec509ec2e2fdf6b5acae835774787d9f3a6c9d4 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Wed, 3 Dec 2025 20:47:15 -0500 Subject: [PATCH] docs: Update GEMINI.md with session learnings --- GEMINI.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 80 insertions(+), 8 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index 626be8a..e09eac4 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,12 +1,86 @@ # Gemini Added Memories -## Learnings from session (December 3, 2025): +## 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. -* **V2 CRUD Endpoint:** API simplification will be centered around the generic `/v2/crud` endpoint defined in `app/routers/api_crud_v2.py`. This is the modern, preferred implementation over the v1 endpoint in `api_crud.py`. -* **Data-Driven Configuration:** The v2 endpoint is highly modular and configured via the `obj_type_kv_li` dictionary in `app/ae_obj_types_def.py`. This dictionary acts as a central registry, mapping URL object strings to their corresponding database tables, Pydantic models, and export configurations. New simple CRUD objects can be added just by updating this dictionary. -* **Complex Filtering with `jp`:** The generic list handler (`handle_get_obj_li`) supports advanced filtering. While it has basic support for foreign key lookups via `for_obj_type` and `for_obj_id` parameters, more complex queries, such as those involving polymorphic relationships (e.g., filtering `journal` by a `user` using `for_type` and `for_id` columns), must be handled by the client. The client should construct and send a custom query using the powerful `jp` (JSON payload) query parameter. -* **Migration Plan Focus:** The user prefers to remain in a planning and documentation phase. The immediate goal is to update the `API_SIMPLIFICATION_PLAN.md` with detailed migration steps, rather than executing code changes directly. +* **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): @@ -18,6 +92,4 @@ * **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. - ---- +* **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. \ No newline at end of file