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-3, 2026)

• Logging Robustness: All core modules and routers now use module-level loggers (logging.getLogger(__name__)). app/log.py includes robust dictConfig initialization with error handling.
• Backward Compatibility: Hybrid object definitions ensure that /v2/crud continues to work by including both modern (tbl, mdl) and legacy (table_name, base_name) keys.
• FastAPI Best Practices: Standardized Response injection via response: Response type hints instead of Depends(Response).
• Documentation: Created V3_FRONTEND_API_GUIDE.md for Svelte/TypeScript integration and V3_CRUD_ARCHITECTURE_AND_LEARNINGS.md for backend maintenance.

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 (environment variables, container status, log accessibility) to better diagnose recurring startup and configuration issues.
2. Security - Field Allowlists (Priority: High): Finish populating searchable_fields for all remaining object definitions.
3. Security - Authentication (Priority: High): Continue refining and enforcing JWT-based authentication across all V3 endpoints.
4. Specialized Endpoints (Priority: Medium): Identify and plan the modernization of custom logic (e.g., importing, websockets) to match V3 patterns.
5. Directory Cleanup (Priority: Low): Long-term plan to archive old projects and standardize directory naming in OSIT_dev.
6. Unused Route Cleanup: Successfully commented out cont_edu_cert routers in main.py.