# shane2512/steward architecture

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

- Interactive diagram: https://gitdiagram.com/shane2512/steward
- Repository: https://github.com/shane2512/steward

## Overview

Steward lets an owner connect a wallet, express treasury intent as a mandate, review and activate its compiled policy, and authorize a bounded Spend Permission. The worker then gathers treasury context, screens untrusted text, obtains a SERV proposal, and subjects it to deterministic policy and risk checks before wallet execution and chain confirmation. Owners can also approve escalations, inspect decisions and audit history, or freeze and sweep funds through a separate signed path. The worker pipeline excerpt is partial; stage relationships follow the README’s documented architecture, while uncertain implementation details are omitted.

Main entry points: [`packages/db/src/schema.ts`](https://github.com/shane2512/steward/blob/main/packages/db/src/schema.ts) (Postgres records), [`apps/worker/src/pipeline.ts`](https://github.com/shane2512/steward/blob/main/apps/worker/src/pipeline.ts) (Decision pipeline), [`packages/wallet/src/executor.ts`](https://github.com/shane2512/steward/blob/main/packages/wallet/src/executor.ts) (Wallet executor), [`apps/web/app/api/mandate/compile/route.ts`](https://github.com/shane2512/steward/blob/main/apps/web/app/api/mandate/compile/route.ts) (Mandate compilation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_owner_app["Owner application"]
  node_web_ui["Steward dashboard<br/>[page.tsx]"]
  node_onboarding["Onboarding flow<br/>[OnboardingFlow.tsx]"]
  node_dashboard_api["Dashboard aggregation<br/>[route.ts]"]
  node_audit_export["Audit and exports<br/>[route.ts]"]
end

subgraph group_controls["Owner controls"]
  node_mandate_api["Mandate compilation<br/>[route.ts]"]
  node_policy_api["Policy review<br/>[route.ts]"]
  node_recipients_api["Recipient allowlist<br/>[route.ts]"]
  node_permission_api["Spend permission<br/>[route.ts]"]
  node_freeze_api["Freeze and recovery<br/>[route.ts]"]
  node_sweep_api["Owner fund sweep<br/>[route.ts]"]
end

subgraph group_autonomy["Autonomous decisions"]
  node_worker_loop["Decision scheduler<br/>[loop.ts]"]
  node_worker_pipeline["Decision pipeline<br/>[pipeline.ts]"]
  node_context["Treasury context<br/>[build.ts]"]
  node_reasoning["SERV reasoning<br/>[index.ts]"]
  node_policy_engine["Deterministic policy<br/>[evaluate.ts]"]
  node_risk_gate["Simulation risk gate<br/>[simulate.ts]"]
end

subgraph group_execution["Treasury execution"]
  node_wallet_executor["Wallet executor<br/>[executor.ts]"]
  node_agentkit["Coinbase AgentKit<br/>[agentkit.ts]"]
end

subgraph group_records["State and audit"]
  node_database[("Postgres records<br/>[schema.ts]")]
end

node_owner(("Treasury owner"))
node_chain{{"Base treasury chain"}}
node_serv_service{{"SERV inference"}}

node_owner -->|"sets up"| node_onboarding
node_onboarding -->|"submits mandate"| node_mandate_api
node_owner -->|"reviews and signs"| node_policy_api
node_owner -->|"signs recipient"| node_recipients_api
node_owner -->|"grants permission"| node_permission_api
node_mandate_api -->|"compiles mandate"| node_reasoning
node_mandate_api -->|"stores mandate"| node_database
node_policy_api -->|"reads and activates"| node_database
node_recipients_api -->|"reads and writes"| node_database
node_permission_api -->|"stores grant"| node_database
node_worker_loop -->|"runs iterations"| node_worker_pipeline
node_worker_pipeline -->|"builds context"| node_context
node_worker_pipeline -->|"screens and proposes"| node_reasoning
node_worker_pipeline -->|"evaluates proposal"| node_policy_engine
node_worker_pipeline -->|"simulates calls"| node_risk_gate
node_worker_pipeline -->|"executes allowed"| node_wallet_executor
node_reasoning -.->|"requests inference"| node_serv_service
node_worker_pipeline -->|"records decisions"| node_database
node_context -->|"reads treasury state"| node_database
node_wallet_executor -->|"dispatches actions"| node_agentkit
node_agentkit -->|"sends transactions"| node_chain
node_chain -->|"confirms transactions"| node_wallet_executor
node_owner -->|"signs freeze"| node_freeze_api
node_freeze_api -->|"freezes and audits"| node_database
node_owner -->|"requests signed sweep"| node_sweep_api
node_sweep_api -->|"invokes sweep"| node_wallet_executor
node_dashboard_api -->|"reads decisions and state"| node_database
node_web_ui -->|"loads dashboard"| node_dashboard_api
node_audit_export -->|"reads audit records"| node_database
node_web_ui -->|"requests history"| node_audit_export

click node_web_ui "https://github.com/shane2512/steward/blob/main/apps/web/app/app/page.tsx"
click node_onboarding "https://github.com/shane2512/steward/blob/main/apps/web/components/onboarding/OnboardingFlow.tsx"
click node_mandate_api "https://github.com/shane2512/steward/blob/main/apps/web/app/api/mandate/compile/route.ts"
click node_policy_api "https://github.com/shane2512/steward/blob/main/apps/web/app/api/policy/route.ts"
click node_recipients_api "https://github.com/shane2512/steward/blob/main/apps/web/app/api/recipients/route.ts"
click node_permission_api "https://github.com/shane2512/steward/blob/main/apps/web/app/api/spend-permission/route.ts"
click node_freeze_api "https://github.com/shane2512/steward/blob/main/apps/web/app/api/freeze/route.ts"
click node_sweep_api "https://github.com/shane2512/steward/blob/main/apps/web/app/api/sweep/route.ts"
click node_worker_loop "https://github.com/shane2512/steward/blob/main/apps/worker/src/loop.ts"
click node_worker_pipeline "https://github.com/shane2512/steward/blob/main/apps/worker/src/pipeline.ts"
click node_context "https://github.com/shane2512/steward/blob/main/packages/context/src/build.ts"
click node_reasoning "https://github.com/shane2512/steward/blob/main/packages/reasoning/src/index.ts"
click node_policy_engine "https://github.com/shane2512/steward/blob/main/packages/policy/src/evaluate.ts"
click node_risk_gate "https://github.com/shane2512/steward/blob/main/packages/risk/src/simulate.ts"
click node_wallet_executor "https://github.com/shane2512/steward/blob/main/packages/wallet/src/executor.ts"
click node_agentkit "https://github.com/shane2512/steward/blob/main/packages/wallet/src/agentkit.ts"
click node_dashboard_api "https://github.com/shane2512/steward/blob/main/apps/web/app/api/dashboard/route.ts"
click node_audit_export "https://github.com/shane2512/steward/blob/main/apps/web/app/api/audit/route.ts"
click node_database "https://github.com/shane2512/steward/blob/main/packages/db/src/schema.ts"

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_web_ui,node_onboarding,node_dashboard_api,node_audit_export toneBlue
class node_mandate_api,node_policy_api,node_recipients_api,node_permission_api,node_freeze_api,node_sweep_api toneAmber
class node_worker_loop,node_worker_pipeline,node_context,node_reasoning,node_policy_engine,node_risk_gate toneMint
class node_wallet_executor,node_agentkit toneRose
class node_database,node_owner,node_chain,node_serv_service toneIndigo
```

## Components

### Owner application

- [Steward dashboard](https://github.com/shane2512/steward/blob/main/apps/web/app/app/page.tsx): `apps/web/app/app/page.tsx`
- [Onboarding flow](https://github.com/shane2512/steward/blob/main/apps/web/components/onboarding/OnboardingFlow.tsx): `apps/web/components/onboarding/OnboardingFlow.tsx`
- [Dashboard aggregation](https://github.com/shane2512/steward/blob/main/apps/web/app/api/dashboard/route.ts): `apps/web/app/api/dashboard/route.ts`
- [Audit and exports](https://github.com/shane2512/steward/blob/main/apps/web/app/api/audit/route.ts): `apps/web/app/api/audit/route.ts`

### Owner controls

- [Mandate compilation](https://github.com/shane2512/steward/blob/main/apps/web/app/api/mandate/compile/route.ts): `apps/web/app/api/mandate/compile/route.ts`
- [Policy review](https://github.com/shane2512/steward/blob/main/apps/web/app/api/policy/route.ts): `apps/web/app/api/policy/route.ts`
- [Recipient allowlist](https://github.com/shane2512/steward/blob/main/apps/web/app/api/recipients/route.ts): `apps/web/app/api/recipients/route.ts`
- [Spend permission](https://github.com/shane2512/steward/blob/main/apps/web/app/api/spend-permission/route.ts): `apps/web/app/api/spend-permission/route.ts`
- [Freeze and recovery](https://github.com/shane2512/steward/blob/main/apps/web/app/api/freeze/route.ts): `apps/web/app/api/freeze/route.ts`
- [Owner fund sweep](https://github.com/shane2512/steward/blob/main/apps/web/app/api/sweep/route.ts): `apps/web/app/api/sweep/route.ts`

### Autonomous decisions

- [Decision scheduler](https://github.com/shane2512/steward/blob/main/apps/worker/src/loop.ts): `apps/worker/src/loop.ts`
- [Decision pipeline](https://github.com/shane2512/steward/blob/main/apps/worker/src/pipeline.ts): `apps/worker/src/pipeline.ts`
- [Treasury context](https://github.com/shane2512/steward/blob/main/packages/context/src/build.ts): `packages/context/src/build.ts`
- [SERV reasoning](https://github.com/shane2512/steward/blob/main/packages/reasoning/src/index.ts): `packages/reasoning/src/index.ts`
- [Deterministic policy](https://github.com/shane2512/steward/blob/main/packages/policy/src/evaluate.ts): `packages/policy/src/evaluate.ts`
- [Simulation risk gate](https://github.com/shane2512/steward/blob/main/packages/risk/src/simulate.ts): `packages/risk/src/simulate.ts`

### Treasury execution

- [Wallet executor](https://github.com/shane2512/steward/blob/main/packages/wallet/src/executor.ts): `packages/wallet/src/executor.ts`
- [Coinbase AgentKit](https://github.com/shane2512/steward/blob/main/packages/wallet/src/agentkit.ts): `packages/wallet/src/agentkit.ts`

### State and audit

- [Postgres records](https://github.com/shane2512/steward/blob/main/packages/db/src/schema.ts): `packages/db/src/schema.ts`

### Other components

- **Treasury owner**
- **Base treasury chain**
- **SERV inference**

## Connections

- Treasury owner → Onboarding flow: sets up
- Onboarding flow → Mandate compilation: submits mandate
- Treasury owner → Policy review: reviews and signs
- Treasury owner → Recipient allowlist: signs recipient
- Treasury owner → Spend permission: grants permission
- Mandate compilation → SERV reasoning: compiles mandate
- Mandate compilation → Postgres records: stores mandate
- Policy review → Postgres records: reads and activates
- Recipient allowlist → Postgres records: reads and writes
- Spend permission → Postgres records: stores grant
- Decision scheduler → Decision pipeline: runs iterations
- Decision pipeline → Treasury context: builds context
- Decision pipeline → SERV reasoning: screens and proposes
- Decision pipeline → Deterministic policy: evaluates proposal
- Decision pipeline → Simulation risk gate: simulates calls
- Decision pipeline → Wallet executor: executes allowed
- SERV reasoning → SERV inference: requests inference
- Decision pipeline → Postgres records: records decisions
- Treasury context → Postgres records: reads treasury state
- Wallet executor → Coinbase AgentKit: dispatches actions
- Coinbase AgentKit → Base treasury chain: sends transactions
- Base treasury chain → Wallet executor: confirms transactions
- Treasury owner → Freeze and recovery: signs freeze
- Freeze and recovery → Postgres records: freezes and audits
- Treasury owner → Owner fund sweep: requests signed sweep
- Owner fund sweep → Wallet executor: invokes sweep
- Dashboard aggregation → Postgres records: reads decisions and state
- Steward dashboard → Dashboard aggregation: loads dashboard
- Audit and exports → Postgres records: reads audit records
- Steward dashboard → Audit and exports: requests history