# ruvnet/open-agentics architecture

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

- Interactive diagram: https://gitdiagram.com/ruvnet/open-agentics
- Repository: https://github.com/ruvnet/open-agentics

## Overview

1. **Repository shape**
   - This is a monorepo with two real applications: `apps/web` for the product UI and `apps/docs` for the documentation site.
   - The root also contains workspace/build config (`package.json`, `turbo.json`, `tsconfig.json`, Yarn config) plus GitHub Actions CI.

2. **Primary runtime**
   - The product is a **Next.js App Router** frontend in `apps/web`.
   - Most domain logic lives in client-side React components, hooks, and providers rather than a traditional backend service inside this repo.

3. **Core external dependencies**
   - The app is designed around **LangGraph Platform** deployments: agents are fetched/configured through LangGraph APIs and proxied from the web app.
   - **LangConnect** is the RAG backend the UI expects for document/collection operations.
   - **Supabase** provides authentication and session management.
   - **MCP servers** provide external tool access.
   - The README also frames the product as a no-code orchestration layer for LangGraph agents, including agent supervision.

4. **Top-level product areas in the web app**
   - The main user-facing feature areas are:
     - **Agents**: create, edit, and manage agent configurations.
     - **Chat**: interact with a selected agent and configure runtime inputs.
     - **Inbox**: review interrupts, thread state, and agent actions.
     - **Tools**: browse tools and test them in a playground.
     - **RAG**: manage collections and documents.
     - **Auth**: sign in/up/reset flows.

5. **Application shell and routing**
   - `apps/web/src/app/(app)` contains the authenticated product shell, including the app layout and pages for agents, inbox, rag, and tools.
   - `apps/web/src/app/(auth)` contains unauthenticated auth pages and an auth layout.
   - `apps/web/src/app/layout.tsx` and global CSS establish the app-wide shell and styling.

6. **Authentication boundary**
   - Auth is isolated under `src/lib/auth`, `src/providers/Auth.tsx`, and `src/app/api/auth/callback`.
   - Middleware is used to gate routes and likely to keep session state aligned with Supabase.
   - This is an important architecture boundary: auth is handled in the frontend app, but the actual identity/session source is external.

7. **Agent management subsystem**
   - The `features/agents` area drives the “build and manage agents” experience.
   - It includes dashboards, templates, create/edit dialogs, graph selection, and agent cards.
   - The data model is centered around agent/deployment concepts in `src/types/agent.ts` and `src/types/deployment.ts`, which suggests agent UI is layered on top of deployment metadata rather than owned locally.

8. **Chat/runtime configuration subsystem**
   - `features/chat` is the interactive agent runtime UI.
   - It includes thread history, breadcrumbs, message renderers, configuration sidebar, and a streaming provider.
   - `hooks/use-agent-config.tsx`, `hooks/use-agents.tsx`, and `providers/Agents.tsx` indicate the selected agent/deployment is shared application state, while `providers/Stream.tsx` handles live message flow.

9. **Inbox and interrupt handling**
   - `components/agent-inbox` plus `features/inbox` implement the operational view for agent threads.
   - The structure focuses on thread state, interrupt details, tool-call inspection, pagination, and thread actions.
   - This subsystem is distinct from chat: it is for monitoring and resolving agent execution state, not just conversational interaction.

10. **Tools and MCP integration**
   - `features/tools` provides browsing, inspection, and a playground for tool schemas and responses.
   - `src/app/api/oap_mcp` and `providers/MCP.tsx` are the boundary for MCP requests/proxying.
   - The tool UI is built around schema-driven forms and tool metadata, which makes the architecture strongly “capability catalog + execution proxy.”

11. **RAG subsystem**
   - `features/rag` manages collections and documents, with dedicated hooks and a `providers/RAG.tsx` layer.
   - The README makes clear this depends on a separately hosted LangConnect RAG server, so the web app is only the control plane/UI.
   - This is another clear split: document ingestion/querying happen outside the repo, while the app handles configuration and visualization.

12. **API routes as service adapters**
   - The app contains small API route layers under `src/app/api` for auth callback, LangGraph defaults/proxying, and MCP proxying.
   - These routes act as adapters between the browser UI and external services, rather than a full backend domain layer.
   - `src/lib/client.ts` and shared lib code likely centralize HTTP/client concerns for these adapters.

13. **Shared UI and state infrastructure**
   - `src/components/ui` is a reusable design-system layer built from common primitives like dialogs, tables, sidebars, forms, and markdown rendering.
   - `src/providers` and `src/hooks` provide cross-cutting state for auth, agents, MCP, mobile responsiveness, search, scrolling, and config storage.
   - This indicates the app is organized as feature modules over a shared client-side foundation.

14. **Documentation site**
   - `apps/docs` is a separate docs application with MDX content for setup, quickstart, auth, MCP, RAG, and custom agents.
   - The docs mirror the product boundaries, which is useful when diagramming the ecosystem: the docs site supports onboarding for the same external systems the web app depends on.

