Architecture Overview - Documentation

Gravity — Architecture Overview

Gravity is a multi-agent AI orchestration platform for local autonomous software development. Built as a .NET 10 Windows Forms desktop application, it provides a chat-driven interface where users describe tasks in natural language and AI agents autonomously explore codebases, plan changes, execute shell commands, and produce code modifications.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          UI Layer                               │
│  Form1 (WinForms)  ←→  WPF Controls (via ElementHost)         │
│  Chat Bubbles │ Artifacts │ Editor (AvalonEdit) │ Sidebar       │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────┴─────────────────────────────────────┐
│                     Orchestration Layer                         │
│  Orchestrator  ←→  IntentRouter  ←→  TaskPlanner               │
│  (Agent Pool)     (Layer 1)         (Layer 2)                  │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────┴─────────────────────────────────────┐
│                       Agent Layer                               │
│  ReasoningRouter (Command Resolution)                           │
│  ├─ FileAgent (code_editor)                                    │
│  ├─ ShellAgent (terminal)                                      │
│  ├─ KnowledgeAgent (knowledge)                                 │
│  ├─ GravityAgent (gravity)                                     │
│  ├─ SearchAgent (search)                                       │
│  ├─ DynamicAgent (JSON-defined)                                │
│  └─ McpAgent (MCP protocol)                                   │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────┴─────────────────────────────────────┐
│                      Service Layer                              │
│  IModelClient │ RagService │ KnowledgeService │ RoslynService  │
│  GitService │ FileSearchService │ BuildService │ McpClient     │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────┴─────────────────────────────────────┐
│                     Infrastructure                              │
│  Microsoft.Extensions.DependencyInjection                      │
│  ISettingsService (JSON persistence)                            │
│  OpenAI-compatible HTTP API │ MCP stdio protocol               │
└─────────────────────────────────────────────────────────────────┘

Core Pipeline: Router-Worker Architecture

Layer 1 — Intent Classification (`IntentRouter`)

The user's raw message is classified into intent types and a plan shape:

Intent Type	Description
`Conversational`	Greetings, small-talk, status questions
`CodeAnalysis`	Read-only exploration, search, explanation
`CodeEdit`	Write operations, fixes, refactoring
`ShellTask`	Build, test, compile commands
`KnowledgeQuery`	Architecture, patterns, "what does X do"
`FileStatsCount`	Line counts, sizes, existence checks
`Unknown`	Ambiguous, fall back to full agent loop

Layer 2 — Task Planning (`TaskPlanner`)

For TaskList intents, the planner compiles a concrete TaskPlan with steps that support output chaining via $stepN references.

Layer 3 — Agent Execution (`Orchestrator` + `AppEngine`)

The Orchestrator manages an agent pool (max 5 concurrent AppEngine instances). Each engine enters a reasoning loop, calls the LLM to decide which tool to invoke, routes tool calls through ReasoningRouter → target IAgent, feeds observations back, and produces a final answer.

Agent System

Built-In Agents

Agent	Name	Capabilities
`FileAgent`	`code_editor`	read_file, write_file, apply_diff, list_directory, search_in_files, glob, grep, delete, read_range
`ShellAgent`	`terminal`	run_command, dotnet, git, powershell, where
`KnowledgeAgent`	`knowledge`	list, read, add (SOP management)
`GravityAgent`	`gravity`	about, context, help, plan, propose, walkthrough
`SearchAgent`	`search`	web (Multi-resource search), fetch/read_url (Webpage scraping)

Dynamic Agents

JSON-defined agents loaded from agents/*.json at startup. They use the LLM as their reasoning engine and route tool calls through the shared ReasoningRouter.

MCP Agents

Agents backed by Model Context Protocol (MCP) servers. Spawned as child processes, communicate via stdio JSON-RPC.

Key Design Decisions

Hybrid WinForms + WPF — WinForms for layout control, WPF (via ElementHost) for rich rendering
Agent Pool with max concurrency — Limits resource usage while allowing parallel task execution
Router-Worker separation — Intent classification and task planning are separate LLM calls
Generic OpenAI-compatible client — Works with any OpenAI-compatible API
JSON-defined dynamic agents — Extensibility without code changes
MCP protocol support — First-class integration with the MCP ecosystem
Knowledge base as markdown — Human-readable, version-controllable SOPs
Obfuscation on publish — Uses Obfuscar for assembly obfuscation in Release builds