OSIT-AE-API-FastAPI/GEMINI.md

Gemini Added Memories

Learnings from session (December 3, 2025):

• 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.

Learnings from previous session (December 2, 2025):

• Docker Environment Challenges: Debugging issues in a Dockerized FastAPI environment when running locally (outside the container's execution context) is significantly more challenging due to environment mismatches and symlinked executables. Direct uvicorn execution for debugging is not viable in this setup. This necessitates an approach that can either:
  • Execute Python code snippets directly (e.g., for import validation).
  • Rely on external tools (like curl or requests from another script) to interact with the Dockerized API for runtime testing.
  • Assume that the Docker container provides the authoritative runtime environment, and local checks are primarily for static analysis (syntax, imports).
• Need for Incremental Verification: Given the complexity of the project and the debugging constraints, future changes must be exceptionally small, incremental, and verified through a robust testing strategy that can be executed, ideally, within the Docker environment or through isolated Python scripts.
• 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.

---