# mrinalsunny/gemiflow architecture

> Architecture diagram of the GitHub repository mrinalsunny/gemiflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrinalsunny/gemiflow
- Repository: https://github.com/mrinalsunny/gemiflow

## Overview

1. **What this repo is**
   GemiFlow is a monorepo for a multi-agent CLI platform built around Gemini CLI, with a large v3 rewrite and a compatibility/plugin layer around it. The main runtime is TypeScript/Node, with a few Rust/WASM components for performance-sensitive and trust-sensitive paths.

2. **Top-level architectural split**
   The repo has three big surfaces:
   - **Core platform/runtime** in `v3/` and root CLI entrypoints.
   - **Plugin ecosystem** in `plugins/`, `plugin/`, `.claude-plugin/`, and generated `.gemiflow/` assets.
   - **Operational assets** in `docs/`, `verification/`, `scripts/`, `tests/`, `github/` workflows, and benchmark outputs.

3. **Primary execution path**
   User commands enter through the CLI (`bin/cli.js`, `v3/@gemiflow/cli/src/commands/*`) or through MCP (`v3/mcp`, `v3/@gemiflow/mcp`, shared MCP server code). Those entrypoints route into application services, which then call memory, swarm, security, plugin, or provider subsystems depending on the task.

4. **Orchestration and control plane**
   The orchestration layer lives in packages like `v3/@gemiflow/shared`, `v3/@gemiflow/swarm`, `v3/@gemiflow/hooks`, `v3/@gemiflow/integration`, and `v3/@gemiflow/cli`. This layer handles:
   - task dispatch
   - agent spawning and lifecycle
   - hooks and daemons
   - statusline/monitoring
   - worker pools and background automation
   It is the “brainstem” that keeps agent activity coordinated.

5. **Agent and swarm subsystem**
   `v3/@gemiflow/swarm` provides agent/task coordination, topology management, and consensus variants such as Raft, gossip, and Byzantine-style flows. Related packages in the root and `v3/plugins/*` expand this with specialized roles, worker dispatch, queen/coordinator patterns, and federated transport.

6. **Memory, retrieval, and learning**
   Memory is a major subsystem, centered in `v3/@gemiflow/memory`, `v3/@gemiflow/embeddings`, `v3/@gemiflow/neural`, `v3/@gemiflow/rag-memory`, and related packages. The flow is roughly:
   - capture task/session artifacts
   - embed and index them
   - retrieve via hybrid search / vector search / graph reasoning
   - feed results back into planning and routing
   This is what enables cross-session recall and self-improvement.

7. **Guidance and governance layer**
   `v3/@gemiflow/guidance` acts like a policy/control plane for capability gating, trust, proof, uncertainty, and memory writes. It also includes a WASM kernel (`v3/@gemiflow/guidance/wasm-kernel`) used for deterministic enforcement and scoring. In architecture terms, this sits between agent intent and tool execution.

8. **Security and trust boundaries**
   Security is not a sidecar here; it is a first-class boundary. `v3/@gemiflow/security`, `plugins/ruflo-aidefence`, `v3/plugins/prime-radiant`, and federation-related packages enforce:
   - input validation
   - path/tool output guardrails
   - plugin integrity checks
   - authorization propagation
   - PII filtering and trust scoring
   The federation stack is explicitly zero-trust and treats remote peers as untrusted until verified.

9. **Plugin architecture**
   The repo is built to be extended by plugins with a common shape: metadata, agents, commands, skills, MCP tools, and tests. Many packages under `plugins/` and `v3/plugins/` follow this pattern, exposing domain-specific capability bundles such as browser automation, cost tracking, workflows, neural trading, DDD, docs, and federation. The plugin registry/discovery code lives in `v3/@gemiflow/plugins`, `v3/@gemiflow/cli/src/plugins`, and shared plugin interfaces.

10. **External integration points**
   Material external dependencies include:
   - **LLM providers**: Gemini, OpenAI, Anthropic, Cohere, Ollama, OpenRouter/compatible endpoints
   - **Storage/backends**: SQLite/sqljs, AgentDB/RVF, Mongo in the web UI, GCS, IPFS
   - **Collaboration surfaces**: GitHub APIs/workflows, MCP servers, federation peers
   - **Cloud/runtime**: Supabase for the goal UI, Cloud Run/containers for some deployments
   These are plugged in through provider, storage, transport, and bridge packages rather than being hardwired into core logic.

11. **Web and product surfaces**
   There are separate product UIs outside the CLI:
   - `v3/goal_ui` for the GOAP planner and live agent dashboard
   - the hosted “flo.ruv.io” chat UI described in the README
   These are not the main runtime, but they consume the same orchestration and tool concepts as the CLI.

