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)

V3 CRUD Infrastructure & Security

• Modular Object Definitions: Successfully refactored the monolithic ae_obj_types_def.py into a domain-driven structure under app/object_definitions/. This improved maintainability while keeping legacy V2 keys for backward compatibility.
• Advanced Search (POST): Implemented a robust /search endpoint supporting recursive AND/OR logic and standardized full-text search via the q property.
• Security Hardening: Enforced a 5-level recursion depth limit and a field allowlist (searchable_fields) per object to prevent unauthorized data leaks.
• JWT Authentication: Implemented modern JWT validation for V3, supporting both the Authorization header and a jwt query parameter (enabling secure, header-free file downloads).
• Frontend Integration: Created a dedicated V3_FRONTEND_API_GUIDE.md to help the Svelte Gemini agent and developers migrate to the new endpoints.

Technical & Environment Stability

• Robust Logging: Standardized on module-level loggers and wrapped logging configuration in try/except to prevent Docker startup crashes.
• Circular Dependency Resolution: Identified and resolved a major circular dependency loop between lib_general_v3, response_models, and db_sql.
• FastAPI Standards: Fixed Response injection and parameter ordering issues that were causing "Worker failed to boot" errors.

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.