178 lines
6.6 KiB
Markdown
178 lines
6.6 KiB
Markdown
# Architecture
|
|
|
|
## High-Level Design
|
|
|
|
Agentic OS is a multi-service Docker stack:
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
browser[Browser] --> frontend[Next.js Frontend]
|
|
frontend --> backend[FastAPI Backend]
|
|
backend --> postgres[(Postgres)]
|
|
backend --> redis[(Redis)]
|
|
worker[Worker] --> redis
|
|
worker --> agent[LangGraph Agent]
|
|
agent --> litellm[LiteLLM Gateway]
|
|
litellm --> ollama[Ollama on Host]
|
|
litellm --> cloud[Gemini DeepSeek OpenRouter]
|
|
worker --> mcp[MCP Sidecars]
|
|
mcp --> devices[Vessel Devices]
|
|
agent --> memory[Project Memory MCP]
|
|
agent --> obsidian[Obsidian Vault Git]
|
|
```
|
|
|
|
## Services
|
|
|
|
| Service | Location | Responsibility |
|
|
|---|---|---|
|
|
| `frontend` | `frontend/` | Next.js operator console, task UX, dashboard, rules, skills, models, inventory. |
|
|
| `backend` | `backend/app/` | FastAPI API, auth, schemas, inventory, tasks, MCP admin, balance polling. |
|
|
| `worker` | `backend/app/worker.py` | Consumes task queue, owns MCP manager, runs LangGraph task agent. |
|
|
| `postgres` | `docker-compose.yml` | Users, inventory, tasks, task events, approvals, balances, audit logs. |
|
|
| `redis` | `docker-compose.yml` | Task queue, live event pub/sub, cancel/escalate flags, MCP command queue/status. |
|
|
| `litellm` | `litellm/config.yaml` | Unified API for local Ollama and cloud providers. |
|
|
| MCP sidecars | `mcp-servers/` and cloned repos | Device-facing tool servers. |
|
|
|
|
## Backend Modules
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `backend/app/api/` | REST and WebSocket endpoints. |
|
|
| `backend/app/agent/` | LangGraph workflow, device profiles, playbooks, tool execution, MCP development. |
|
|
| `backend/app/mcp_manager/` | MCP repository sync, subprocess lifecycle, command queue, tool discovery. |
|
|
| `backend/app/services/` | Rules, skills, balance, model routing, report formatting, memory/Obsidian integrations, audit. |
|
|
| `backend/app/models/` | SQLAlchemy models. |
|
|
| `backend/alembic/` | Database migrations. |
|
|
|
|
## Frontend Modules
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `frontend/app/page.tsx` | Operations dashboard. |
|
|
| `frontend/app/tasks/page.tsx` | Task list and guided task creation. |
|
|
| `frontend/app/tasks/[id]/page.tsx` | Live task page, approvals, report, artifacts, run history. |
|
|
| `frontend/app/inventory/page.tsx` | Vessel and device management. |
|
|
| `frontend/app/mcp/page.tsx` | MCP server status and controls. |
|
|
| `frontend/app/rules/page.tsx` | Troubleshooting rules editor. |
|
|
| `frontend/app/skills/page.tsx` | Procedural skills editor/preview. |
|
|
| `frontend/app/models/page.tsx` | LLM routing configuration. |
|
|
| `frontend/components/` | Shared UI, task status, task report panels, app shell. |
|
|
| `frontend/lib/` | API client, auth context, shared task types. |
|
|
|
|
## Task Lifecycle
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
create[Create Task] --> preview[Preview Scope]
|
|
preview --> queue[Queue in Redis]
|
|
queue --> worker[Worker Picks Task]
|
|
worker --> context[Context Search]
|
|
context --> triage[Triage and Scope]
|
|
triage --> diagnose[Run MCP Diagnostics]
|
|
diagnose --> reason[LLM Reasoning Cascade]
|
|
reason --> report[Structured Report]
|
|
report --> approvals[Approval Requests]
|
|
report --> memory[Project Memory]
|
|
report --> obsidian[Obsidian Note]
|
|
report --> dashboard[Dashboard Summary]
|
|
```
|
|
|
|
### 1. Create and Preview
|
|
|
|
The frontend calls `POST /api/tasks/preview` with title, issue, and vessel. The backend uses `select_devices_for_issue()` from `backend/app/services/troubleshooting_rules.py` so preview and execution share the same routing logic.
|
|
|
|
### 2. Queue
|
|
|
|
`POST /api/tasks` inserts a `Task`, sets status `queued`, emits a `log` event, and pushes the task ID to Redis list `agentic:task_queue`.
|
|
|
|
### 3. Worker Execution
|
|
|
|
The worker consumes the queue, loads MCP servers, and calls `run_task_agent()` in `backend/app/agent/graph.py`.
|
|
|
|
### 4. LangGraph Pipeline
|
|
|
|
| Node | Responsibility |
|
|
|---|---|
|
|
| `context_step` | Search project-memory and Obsidian for related past investigations. |
|
|
| `triage_step` | Use local LLM plus rules/skills to plan checks and severity. |
|
|
| `diagnose_step` | Run device-specific or generic MCP diagnostics. |
|
|
| `reason_step` | Use tiered LLM cascade to interpret findings. |
|
|
| `report_step` | Build structured report, create approvals, save artifacts. |
|
|
|
|
### 5. Live Events
|
|
|
|
Events are sent through `publish_event()` in `backend/app/services/events.py`.
|
|
|
|
- Persisted events go to `task_events` and Redis pub/sub.
|
|
- Ephemeral high-frequency events such as `progress` and `tool_start` are streamed live but not stored.
|
|
- The frontend WebSocket `/api/tasks/{id}/stream` replays recent persisted events and then streams live ones.
|
|
|
|
### 6. Report Shape
|
|
|
|
Reports are JSON stored on the `tasks.report` column. New reports include:
|
|
|
|
- `executive_summary`;
|
|
- `scope_checked`;
|
|
- `findings`;
|
|
- `planned_steps`;
|
|
- `actions_taken`;
|
|
- `tools_run`;
|
|
- `diagnostics` with formatted evidence and raw metadata;
|
|
- `memory_id`, `memory_project_id`;
|
|
- `obsidian_path`, `obsidian_push_error`;
|
|
- LLM usage and cost fields.
|
|
|
|
Backward-compatible fields such as `summary`, `steps`, `devices_checked`, `root_cause`, and `resolution` remain available.
|
|
|
|
## Persistence
|
|
|
|
### Postgres
|
|
|
|
Stores durable application state:
|
|
|
|
- users and roles;
|
|
- vessels and devices;
|
|
- tasks, events, reports, approvals;
|
|
- balance snapshots;
|
|
- audit logs.
|
|
|
|
Database migrations live under `backend/alembic/`.
|
|
|
|
### Redis
|
|
|
|
Stores operational state:
|
|
|
|
- task queue;
|
|
- live task event channels;
|
|
- MCP command queue and status cache;
|
|
- task cancellation and LLM escalation flags.
|
|
|
|
### Project Memory
|
|
|
|
Task reports and durable operational facts are saved through an HTTP MCP server configured by `MEMORY_MCP_URL`. Task outputs use the project ID configured by `MEMORY_TASK_PROJECT_ID`.
|
|
|
|
### Obsidian
|
|
|
|
The backend clones the configured vault repository into `/runtime/obsidian-vault`, writes task notes under `OBSIDIAN_TASKS_FOLDER`, and commits/pushes when `OBSIDIAN_AUTO_PUSH=true`.
|
|
|
|
## MCP Integration Boundary
|
|
|
|
The application does not talk directly to infrastructure devices. It calls MCP tools. MCP servers hide the details of pfSense REST, Proxmox API/SSH, Asterisk shell/docker access, FortiGate/FortiSwitch APIs, and generic SSH.
|
|
|
|
This boundary makes the system extensible:
|
|
|
|
1. Add or clone an MCP server.
|
|
2. Add a device catalog entry if needed.
|
|
3. Add rules/skills so the agent knows when to use it.
|
|
4. Add diagnostics formatting for readable reports.
|
|
|
|
## Security Boundaries
|
|
|
|
- Device secrets are encrypted at rest.
|
|
- Real `.env` values must not be committed.
|
|
- MCP write tools are disabled by default unless each MCP explicitly enables writes.
|
|
- MCP self-development requires approval by default.
|
|
- Config-changing proposals are represented as approval requests before execution.
|
|
- Project memory and Obsidian should store references and summaries, not secret values.
|
|
|