Agentic-OS/docs/architecture.md

Architecture

High-Level Design

Agentic OS is a multi-service Docker stack:

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

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.