12. **Build, test, and verification pipeline**
   The repo is heavily instrumented with CI, smoke tests, benchmarks, and verification artifacts. Key boundaries here are:
   - package-level Vitest suites
   - repo-wide smoke/audit scripts
   - GitHub Actions workflows
   - verification manifests and witness data under `verification/`
   - benchmark corpora/results under `docs/benchmarks` and `v3/docs/benchmarks`
   This indicates the architecture is optimized not just for features, but for reproducibility and trust.

13. **How to draw the main diagram**
   A useful diagram would show:
   - **Clients**: Gemini CLI, MCP clients, hosted UIs
   - **Control plane**: CLI/MCP server, hooks, swarm/orchestrator, guidance/security
   - **Capability planes**: agents, plugins, workflows, federation, background workers
   - **State plane**: memory, embeddings, neural, RVF/AgentDB, event/ledger stores
   - **External systems**: LLM providers, GitHub, storage, cloud services, peer nodes
   The most important arrows are: user intent → orchestration → agent/tool execution → memory/learning → routing/planning feedback.

14. **Main architectural takeaway**
   This repo is less “one app” and more a platform for composing agentic systems. The stable seams are the control plane, memory/learning plane, security/trust boundary, and the plugin/MCP extension model. Everything else is built around those seams.

