# asliadarsh/buttlr architecture

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

- Interactive diagram: https://gitdiagram.com/asliadarsh/buttlr
- Repository: https://github.com/asliadarsh/buttlr

## Overview

Buttlr is an AI workforce platform: users describe and configure scoped, scheduled AI employees, then supervise their tool use through permissions, approvals, execution history, and audit. The main path runs from the React workspace through the API and domain services into the runtime; scheduled runs enter through the scheduler and worker. The README documents model choice, integrations, analytics, and activity alongside that path. Source excerpts are partial, so unsampled subsystem links are shown only where README documentation or indexed references support them.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/asliadarsh/buttlr/blob/main/backend/app/api/v1/router.py) (REST API routers), [`backend/app/runtime/executor.py`](https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/executor.py) (Execution loop), [`frontend/src/lib/queries.ts`](https://github.com/asliadarsh/buttlr/blob/main/frontend/src/lib/queries.ts) (API client and queries), [`backend/app/database/repository.py`](https://github.com/asliadarsh/buttlr/blob/main/backend/app/database/repository.py) (Store and repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Workspace UI"]
  node_frontend["React workspace<br/>[App.tsx]"]
  node_client["API client and queries<br/>[queries.ts]"]
  node_create["Describe and configure<br/>[ButtlrNewPage.tsx]"]
  node_supervise["Approvals and activity<br/>[ApprovalCard.tsx]"]
end

subgraph group_api["API and domains"]
  node_api["REST API routers<br/>[router.py]"]
  node_auth["Identity and membership<br/>[service.py]"]
  node_buttlrs["Buttlr management<br/>[buttlrs.py]"]
  node_approvals["Approval service<br/>[approvals.py]"]
  node_audit["Audit and analytics<br/>[audit.py]"]
end

subgraph group_runtime["Buttlr runtime"]
  node_drafting["Natural-language drafting<br/>[drafting.py]"]
  node_executor["Execution loop<br/>[executor.py]"]
  node_planner["Planner and observations"]
  node_permission["Permission engine<br/>[engine.py]"]
  node_tool_runtime["Tool execution"]
end

subgraph group_connect["Models and integrations"]
  node_integrations_svc["Integration connections<br/>[service.py]"]
  node_provider_clients["Provider clients"]
  node_model_router["Model routing<br/>[router.py]"]
  node_model_providers["Model providers"]
  node_tool_integrations["GitHub, Google, Jira tools"]
end

subgraph group_state["Persistence and operations"]
  node_scheduler["Schedule dispatch<br/>[service.py]"]
  node_worker["Execution worker<br/>[runner.py]"]
  node_store["Store and repository<br/>[repository.py]"]
  node_database[("Firestore or memory")]
  node_execution_records["Execution and approval records<br/>[execution.py]"]
end

node_user(("Workspace user"))
node_external_tools{{"Connected work services"}}

node_user -->|"configures and supervises"| node_frontend
node_frontend -->|"uses API queries"| node_client
node_create -->|"submits configuration"| node_client
node_client -->|"REST and SSE"| node_api
node_api -->|"resolves identity"| node_auth
node_api -.->|"routes management"| node_buttlrs
node_api -.->|"routes decisions"| node_approvals
node_api -.->|"routes activity and analytics"| node_audit
node_api -.->|"routes connections"| node_integrations_svc
node_api -.->|"requests draft configuration"| node_drafting
node_buttlrs -.->|"persists Buttlrs"| node_store
node_integrations_svc -->|"stores credentials"| node_store
node_store -->|"reads and writes"| node_database
node_buttlrs -.->|"configures schedules"| node_scheduler
node_scheduler -->|"dispatches runs"| node_worker
node_worker -->|"runs execution"| node_executor
node_executor -.->|"plans and observes"| node_planner
node_planner -->|"requests model output"| node_model_router
node_model_router -.->|"selects provider"| node_model_providers
node_executor -->|"checks each tool call"| node_permission
node_executor -.->|"executes permitted calls"| node_tool_runtime
node_tool_runtime -.->|"resolves credentials"| node_integrations_svc
node_tool_runtime -.->|"dispatches tools"| node_tool_integrations
node_tool_integrations -.->|"calls provider clients"| node_provider_clients
node_provider_clients -.->|"accesses services"| node_external_tools
node_approvals -.->|"presents decisions"| node_supervise
node_supervise -.->|"submits approval"| node_client
node_executor -.->|"records run state"| node_execution_records
node_audit -.->|"reads execution history"| node_execution_records
node_execution_records -.->|"persists domain records"| node_store

click node_frontend "https://github.com/asliadarsh/buttlr/blob/main/frontend/src/App.tsx"
click node_client "https://github.com/asliadarsh/buttlr/blob/main/frontend/src/lib/queries.ts"
click node_create "https://github.com/asliadarsh/buttlr/blob/main/frontend/src/pages/ButtlrNewPage.tsx"
click node_supervise "https://github.com/asliadarsh/buttlr/blob/main/frontend/src/components/buttlr/ApprovalCard.tsx"
click node_api "https://github.com/asliadarsh/buttlr/blob/main/backend/app/api/v1/router.py"
click node_auth "https://github.com/asliadarsh/buttlr/blob/main/backend/app/auth/service.py"
click node_buttlrs "https://github.com/asliadarsh/buttlr/blob/main/backend/app/services/buttlrs.py"
click node_approvals "https://github.com/asliadarsh/buttlr/blob/main/backend/app/services/approvals.py"
click node_audit "https://github.com/asliadarsh/buttlr/blob/main/backend/app/services/audit.py"
click node_integrations_svc "https://github.com/asliadarsh/buttlr/blob/main/backend/app/integrations/service.py"
click node_provider_clients "https://github.com/asliadarsh/buttlr/tree/main/backend/app/integrations"
click node_drafting "https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/drafting.py"
click node_scheduler "https://github.com/asliadarsh/buttlr/blob/main/backend/app/scheduler/service.py"
click node_worker "https://github.com/asliadarsh/buttlr/blob/main/backend/app/workers/runner.py"
click node_executor "https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/executor.py"
click node_planner "https://github.com/asliadarsh/buttlr/tree/main/backend/app/runtime/planner"
click node_model_router "https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/models/router.py"
click node_model_providers "https://github.com/asliadarsh/buttlr/tree/main/backend/app/runtime/models/providers"
click node_permission "https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/permissions/engine.py"
click node_tool_runtime "https://github.com/asliadarsh/buttlr/tree/main/backend/app/runtime/tools"
click node_tool_integrations "https://github.com/asliadarsh/buttlr/tree/main/backend/app/runtime/tools/integrations"
click node_store "https://github.com/asliadarsh/buttlr/blob/main/backend/app/database/repository.py"
click node_database "https://github.com/asliadarsh/buttlr/tree/main/backend/app/database"
click node_execution_records "https://github.com/asliadarsh/buttlr/blob/main/backend/app/schemas/execution.py"

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_frontend,node_client,node_create,node_supervise,node_user toneBlue
class node_api,node_auth,node_buttlrs,node_approvals,node_audit toneAmber
class node_drafting,node_executor,node_planner,node_permission,node_tool_runtime toneMint
class node_integrations_svc,node_provider_clients,node_model_router,node_model_providers,node_tool_integrations toneRose
class node_scheduler,node_worker,node_store,node_database,node_execution_records,node_external_tools toneIndigo
```

## Components

### Workspace UI

- [React workspace](https://github.com/asliadarsh/buttlr/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client and queries](https://github.com/asliadarsh/buttlr/blob/main/frontend/src/lib/queries.ts): `frontend/src/lib/queries.ts`
- [Describe and configure](https://github.com/asliadarsh/buttlr/blob/main/frontend/src/pages/ButtlrNewPage.tsx): `frontend/src/pages/ButtlrNewPage.tsx`
- [Approvals and activity](https://github.com/asliadarsh/buttlr/blob/main/frontend/src/components/buttlr/ApprovalCard.tsx): `frontend/src/components/buttlr/ApprovalCard.tsx`

### API and domains

- [REST API routers](https://github.com/asliadarsh/buttlr/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Identity and membership](https://github.com/asliadarsh/buttlr/blob/main/backend/app/auth/service.py): `backend/app/auth/service.py`
- [Buttlr management](https://github.com/asliadarsh/buttlr/blob/main/backend/app/services/buttlrs.py): `backend/app/services/buttlrs.py`
- [Approval service](https://github.com/asliadarsh/buttlr/blob/main/backend/app/services/approvals.py): `backend/app/services/approvals.py`
- [Audit and analytics](https://github.com/asliadarsh/buttlr/blob/main/backend/app/services/audit.py): `backend/app/services/audit.py`

### Buttlr runtime

- [Natural-language drafting](https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/drafting.py): `backend/app/runtime/drafting.py`
- [Execution loop](https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/executor.py): `backend/app/runtime/executor.py`
- [Planner and observations](https://github.com/asliadarsh/buttlr/tree/main/backend/app/runtime/planner): `backend/app/runtime/planner`
- [Permission engine](https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/permissions/engine.py): `backend/app/runtime/permissions/engine.py`
- [Tool execution](https://github.com/asliadarsh/buttlr/tree/main/backend/app/runtime/tools): `backend/app/runtime/tools`

### Models and integrations

- [Integration connections](https://github.com/asliadarsh/buttlr/blob/main/backend/app/integrations/service.py): `backend/app/integrations/service.py`
- [Provider clients](https://github.com/asliadarsh/buttlr/tree/main/backend/app/integrations): `backend/app/integrations`
- [Model routing](https://github.com/asliadarsh/buttlr/blob/main/backend/app/runtime/models/router.py): `backend/app/runtime/models/router.py`
- [Model providers](https://github.com/asliadarsh/buttlr/tree/main/backend/app/runtime/models/providers): `backend/app/runtime/models/providers`
- [GitHub, Google, Jira tools](https://github.com/asliadarsh/buttlr/tree/main/backend/app/runtime/tools/integrations): `backend/app/runtime/tools/integrations`

### Persistence and operations

- [Schedule dispatch](https://github.com/asliadarsh/buttlr/blob/main/backend/app/scheduler/service.py): `backend/app/scheduler/service.py`
- [Execution worker](https://github.com/asliadarsh/buttlr/blob/main/backend/app/workers/runner.py): `backend/app/workers/runner.py`
- [Store and repository](https://github.com/asliadarsh/buttlr/blob/main/backend/app/database/repository.py): `backend/app/database/repository.py`
- [Firestore or memory](https://github.com/asliadarsh/buttlr/tree/main/backend/app/database): `backend/app/database`
- [Execution and approval records](https://github.com/asliadarsh/buttlr/blob/main/backend/app/schemas/execution.py): `backend/app/schemas/execution.py`

### Other components

- **Workspace user**
- **Connected work services**

## Connections

- Workspace user → React workspace: configures and supervises (evidence: `README.md`)
- React workspace → API client and queries: uses API queries (evidence: `frontend/src/lib/queries.ts`)
- Describe and configure → API client and queries: submits configuration (evidence: `frontend/src/pages/ButtlrNewPage.tsx`)
- API client and queries → REST API routers: REST and SSE (evidence: `README.md`)
- REST API routers → Identity and membership: resolves identity
- REST API routers → Buttlr management: routes management
- REST API routers → Approval service: routes decisions
- REST API routers → Audit and analytics: routes activity and analytics
- REST API routers → Integration connections: routes connections
- REST API routers → Natural-language drafting: requests draft configuration
- Buttlr management → Store and repository: persists Buttlrs
- Integration connections → Store and repository: stores credentials (evidence: `backend/app/integrations/service.py`)
- Store and repository → Firestore or memory: reads and writes (evidence: `backend/app/database/repository.py`)
- Buttlr management → Schedule dispatch: configures schedules
- Schedule dispatch → Execution worker: dispatches runs (evidence: `backend/app/scheduler/service.py`)
- Execution worker → Execution loop: runs execution (evidence: `backend/app/workers/runner.py`)
- Execution loop → Planner and observations: plans and observes (evidence: `README.md`)
- Planner and observations → Model routing: requests model output (evidence: `backend/app/runtime/planner/llm.py`)
- Model routing → Model providers: selects provider
- Execution loop → Permission engine: checks each tool call (evidence: `README.md`)
- Execution loop → Tool execution: executes permitted calls (evidence: `README.md`)
- Tool execution → Integration connections: resolves credentials
- Tool execution → GitHub, Google, Jira tools: dispatches tools
- GitHub, Google, Jira tools → Provider clients: calls provider clients
- Provider clients → Connected work services: accesses services (evidence: `README.md`)
- Approval service → Approvals and activity: presents decisions
- Approvals and activity → API client and queries: submits approval
- Execution loop → Execution and approval records: records run state
- Audit and analytics → Execution and approval records: reads execution history
- Execution and approval records → Store and repository: persists domain records