15. **Build and delivery**
   - The repo uses a workspace/turbo-style setup and GitHub Actions CI.
   - There is no evidence of a large custom backend in this repository; the architecture is primarily a frontend orchestration layer over LangGraph, LangConnect, Supabase, and MCP services.

Main entry points: [`apps/web/src/app/(app)/layout.tsx`](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/(app)/layout.tsx) (App shell), [`apps/docs/index.mdx`](https://github.com/ruvnet/open-agentics/blob/main/apps/docs/index.mdx) (Docs site), [`apps/web/src/providers/Agents.tsx`](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/providers/Agents.tsx) (Shared state), [`apps/web/src/app/layout.tsx`](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/layout.tsx) (Product UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Workspace"]
  node_workspace["Workspace<br/>build/monorepo<br/>[package.json]"]
  node_ci["CI<br/>automation/gha<br/>[ci.yml]"]
end

subgraph group_web["Web app"]
  node_webapp["Product UI<br/>nextjs/app<br/>[layout.tsx]"]
  node_appshell["App shell<br/>routing/layout<br/>[layout.tsx]"]
  node_authroutes["Auth pages<br/>routing/auth<br/>[layout.tsx]"]
  node_authboundary["Auth boundary<br/>auth/supabase<br/>[middleware.ts]"]
  node_agents["Agents<br/>feature/management<br/>[index.tsx]"]
  node_chat["Chat<br/>feature/runtime<br/>[index.tsx]"]
  node_inbox["Inbox<br/>feature/ops<br/>[index.tsx]"]
  node_tools["Tools<br/>feature/catalog<br/>[index.tsx]"]
  node_rag["RAG<br/>feature/collections<br/>[index.tsx]"]
  node_sharedui["UI kit<br/>shared/design-system<br/>[button.tsx]"]
  node_sharedstate["Shared state<br/>shared/providers+hooks<br/>[Agents.tsx]"]
  node_apiroutes["API adapters<br/>api/routes<br/>[route.ts]"]
end

subgraph group_docs["Docs app"]
  node_docsapp["Docs site<br/>nextjs/docs<br/>[index.mdx]"]
end

node_langgraph[("LangGraph<br/>external/agent-platform")]
node_supabase[("Supabase<br/>external/auth")]
node_mcp[("MCP servers<br/>external/tools")]
node_langconnect[("LangConnect<br/>external/rag")]

node_workspace -->|"hosts"| node_webapp
node_workspace -->|"hosts"| node_docsapp
node_ci -->|"validates"| node_workspace
node_webapp -->|"routes to"| node_appshell
node_webapp -->|"routes to"| node_authroutes
node_webapp -->|"secures"| node_authboundary
node_appshell -->|"contains"| node_agents
node_appshell -->|"contains"| node_chat
node_appshell -->|"contains"| node_inbox
node_appshell -->|"contains"| node_tools
node_appshell -->|"contains"| node_rag
node_agents -->|"uses"| node_sharedstate
node_chat -->|"uses"| node_sharedstate
node_inbox -->|"uses"| node_sharedstate
node_tools -->|"uses"| node_sharedstate
node_rag -->|"uses"| node_sharedstate
node_authboundary -->|"backs onto"| node_supabase
node_apiroutes -->|"proxies"| node_langgraph
node_apiroutes -->|"proxies"| node_mcp
node_rag -->|"depends on"| node_langconnect
node_docsapp -.->|"documents"| node_authboundary
node_docsapp -.->|"documents"| node_mcp
node_docsapp -.->|"documents"| node_langconnect
node_docsapp -.->|"documents"| node_langgraph

click node_workspace "https://github.com/ruvnet/open-agentics/blob/main/package.json"
click node_ci "https://github.com/ruvnet/open-agentics/blob/main/.github/workflows/ci.yml"
click node_webapp "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/layout.tsx"
click node_appshell "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/(app)/layout.tsx"
click node_authroutes "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/(auth)/layout.tsx"
click node_authboundary "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/lib/auth/middleware.ts"
click node_agents "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/agents/index.tsx"
click node_chat "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/chat/index.tsx"
click node_inbox "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/inbox/index.tsx"
click node_tools "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/tools/index.tsx"
click node_rag "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/rag/index.tsx"
click node_sharedui "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/components/ui/button.tsx"
click node_sharedstate "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/providers/Agents.tsx"
click node_apiroutes "https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/api/langgraph/proxy/[..._path]/route.ts"
click node_docsapp "https://github.com/ruvnet/open-agentics/blob/main/apps/docs/index.mdx"

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_workspace,node_ci toneBlue
class node_webapp,node_appshell,node_authroutes,node_authboundary,node_agents,node_chat,node_inbox,node_tools,node_rag,node_sharedui,node_sharedstate,node_apiroutes toneAmber
class node_docsapp toneMint
class node_langgraph,node_supabase,node_mcp,node_langconnect toneNeutral
```

## Components

### Workspace

Monorepo-level build, typing, and CI setup.

- [Workspace](https://github.com/ruvnet/open-agentics/blob/main/package.json): build/monorepo · Yarn/Turbo workspace and shared repo configuration. · `package.json`
- [CI](https://github.com/ruvnet/open-agentics/blob/main/.github/workflows/ci.yml): automation/gha · GitHub Actions workflow for repository validation. · `.github/workflows/ci.yml`

### Web app

Next.js product UI and its client-side feature modules.

- [Product UI](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/layout.tsx): nextjs/app · Authenticated Next.js application for operating agents, tools, and RAG. · `apps/web/src/app/layout.tsx`
- [App shell](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/(app)/layout.tsx): routing/layout · Authenticated layout and main route grouping for the product area. · `apps/web/src/app/(app)/layout.tsx`
- [Auth pages](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/(auth)/layout.tsx): routing/auth · Sign-in and account recovery flows for unauthenticated users. · `apps/web/src/app/(auth)/layout.tsx`
- [Auth boundary](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/lib/auth/middleware.ts): auth/supabase · Supabase-backed session handling, callback route, middleware, and auth provider. · `apps/web/src/lib/auth/middleware.ts`
- [Agents](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/agents/index.tsx): feature/management · Agent dashboards, templates, create/edit flows, and deployment-aware configuration. · `apps/web/src/features/agents/index.tsx`
- [Chat](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/chat/index.tsx): feature/runtime · Interactive agent runtime view with thread history, config sidebar, and streaming messages. · `apps/web/src/features/chat/index.tsx`
- [Inbox](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/inbox/index.tsx): feature/ops · Operational thread review, interrupts, and agent action inspection. · `apps/web/src/features/inbox/index.tsx`
- [Tools](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/tools/index.tsx): feature/catalog · Tool browsing, detail inspection, and schema-driven playground execution. · `apps/web/src/features/tools/index.tsx`
- [RAG](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/features/rag/index.tsx): feature/collections · Collection and document management for the LangConnect-backed retrieval layer. · `apps/web/src/features/rag/index.tsx`
- [UI kit](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/components/ui/button.tsx): shared/design-system · Reusable client UI primitives, layout components, and common controls. · `apps/web/src/components/ui/button.tsx`
- [Shared state](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/providers/Agents.tsx): shared/providers+hooks · Cross-cutting providers and hooks for agents, auth, MCP, search, and device state. · `apps/web/src/providers/Agents.tsx`
- [API adapters](https://github.com/ruvnet/open-agentics/blob/main/apps/web/src/app/api/langgraph/proxy/[..._path]/route.ts): api/routes · Thin route handlers that proxy auth, LangGraph, and MCP requests. · `apps/web/src/app/api/langgraph/proxy/[..._path]/route.ts`

### Docs app

MDX documentation site for setup and product usage.

- [Docs site](https://github.com/ruvnet/open-agentics/blob/main/apps/docs/index.mdx): nextjs/docs · Separate documentation application with MDX content for setup and usage. · `apps/docs/index.mdx`

### Other components

- **LangGraph**: external/agent-platform · Primary agent platform used for deployments, defaults, and request proxying.
- **Supabase**: external/auth · External identity and session source for authentication.
- **MCP servers**: external/tools · External tool providers accessed through the MCP proxy boundary.
- **LangConnect**: external/rag · Separate RAG backend expected by the web UI for collections and documents.

## Connections

- Workspace → Product UI: hosts · Workspace contains the main product application.
- Workspace → Docs site: hosts · Workspace also contains the documentation site.
- CI → Workspace: validates · CI runs checks across the repository workspace.
- Product UI → App shell: routes to · The product app is organized under the authenticated app shell.
- Product UI → Auth pages: routes to · Unauthenticated flows live in the auth route group.
- Product UI → Auth boundary: secures · App routing depends on session gating and auth callbacks.
- App shell → Agents: contains · The main shell exposes agent management views.
- App shell → Chat: contains · The shell also hosts the conversational runtime UI.
- App shell → Inbox: contains · Operational inbox views are part of the authenticated product area.
- App shell → Tools: contains · Tool browsing and playground pages live in the app shell.
- App shell → RAG: contains · RAG management pages are part of the authenticated product area.
- Agents → Shared state: uses · Agent selection and configuration state is shared across the app.
- Chat → Shared state: uses · Chat reuses shared agent selection, config, and streaming state.
- Inbox → Shared state: uses · Inbox views rely on shared thread and agent state.
- Tools → Shared state: uses · Tools and MCP search state are managed through shared hooks/providers.
- RAG → Shared state: uses · RAG collections and documents use shared app state layers.
- Auth boundary → Supabase: backs onto · Authentication and sessions are sourced from Supabase.
- API adapters → LangGraph: proxies · LangGraph requests are adapted through local route handlers.
- API adapters → MCP servers: proxies · MCP execution is proxied through the app API boundary.
- RAG → LangConnect: depends on · The UI assumes an external LangConnect service for RAG operations.
- Docs site → Auth boundary: documents · Docs cover setup and authentication integration.
- Docs site → MCP servers: documents · Docs describe MCP server setup and usage.
- Docs site → LangConnect: documents · Docs explain the RAG server dependency.
- Docs site → LangGraph: documents · Docs cover custom agents and LangGraph-oriented workflows.
