OSIT-AE-API-FastAPI/documentation/UNIFIED_AGENT_ARCH.md

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.