69 lines
5.8 KiB
Markdown
69 lines
5.8 KiB
Markdown
# 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`.
|