# vinhnxab/bean architecture

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

- Interactive diagram: https://gitdiagram.com/vinhnxab/bean
- Repository: https://github.com/vinhnxab/bean

## Overview

Bean is a self-hosted personal AI agent delivered as a Rust CLI and web/Telegram service. Users submit prompts through a client; the Router owns run admission and lifecycle, the agent uses an LLM and tools, and results return through the channel. Persistent sessions and related state use SQLite. Major documented branches include browser automation, scheduled tasks, voice, skills, and a read-only MCP server. Some subsystem paths and links rely on README statements or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`crates/bean-core/src/router.rs`](https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/router.rs) (Run router), [`crates/bean-tools/src/registry.rs`](https://github.com/vinhnxab/bean/blob/master/crates/bean-tools/src/registry.rs) (Tool registry), [`crates/bean/src/main.rs`](https://github.com/vinhnxab/bean/blob/master/crates/bean/src/main.rs) (Bean CLI), [`crates/bean-web/src/server/routes.rs`](https://github.com/vinhnxab/bean/blob/master/crates/bean-web/src/server/routes.rs) (Web API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_binary["Bean CLI<br/>[main.rs]"]
  node_webui["Web UI<br/>[App.tsx]"]
  node_webapi["Web API<br/>[routes.rs]"]
  node_telegram["Telegram channel<br/>[handlers.rs]"]
end

subgraph group_runtime["Agent runtime"]
  node_router["Run router<br/>[router.rs]"]
  node_agent["Agent execution<br/>[agent.rs]"]
  node_toolcall["Tool dispatch<br/>[tool_call.rs]"]
end

subgraph group_integrations["Providers and tools"]
  node_llm["LLM providers<br/>[lib.rs]"]
  node_tools["Tool registry<br/>[registry.rs]"]
  node_browser["Browser automation<br/>[act_tools.rs]"]
  node_memorytool["Memory query<br/>[memory_query.rs]"]
end

subgraph group_state["State and security"]
  node_store["Core store API<br/>[store.rs]"]
  node_sqlite[("SQLite persistence<br/>[worker.rs]")]
  node_security["Security controls<br/>[policy.rs]"]
end

subgraph group_extensions["Product capabilities"]
  node_mcp["Read-only MCP<br/>[handler.rs]"]
  node_scheduler["Scheduled tasks<br/>[scheduler.rs]"]
  node_skills["Skills<br/>[loader.rs]"]
  node_voice["Push-to-talk voice<br/>[lib.rs]"]
  node_billing["Billing tools<br/>[tool.rs]"]
  node_marketing["Marketing tools<br/>[publish.rs]"]
  node_scan["Infrastructure scan<br/>[tool.rs]"]
end

node_user(("User"))

node_user -->|"runs command"| node_binary
node_binary -.->|"starts service"| node_router
node_user -->|"uses"| node_webui
node_webui -.->|"requests API"| node_webapi
node_webapi -.->|"serves agent operations"| node_router
node_telegram -->|"submits prompts"| node_router
node_router -->|"owns runs"| node_agent
node_agent -->|"dispatches tools"| node_toolcall
node_toolcall -.->|"requests completion"| node_llm
node_toolcall -.->|"invokes tools"| node_tools
node_tools -.->|"offers browser tools"| node_browser
node_tools -->|"offers memory query"| node_memorytool
node_router -->|"uses persistence"| node_store
node_store -.->|"persists state"| node_sqlite
node_router -.->|"applies policy"| node_security
node_binary -->|"serves MCP"| node_mcp
node_mcp -->|"calls tools"| node_router
node_router -.->|"runs scheduled tasks"| node_scheduler
node_tools -.->|"loads skills"| node_skills
node_webapi -->|"exposes voice endpoints"| node_voice
node_tools -.->|"provides billing tools"| node_billing
node_tools -.->|"provides publishing tools"| node_marketing
node_tools -.->|"provides scan tools"| node_scan

click node_binary "https://github.com/vinhnxab/bean/blob/master/crates/bean/src/main.rs"
click node_webui "https://github.com/vinhnxab/bean/blob/master/web/src/App.tsx"
click node_webapi "https://github.com/vinhnxab/bean/blob/master/crates/bean-web/src/server/routes.rs"
click node_telegram "https://github.com/vinhnxab/bean/blob/master/crates/bean-channels/src/telegram/handlers.rs"
click node_router "https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/router.rs"
click node_agent "https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/agent.rs"
click node_toolcall "https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/agent/tool_call.rs"
click node_llm "https://github.com/vinhnxab/bean/blob/master/crates/bean-llm/src/lib.rs"
click node_tools "https://github.com/vinhnxab/bean/blob/master/crates/bean-tools/src/registry.rs"
click node_browser "https://github.com/vinhnxab/bean/blob/master/crates/bean-browser/src/act_tools.rs"
click node_memorytool "https://github.com/vinhnxab/bean/blob/master/crates/bean-tools/src/builtin/memory_query.rs"
click node_store "https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/store.rs"
click node_sqlite "https://github.com/vinhnxab/bean/blob/master/crates/bean-memory/src/store/sqlite/worker.rs"
click node_security "https://github.com/vinhnxab/bean/blob/master/crates/bean-security/src/policy.rs"
click node_mcp "https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/mcp_server/handler.rs"
click node_scheduler "https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/scheduler.rs"
click node_skills "https://github.com/vinhnxab/bean/blob/master/crates/bean-skills/src/loader.rs"
click node_voice "https://github.com/vinhnxab/bean/blob/master/crates/bean-speech/src/lib.rs"
click node_billing "https://github.com/vinhnxab/bean/blob/master/crates/bean-billing/src/tool.rs"
click node_marketing "https://github.com/vinhnxab/bean/blob/master/crates/bean-marketing/src/publish.rs"
click node_scan "https://github.com/vinhnxab/bean/blob/master/crates/bean-scan/src/tool.rs"

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_binary,node_webui,node_webapi,node_telegram,node_user toneBlue
class node_router,node_agent,node_toolcall toneAmber
class node_llm,node_tools,node_browser,node_memorytool toneMint
class node_store,node_sqlite,node_security toneRose
class node_mcp,node_scheduler,node_skills,node_voice,node_billing,node_marketing,node_scan toneIndigo
```

## Components

### User interfaces

- [Bean CLI](https://github.com/vinhnxab/bean/blob/master/crates/bean/src/main.rs): `crates/bean/src/main.rs`
- [Web UI](https://github.com/vinhnxab/bean/blob/master/web/src/App.tsx): `web/src/App.tsx`
- [Web API](https://github.com/vinhnxab/bean/blob/master/crates/bean-web/src/server/routes.rs): `crates/bean-web/src/server/routes.rs`
- [Telegram channel](https://github.com/vinhnxab/bean/blob/master/crates/bean-channels/src/telegram/handlers.rs): `crates/bean-channels/src/telegram/handlers.rs`

### Agent runtime

- [Run router](https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/router.rs): `crates/bean-core/src/router.rs`
- [Agent execution](https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/agent.rs): `crates/bean-core/src/agent.rs`
- [Tool dispatch](https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/agent/tool_call.rs): `crates/bean-core/src/agent/tool_call.rs`

### Providers and tools

- [LLM providers](https://github.com/vinhnxab/bean/blob/master/crates/bean-llm/src/lib.rs): `crates/bean-llm/src/lib.rs`
- [Tool registry](https://github.com/vinhnxab/bean/blob/master/crates/bean-tools/src/registry.rs): `crates/bean-tools/src/registry.rs`
- [Browser automation](https://github.com/vinhnxab/bean/blob/master/crates/bean-browser/src/act_tools.rs): `crates/bean-browser/src/act_tools.rs`
- [Memory query](https://github.com/vinhnxab/bean/blob/master/crates/bean-tools/src/builtin/memory_query.rs): `crates/bean-tools/src/builtin/memory_query.rs`

### State and security

- [Core store API](https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/store.rs): `crates/bean-core/src/store.rs`
- [SQLite persistence](https://github.com/vinhnxab/bean/blob/master/crates/bean-memory/src/store/sqlite/worker.rs): `crates/bean-memory/src/store/sqlite/worker.rs`
- [Security controls](https://github.com/vinhnxab/bean/blob/master/crates/bean-security/src/policy.rs): `crates/bean-security/src/policy.rs`

### Product capabilities

- [Read-only MCP](https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/mcp_server/handler.rs): `crates/bean-core/src/mcp_server/handler.rs`
- [Scheduled tasks](https://github.com/vinhnxab/bean/blob/master/crates/bean-core/src/scheduler.rs): `crates/bean-core/src/scheduler.rs`
- [Skills](https://github.com/vinhnxab/bean/blob/master/crates/bean-skills/src/loader.rs): `crates/bean-skills/src/loader.rs`
- [Push-to-talk voice](https://github.com/vinhnxab/bean/blob/master/crates/bean-speech/src/lib.rs): `crates/bean-speech/src/lib.rs`
- [Billing tools](https://github.com/vinhnxab/bean/blob/master/crates/bean-billing/src/tool.rs): `crates/bean-billing/src/tool.rs`
- [Marketing tools](https://github.com/vinhnxab/bean/blob/master/crates/bean-marketing/src/publish.rs): `crates/bean-marketing/src/publish.rs`
- [Infrastructure scan](https://github.com/vinhnxab/bean/blob/master/crates/bean-scan/src/tool.rs): `crates/bean-scan/src/tool.rs`

### Other components

- **User**

## Connections

- User → Bean CLI: runs command (evidence: `crates/bean/src/main.rs`)
- Bean CLI → Run router: starts service
- User → Web UI: uses (evidence: `README.md`)
- Web UI → Web API: requests API
- Web API → Run router: serves agent operations
- Telegram channel → Run router: submits prompts (evidence: `crates/bean-channels/src/telegram/handlers.rs`)
- Run router → Agent execution: owns runs (evidence: `crates/bean-core/src/router.rs`)
- Agent execution → Tool dispatch: dispatches tools (evidence: `crates/bean-core/src/agent.rs`)
- Tool dispatch → LLM providers: requests completion
- Tool dispatch → Tool registry: invokes tools
- Tool registry → Browser automation: offers browser tools
- Tool registry → Memory query: offers memory query (evidence: `crates/bean-tools/src/builtin/memory_query.rs`)
- Run router → Core store API: uses persistence (evidence: `crates/bean-core/src/router.rs`)
- Core store API → SQLite persistence: persists state
- Run router → Security controls: applies policy
- Bean CLI → Read-only MCP: serves MCP (evidence: `crates/bean/src/main.rs`)
- Read-only MCP → Run router: calls tools (evidence: `crates/bean-core/src/mcp_server/handler.rs`)
- Run router → Scheduled tasks: runs scheduled tasks
- Tool registry → Skills: loads skills
- Web API → Push-to-talk voice: exposes voice endpoints (evidence: `crates/bean-web/src/server/routes.rs`)
- Tool registry → Billing tools: provides billing tools
- Tool registry → Marketing tools: provides publishing tools
- Tool registry → Infrastructure scan: provides scan tools
