How ruvnet/open-agentics works
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: (app)/layout.tsx App shell · index.mdx Docs site · Agents.tsx Shared state · app/layout.tsx Product UI
Components 19
Workspace
Monorepo-level build, typing, and CI setup.
Web app
Next.js product UI and its client-side feature modules.
- Product UI · Authenticated Next.js application for operating agents, tools, and RAG.
apps/web/src/app/layout.tsx - App shell · Authenticated layout and main route grouping for the product area.
apps/web/src/app/(app)/layout.tsx - Auth pages · Sign-in and account recovery flows for unauthenticated users.
apps/web/src/app/(auth)/layout.tsx - Auth boundary · Supabase-backed session handling, callback route, middleware, and auth provider.
apps/web/src/lib/auth/middleware.ts - Agents · Agent dashboards, templates, create/edit flows, and deployment-aware configuration.
apps/web/src/features/agents/index.tsx - Chat · Interactive agent runtime view with thread history, config sidebar, and streaming messages.
apps/web/src/features/chat/index.tsx - Inbox · Operational thread review, interrupts, and agent action inspection.
apps/web/src/features/inbox/index.tsx - Tools · Tool browsing, detail inspection, and schema-driven playground execution.
apps/web/src/features/tools/index.tsx - RAG · Collection and document management for the LangConnect-backed retrieval layer.
apps/web/src/features/rag/index.tsx - UI kit · Reusable client UI primitives, layout components, and common controls.
apps/web/src/components/ui/button.tsx - Shared state · Cross-cutting providers and hooks for agents, auth, MCP, search, and device state.
apps/web/src/providers/Agents.tsx - API adapters · 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 · Separate documentation application with MDX content for setup and usage.
apps/docs/index.mdx
Other components
- LangGraph · Primary agent platform used for deployments, defaults, and request proxying.
- Supabase · External identity and session source for authentication.
- MCP servers · External tool providers accessed through the MCP proxy boundary.
- LangConnect · Separate RAG backend expected by the web UI for collections and documents.
Connections 24
- 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.