Docs: Update Unified Agent Architecture and Platform Roadmap.
This commit is contained in:
Scott Idem
101
documentation/UNIFIED_AGENT_ARCH.md
Normal file
101
documentation/UNIFIED_AGENT_ARCH.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Specification: Unified Aether AI Agent (UE-AE-01)
|
||||
|
||||
## 1. Vision & Purpose
|
||||
The **Unified Aether AI Agent** is a single, cohesive AI entity designed to eliminate the friction of multi-agent coordination. It possesses "Total System Awareness," allowing it to understand how a change in the database schema on a remote server impacts the FastAPI backend, the Nginx proxy, and the SvelteKit frontend simultaneously.
|
||||
|
||||
---
|
||||
|
||||
## 2. System Architecture & Operational Domains
|
||||
|
||||
### A. Data Layer (MariaDB)
|
||||
* **Location:** Separate Virtual Server (Remote VM).
|
||||
* **Role:** Master data storage.
|
||||
* **Agent Access Requirements:**
|
||||
* Remote SQL execution capabilities.
|
||||
* SSH access for database maintenance and schema inspection.
|
||||
* Knowledge of cross-server connection strings and security groups.
|
||||
|
||||
### B. Caching & Messaging Layer (Redis)
|
||||
* **Location:** Docker Container (Main Workstation).
|
||||
* **Role:** Session management, ID resolution (Random ID mapping), and real-time messaging.
|
||||
* **Agent Access Requirements:**
|
||||
* Ability to execute `redis-cli` commands via Docker.
|
||||
* Direct inspection of key-value pairs for troubleshooting.
|
||||
|
||||
### C. API Backend Layer (FastAPI / Python)
|
||||
* **Location:** Docker Container (Main Workstation).
|
||||
* **Role:** Business logic, CRUD V3 implementation, JWT authentication, and multi-tenant isolation.
|
||||
* **Agent Access Requirements:**
|
||||
* Full filesystem access to `osit-api-fastapi/`.
|
||||
* Ability to manage Python environments and dependencies.
|
||||
* Docker container management (logs, restarts, shell execution).
|
||||
|
||||
### D. Frontend Layer (SvelteKit / TypeScript)
|
||||
* **Location:** Local Filesystem (Main Workstation).
|
||||
* **Role:** User Interface, API consumption, and client-side state management.
|
||||
* **Agent Access Requirements:**
|
||||
* Full filesystem access to SvelteKit project directories.
|
||||
* Ability to execute build tools (npm, vite) and linting (eslint, prettier).
|
||||
* Browser automation for E2E testing (Playwright).
|
||||
|
||||
### E. Routing Layer (Nginx)
|
||||
* **Location:** Host System or Docker.
|
||||
* **Role:** SSL termination and reverse proxying for the API and Frontend.
|
||||
* **Agent Access Requirements:**
|
||||
* Ability to modify and reload Nginx configuration files.
|
||||
* Diagnostic access to Nginx access/error logs.
|
||||
|
||||
### F. Storage Layer (Syncthing / Hosted Files)
|
||||
* **Location:** `/home/scott/OSIT/hosted_files/` (Main Workstation) and synchronized Remote Servers.
|
||||
* **Role:** Extremely important persistent storage for files served via the API (e.g., `hosted_file`, `event_file`).
|
||||
* **Synchronization:** Managed via **Syncthing** (similar to the `agents_sync` directory), ensuring real-time mirroring across the Aether ecosystem.
|
||||
* **Agent Access Requirements:**
|
||||
* Full filesystem access to the local hosted files directory.
|
||||
* Ability to verify synchronization status and resolve conflicts.
|
||||
* Understanding of the relationship between file metadata in MariaDB and physical assets in this directory.
|
||||
|
||||
### G. Workstation Development Environment
|
||||
* **Base Path:** `/home/scott/OSIT_dev/`
|
||||
* **Project Repositories:**
|
||||
* `aether_container_env/`: Docker Compose and environment configuration.
|
||||
* `aether_api_fastapi/`: The Python/FastAPI backend source.
|
||||
* `ae_app_svelte_tailwind_skeleton/`: The SvelteKit/TypeScript frontend source.
|
||||
* **Network & Proxy Path:**
|
||||
* Docker containers on the workstation are proxied via **Nginx on a separate Home Server** (Proxmox VM hosting Home Assistant, Jellyfin, Jitsi, etc.).
|
||||
* **External Access URL:** `https://dev-api.oneskyit.com`
|
||||
* **Agent Access Requirements:**
|
||||
* Total awareness of the inter-connected paths between these three main directories.
|
||||
* Knowledge of the home server's proxy logic to debug external connectivity vs. internal container health.
|
||||
|
||||
---
|
||||
|
||||
## 3. Communication & Context Strategy
|
||||
|
||||
### A. Integrated Global Memory
|
||||
The Unified Agent will move away from separate `GEMINI.md` files in favor of a **Global System Context**. This context tracks:
|
||||
1. **Service Map:** Mapping of ports, paths (e.g., `/v3/crud/`), and container IDs.
|
||||
2. **Dependency Graph:** Visualizing how modules across different repositories interact.
|
||||
3. **Boot Order Logic:** Understanding the fragile initialization requirements of the stack.
|
||||
|
||||
### B. Agent Sync Orchestration
|
||||
The agent acts as the primary orchestrator for the `~/agents_sync/` directory:
|
||||
- **Log Aggregation:** Pulling logs from MariaDB, FastAPI, and Nginx into a central diagnostic stream.
|
||||
- **Inbound Messaging:** Processing user instructions from the `inbox/` and updating "System Health" status files.
|
||||
|
||||
---
|
||||
|
||||
## 4. Key Capabilities
|
||||
|
||||
1. **Cross-Stack Debugging:** Tracing a "500 Internal Server Error" from a Svelte fetch call, through the Nginx proxy, into the FastAPI logic, and finally identifying the missing column in the remote MariaDB table.
|
||||
2. **Automated Schema Synchronization:** Reading Pydantic models and MariaDB table schemas to automatically generate and update TypeScript interfaces and `.editable_fields.ts` definitions in the Svelte project (`src/lib/ae_core/`).
|
||||
3. **Log Stream Aggregation:** Simultaneous monitoring of Svelte console output, Nginx access/error logs, and FastAPI container logs to provide instant root-cause identification for cross-stack failures.
|
||||
4. **Automated Lifecycle Management:** Orchestrating the "Change-Restart-Verify" loop. The agent should automatically trigger targeted Docker container restarts whenever backend code is modified to ensure the frontend is always interacting with the latest logic.
|
||||
5. **Environment-Aware Refactoring:** Safely breaking up monolithic files (like `lib_general.py`) while knowing exactly which services are impacted and verifying them across the full stack.
|
||||
6. **Automated Full-Stack Verification:** Writing a backend migration and a frontend UI component in a single turn, then verifying the integration with an automated test suite.
|
||||
|
||||
---
|
||||
|
||||
## 5. Security & Safety
|
||||
- **Credential Isolation:** Secrets and API keys remain in `.env` files; the agent only manages the logic to use them.
|
||||
- **Incremental Deployment:** Changes are applied service-by-service with health checks at every stage.
|
||||
- **Sandboxing Awareness:** The agent operates with the knowledge that it is running directly on the user's workstation and remote infrastructure.
|
||||
Reference in New Issue
Block a user