Arch: Finalize V3 Auth modularization and Unified Agent spec.
- Integrated zero-dependency Auth models and dependencies_v3.py. - Successfully resolved circular dependency boot loops. - Verified site_domain search exception via verify_v3_exceptions.py. - Refined Unified Agent Architecture with Storage Layer and API-driven access details. - Updated project roadmap and milestones in GEMINI.md.
This commit is contained in:
Scott Idem
62
GEMINI.md
62
GEMINI.md
@@ -11,55 +11,43 @@ I am the **primary orchestrator and main helper** for the development of the **U
|
||||
- **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.
|
||||
- **Circular Dependencies during Refactoring:** Even deferred imports can trigger boot failures during FastAPI's introspection phase if the module structure is fragile. "Isolation Mode" (local definitions in routers) is a confirmed temporary fix.
|
||||
- **V3 API Dependencies:** Standardized `Response` injection should use plain type hints (e.g., `response: Response`) to avoid router initialization failures.
|
||||
- **Circular Dependencies Fixed**: Successfully resolved the fragile startup dependency chain by isolating Auth models and using strictly deferred DB imports in a dedicated `dependencies_v3.py` module.
|
||||
- **Bootstrap Paradox Solved**: Implemented a guest-access exception for `site_domain` search, allowing the frontend to resolve site context without a JWT.
|
||||
- **VS Code Optimization**: Configured workspace settings to suppress markdownlint noise and enforce 4-space indentation for cleaner documentation.
|
||||
|
||||
### V3 Architectural Progress (Jan 2026)
|
||||
## Session Learnings & Progress (Jan 7, 2026) - MILESTONE
|
||||
|
||||
- **Modular Object Definitions:** Monolithic `ae_obj_types_def.py` refactored into domain-specific files in `app/object_definitions/`.
|
||||
- **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.
|
||||
### 1. Stability & Architecture
|
||||
- [x] **Permanent Dependency Fix**: Migrated `AccountContext` and Auth logic to dedicated modules (`auth_models.py`, `dependencies_v3.py`). This permanently resolved the "Worker failed to boot" issues.
|
||||
- [x] **Modularized `lib_general.py`**: Successfully extracted core functionalities into specialized modules:
|
||||
- `lib_email.py` (SMTP/Email)
|
||||
- `lib_export.py` (CSV/Excel Exports)
|
||||
- `lib_jwt.py` (JWT encoding/decoding)
|
||||
- `lib_hash.py` (Argon2 hashing)
|
||||
|
||||
## Session Learnings & Progress (Jan 2-7, 2026)
|
||||
### 2. V3 Search & Security
|
||||
- [x] **Site Domain Exception**: Implemented and verified unauthenticated search for `site_domain`.
|
||||
- [x] **Strict Multi-Tenant Isolation**: Enforced `account_id` filtering at the database level for all other V3 endpoints.
|
||||
|
||||
### V3 API Security Hardening (Jan 7, 2026) - MILESTONE
|
||||
- **Mandatory JWT Authentication**: Successfully implemented strict multi-tenant isolation across all V3 CRUD and Search endpoints.
|
||||
- **Account Isolation**: results are automatically filtered by `account_id` from the JWT.
|
||||
- **Bootstrap Paradox Exception**: `site_domain` search is explicitly allowed for unauthenticated guests to unblock site context resolution.
|
||||
|
||||
### Unified Agent Architecture
|
||||
- **Refined Specification**: Incorporated feedback from the Frontend Svelte agent. The Unified Agent will handle **Automated Schema Synchronization**, **Log Stream Aggregation**, and **Automated Lifecycle Management**.
|
||||
|
||||
### Infrastructure & Progress
|
||||
- [x] **Modularize `lib_general.py`**: Successfully extracted Email, Export, JWT, and Hash functions into specialized modules (`lib_email.py`, `lib_export.py`, `lib_jwt.py`, `lib_hash.py`).
|
||||
### 3. Unified Agent Platform
|
||||
- [x] **Initialized `aether_platform`**: Created the orchestrator root at `/home/scott/OSIT_dev/aether_platform/`.
|
||||
- [x] **Established Meta-Structure**: Linked `ae_api`, `ae_app`, and `ae_env` into the platform root via symbolic links.
|
||||
- [x] **Unified Agent Specification**: Published and refined the `UNIFIED_AGENT_ARCH.md` incorporating frontend agent feedback.
|
||||
|
||||
## Current To-Do List
|
||||
|
||||
### 1. High Priority & Urgent
|
||||
- [ ] **Initialize `aether_platform` Project** (Priority: High): Create the root directory at `/home/scott/OSIT_dev/aether_platform/` and establish the initial meta-structure.
|
||||
- [ ] **Unified Agent Architecture Document** (Priority: High): Refine and synchronize the final spec (Draft Done).
|
||||
- [ ] **Permanent Dependency Fix** (Priority: Urgent): Migrate `AccountContext` and Auth logic to a dedicated module.
|
||||
- [ ] **Unified Agent Core Logic**: Plan the implementation of the orchestrator's cross-stack diagnostic tools.
|
||||
- [ ] **Docker MCP Integration**: Re-attempt environment diagnostics using the correct python path (`./env_mcp/bin/python`).
|
||||
|
||||
### 2. Infrastructure & Environment
|
||||
- [ ] **Docker MCP Integration**: Re-attempt diagnostics using the correct python path (`./env_mcp/bin/python`).
|
||||
- [ ] **Agent Bridge Repair**: Resolve the `psutil` or syntax issues in `app/routers/agent_bridge.py`.
|
||||
- [ ] **Nginx Configuration**: Resolve 404 errors on Port 8888 routes.
|
||||
### 2. Infrastructure & Technical Debt
|
||||
- [ ] **Agent Bridge Repair**: Fix the `psutil` or syntax issues in `agent_bridge.py`.
|
||||
- [ ] **Nginx Configuration**: Finalize Port 8888 route proxying if needed.
|
||||
|
||||
### Workflow & Collaboration
|
||||
- **`GEMINI.md` Strategy:** Context flows up the tree.
|
||||
- **Agents Sync (rsync):** Shared documentation and notifications pushed to `~/agents_sync/`.
|
||||
- **Home Server:** Remote proxy at `https://dev-api.oneskyit.com`.- [x] **Establish Symbolic Links**: Linked API, App, and Env into aether_platform.
|
||||
- **Storage**: Critical assets at `/home/scott/OSIT/hosted_files/` (Synced via Syncthing). Files are often accessed directly via API download endpoints.
|
||||
- **Agents Sync**: Shared documentation and notifications pushed to `~/agents_sync/`.
|
||||
Reference in New Issue
Block a user