Main entry points: [`v3/@gemiflow/cli/src/index.ts`](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/cli/src/index.ts) (CLI App), [`v3/@gemiflow/security/src/index.ts`](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/security/src/index.ts) (Security), [`v3/mcp/server.ts`](https://github.com/mrinalsunny/gemiflow/blob/main/v3/mcp/server.ts) (MCP Server), [`v3/@gemiflow/memory/src/index.ts`](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/memory/src/index.ts) (Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_clients["Clients"]
  node_node_root_cli["Root CLI<br/>entrypoint<br/>[cli.js]"]
  node_node_mcp_server["MCP Server<br/>runtime<br/>[server.ts]"]
  node_node_goal_ui["Goal UI<br/>web ui<br/>[App.tsx]"]
end

subgraph group_group_control["Control Plane"]
  node_node_cli_app["CLI App<br/>command shell<br/>[index.ts]"]
  node_node_shared["Shared Core<br/>core runtime<br/>[index.ts]"]
  node_node_hooks["Hooks<br/>automation<br/>[index.ts]"]
  node_node_plugins_registry["Plugin Registry<br/>extension system<br/>[index.ts]"]
end

subgraph group_group_capabilities["Capabilities"]
  node_node_swarm["Swarm<br/>orchestration<br/>[index.ts]"]
  node_node_integration["Integration<br/>adapter layer<br/>[index.ts]"]
  node_node_workflows["Workflows<br/>pipeline<br/>[index.ts]"]
  node_node_plugins_suite["Plugin Packs<br/>domains<br/>[README.md]"]
end

subgraph group_group_state["State & Trust"]
  node_node_memory[("Memory<br/>state store<br/>[index.ts]")]
  node_node_embeddings(("Embeddings<br/>vector service<br/>[index.ts]"))
  node_node_neural(("Neural<br/>learning engine<br/>[index.ts]"))
  node_node_guidance{{"Guidance<br/>policy plane<br/>[index.ts]"}}
  node_node_security{{"Security<br/>trust boundary<br/>[index.ts]"}}
  node_node_providers["Providers<br/>llm adapters<br/>[index.ts]"]
  node_node_federation["Federation<br/>peer network<br/>[index.ts]"]
end

subgraph group_group_ops["Ops & Verification"]
  node_node_verification["Verification<br/>evidence<br/>[README.md]"]
end

node_node_root_cli -->|"launches"| node_node_cli_app
node_node_root_cli -->|"starts"| node_node_mcp_server
node_node_goal_ui -->|"consumes"| node_node_shared
node_node_cli_app -->|"uses"| node_node_shared
node_node_cli_app -->|"invokes"| node_node_hooks
node_node_cli_app -->|"orchestrates"| node_node_swarm
node_node_cli_app -->|"reads/writes"| node_node_memory
node_node_cli_app -->|"enforces"| node_node_guidance
node_node_cli_app -->|"guards"| node_node_security
node_node_cli_app -->|"routes to"| node_node_providers
node_node_cli_app -->|"discovers"| node_node_plugins_registry
node_node_cli_app -->|"triggers"| node_node_workflows
node_node_mcp_server -->|"shares"| node_node_shared
node_node_mcp_server -->|"validates"| node_node_security
node_node_mcp_server -->|"exposes"| node_node_plugins_registry
node_node_swarm -->|"delegates"| node_node_integration
node_node_integration -->|"adapts"| node_node_providers
node_node_integration -->|"persists"| node_node_memory
node_node_memory -->|"indexes"| node_node_embeddings
node_node_embeddings -->|"feeds"| node_node_neural
node_node_neural -->|"informs"| node_node_guidance
node_node_guidance -->|"delegates"| node_node_security
node_node_plugins_suite -->|"extends"| node_node_plugins_registry
node_node_workflows -->|"produces"| node_node_verification
node_node_security -->|"audits"| node_node_verification
node_node_federation -->|"trusts through"| node_node_security
node_node_federation -->|"connects"| node_node_swarm
node_node_federation -->|"syncs"| node_node_memory

click node_node_root_cli "https://github.com/mrinalsunny/gemiflow/blob/main/bin/cli.js"
click node_node_mcp_server "https://github.com/mrinalsunny/gemiflow/blob/main/v3/mcp/server.ts"
click node_node_goal_ui "https://github.com/mrinalsunny/gemiflow/blob/main/v3/goal_ui/src/App.tsx"
click node_node_cli_app "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/cli/src/index.ts"
click node_node_shared "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/shared/src/index.ts"
click node_node_hooks "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/hooks/src/index.ts"
click node_node_swarm "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/swarm/src/index.ts"
click node_node_integration "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/integration/src/index.ts"
click node_node_plugins_registry "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/plugins/src/index.ts"
click node_node_memory "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/memory/src/index.ts"
click node_node_embeddings "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/embeddings/src/index.ts"
click node_node_neural "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/neural/src/index.ts"
click node_node_guidance "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/guidance/src/index.ts"
click node_node_security "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/security/src/index.ts"
click node_node_providers "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/providers/src/index.ts"
click node_node_federation "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/plugin-agent-federation/src/index.ts"
click node_node_workflows "https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/deployment/src/index.ts"
click node_node_plugins_suite "https://github.com/mrinalsunny/gemiflow/blob/main/plugins/README.md"
click node_node_verification "https://github.com/mrinalsunny/gemiflow/blob/main/verification/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_root_cli,node_node_mcp_server,node_node_goal_ui toneBlue
class node_node_cli_app,node_node_shared,node_node_hooks,node_node_plugins_registry toneAmber
class node_node_swarm,node_node_integration,node_node_workflows,node_node_plugins_suite toneMint
class node_node_memory,node_node_embeddings,node_node_neural,node_node_guidance,node_node_security,node_node_providers,node_node_federation toneRose
class node_node_verification toneIndigo
```

## Components

### Clients

User-facing entrypoints and surfaces that initiate work.

- [Root CLI](https://github.com/mrinalsunny/gemiflow/blob/main/bin/cli.js): entrypoint · Top-level command entrypoint for the monorepo. · `bin/cli.js`
- [MCP Server](https://github.com/mrinalsunny/gemiflow/blob/main/v3/mcp/server.ts): runtime · Shared model-context protocol server and transport layer. · `v3/mcp/server.ts`
- [Goal UI](https://github.com/mrinalsunny/gemiflow/blob/main/v3/goal_ui/src/App.tsx): web ui · Planner/dashboard surface for live agent workflows. · `v3/goal_ui/src/App.tsx`

### Control Plane

CLI, MCP, orchestration, hooks, and policy enforcement.

- [CLI App](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/cli/src/index.ts): command shell · Main v3 command surface and command routing. · `v3/@gemiflow/cli/src/index.ts`
- [Shared Core](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/shared/src/index.ts): core runtime · Common config, event, hook, MCP, plugin, and resilience primitives. · `v3/@gemiflow/shared/src/index.ts`
- [Hooks](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/hooks/src/index.ts): automation · Hook execution, daemons, statusline, and worker coordination. · `v3/@gemiflow/hooks/src/index.ts`
- [Plugin Registry](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/plugins/src/index.ts): extension system · Plugin discovery, loading, trust, and package registry. · `v3/@gemiflow/plugins/src/index.ts`

### Capabilities

Agentic subsystems and extension packages that perform work.

- [Swarm](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/swarm/src/index.ts): orchestration · Agent/task coordination, topology, and consensus orchestration. · `v3/@gemiflow/swarm/src/index.ts`
- [Integration](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/integration/src/index.ts): adapter layer · Bridges between the core runtime and specialized workers/providers. · `v3/@gemiflow/integration/src/index.ts`
- [Workflows](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/deployment/src/index.ts): pipeline · Benchmark, deployment, release, and GAIA-style workflow automation. · `v3/@gemiflow/deployment/src/index.ts`
- [Plugin Packs](https://github.com/mrinalsunny/gemiflow/blob/main/plugins/README.md): domains · Domain plugins for browser, intelligence, cost, docs, QA, IO, and more. · `plugins/README.md`

### State & Trust

Memory, learning, provider, security, and federation boundaries.

- [Memory](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/memory/src/index.ts): state store · Persistent memory, retrieval, indexing, and migration subsystem. · `v3/@gemiflow/memory/src/index.ts`
- [Embeddings](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/embeddings/src/index.ts): vector service · Embedding, chunking, normalization, and cache-backed vector features. · `v3/@gemiflow/embeddings/src/index.ts`
- [Neural](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/neural/src/index.ts): learning engine · Pattern learning, routing, reasoning bank, and SONA integration. · `v3/@gemiflow/neural/src/index.ts`
- [Guidance](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/guidance/src/index.ts): policy plane · Capability gating, proof, trust, uncertainty, and deterministic enforcement. · `v3/@gemiflow/guidance/src/index.ts`
- [Security](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/security/src/index.ts): trust boundary · Input validation, path/output guardrails, integrity, and safe execution. · `v3/@gemiflow/security/src/index.ts`
- [Providers](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/providers/src/index.ts): llm adapters · Model-provider abstraction for Gemini, OpenAI, Anthropic, Ollama, and others. · `v3/@gemiflow/providers/src/index.ts`
- [Federation](https://github.com/mrinalsunny/gemiflow/blob/main/v3/@gemiflow/plugin-agent-federation/src/index.ts): peer network · Zero-trust peer coordination, discovery, claims, and transport for remote nodes. · `v3/@gemiflow/plugin-agent-federation/src/index.ts`

### Ops & Verification

Build, test, benchmark, docs, and release assets.

- [Verification](https://github.com/mrinalsunny/gemiflow/blob/main/verification/README.md): evidence · Smoke tests, benchmarks, witness data, and cross-platform validation artifacts. · `verification/README.md`

## Connections

- Root CLI → CLI App: launches · Root CLI delegates to the v3 command application.
- Root CLI → MCP Server: starts · CLI can also bootstrap the MCP server.
- Goal UI → Shared Core: consumes · UI reuses shared event and orchestration primitives.
- CLI App → Shared Core: uses · Command handling relies on shared config, hooks, MCP, and plugins.
- CLI App → Hooks: invokes · CLI commands activate hook and daemon automation.
- CLI App → Swarm: orchestrates · Agent spawning and task routing flow through swarm coordination.
- CLI App → Memory: reads/writes · CLI routes recall and persistence into the memory subsystem.
- CLI App → Guidance: enforces · Capability and trust decisions are mediated by guidance.
- CLI App → Security: guards · Inputs, paths, tool output, and plugin integrity are checked here.
- CLI App → Providers: routes to · Model access is abstracted through provider adapters.
- CLI App → Plugin Registry: discovers · CLI discovers and loads plugin capabilities through the registry.
- CLI App → Workflows: triggers · Higher-level workflows and benchmarks are launched from commands.
- MCP Server → Shared Core: shares · MCP server uses the same core abstractions as the CLI.
- MCP Server → Security: validates · Protocol payloads and tool surfaces are validated at the boundary.
- MCP Server → Plugin Registry: exposes · Plugins register tools and prompts over MCP.
- Swarm → Integration: delegates · Swarm coordination hands work to integration workers and bridges.
- Integration → Providers: adapts · Workers and routers call into model providers through adapters.
- Integration → Memory: persists · Worker and agent activity feeds memory and retrieval.
- Memory → Embeddings: indexes · Memory uses embeddings for search and retrieval.
- Embeddings → Neural: feeds · Embedding and retrieval signals support learning and routing.
- Neural → Guidance: informs · Learning signals contribute to policy, scoring, and gating.
- Guidance → Security: delegates · Guidance enforcement depends on security primitives and trust checks.
- Plugin Packs → Plugin Registry: extends · Domain plugins are installed and discovered through the registry.
- Workflows → Verification: produces · Automated runs emit evidence, benchmarks, and witness artifacts.
- Security → Verification: audits · Security checks are corroborated by verification artifacts.
- Federation → Security: trusts through · Remote peers remain untrusted until authenticated and evaluated.
- Federation → Swarm: connects · Federation extends swarm coordination across peers.
- Federation → Memory: syncs · Claims and shared state can be propagated through memory-backed flows.