OSIT-AE-API-FastAPI/GEMINI.md

# 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).
-   **Current API Version (FastAPI):** v4.9.0.
-   **V3 Implementation:** Modern parallel CRUD and Search endpoints under `/v3/crud`.

### API Versioning & Strategy

-   `/crud` (v1): Legacy, still used by older frontend parts.
-   `/v2/crud` (v2.5): Modern, preferred, and mostly functional endpoint.
-   `/v3/crud`: The goal of this project phase. A new, parallel implementation with a refined structure and advanced search. **Runs alongside v1 and v2.**

### Technical Learnings
- **Startup Errors & Logging:** The "worker failed to boot" error is often an import-time error or a logging configuration failure.
    - **Root Cause:** If `logging.config.dictConfig` fails (e.g., due to missing `/logs` directories in Docker), the entire application crashes.
    - **Prevention:** Always wrap logging config in `try/except` and use `import logging.config` explicitly.
    - **Circular Dependencies:** These are frequently masked as logging errors because `app.log` is imported very early in most files. Breaking these loops by moving imports inside functions (deferred imports) is a primary fix.
- **V3 API Dependencies:** Standardized `Response` injection should use plain type hints (e.g., `response: Response`) to avoid router initialization failures.
- **Pydantic Compatibility:** The current environment uses Pydantic v1.10. Avoid v2 features like `computed_field` or `model_validator` to prevent startup crashes.

### V3 Architectural Progress (Jan 2026)

-   **Modular Object Definitions:** Monolithic `ae_obj_types_def.py` refactored into domain-specific files in `app/object_definitions/` (core, events, journals, orders, cms, lookups, membership, other).
-   **Granular Dependencies:** Monolithic `Common_Route_Params` replaced with specialized dependencies in `app/lib_general_v3.py` (AccountContext, Pagination, StatusFilter, Serialization, Delay).
-   **Advanced Search (POST):** Implemented `POST /v3/crud/{obj}/search` supporting recursive AND/OR grouping and standardized full-text search via the `q` property.
-   **Security Hardening:** Implemented a 5-level recursion depth limit and a field allowlist (`searchable_fields`) for the Search API.
-   **Non-blocking Concurrency:** Standardized on `asyncio.sleep()` for delay simulation to prevent Gunicorn worker hangs.

## Session Learnings & Progress (Jan 2-6, 2026)

### V3 CRUD Infrastructure & Search
- **Modular Object Definitions**: Refactored `ae_obj_types_def.py` into modular domain files in `app/object_definitions/`.
- **Advanced Search Fixes**: 
    - Resolved account listing and search issues by implementing `get_supported_filters` in `api_crud_v3.py`. This helper automatically adjusts `status_filter` (enabled/hidden) based on model field support (e.g., handles tables missing the `hide` column).
    - Improved standardized full-text search (`q` parameter) in `sql_search_qry_part` with a dry-run check for the `default_qry_str` column. It now falls back to a `LIKE` search across all searchable fields if the column is missing.
    - Added support for the `%` wildcard in `q`, allowing it to bypass filtering and return all records.
- **Data Integrity & Aliasing**: Fixed a critical issue where aliased fields (like `account_id_random`) were returned as `null` by adding `allow_population_by_field_name = True` to Pydantic models (updated `Account_Base`, `Site_Domain_Base`, etc.).
- **Consolidated V3 Router**: Systematically cleaned up `api_crud_v3.py`, removing duplicate endpoint definitions and standardizing logic across all CRUD and Search routes.
- **Robust Error Handling**: Updated V3 routers to return 500 status codes on database failures instead of masking errors with empty result sets.

### Database Schema Insights
- Verified schema for core tables (`account`, `event`, `person`, `user`, `data_store`, `site`, `site_domain`).
- Noted that `site_domain` lacks a `hide` column, and `hosted_file_link` lacks both `hide` and `enable`.
- Most major tables now have a standardized `hide` column (added to `account` on Jan 6, 2026).

## Current To-Do List

1. **Docker Environment Insight Improvements (Priority: High)**: Implement methods/endpoints to give the agent more insight into the actual Docker runtime environment.
2. **Security - Field Allowlists (Priority: High)**: Finish populating `searchable_fields` for all remaining object definitions.
3. **Refactoring - Modularize `db_sql.py` (Priority: Medium)**: Given the file's size (>2200 lines), plan to split it into functional modules (Search Builder, Core CRUD, Redis Helpers) to improve maintainability and agent reliability.
4. **Specialized Endpoints (Priority: Medium)**: Plan modernization of custom logic (importing, websockets) to match V3 patterns.
5. **Security - Authentication (Priority: High)**: Continue refining and enforcing JWT-based authentication across all V3 endpoints.