# olamidepy/valence architecture

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

- Interactive diagram: https://gitdiagram.com/olamidepy/valence
- Repository: https://github.com/olamidepy/valence

## Overview

Valence is a web app and API for recurring, guardrailed investment in tokenized equities on Robinhood Chain. A user defines a goal; the goals API requests a SERV basket and checks it against guardrails for preview. Scheduled goals repeat that reasoning and validation before the cron handler dispatches approved holdings to chain execution. The app also exposes portfolio, activity, market, account, Telegram-alert, and MCP capabilities. The sampled code uses mock data alongside Prisma; unsampled UI and route implementations limit certainty about their wiring.

Main entry points: [`app/api/cron/run-due-goals/route.ts`](https://github.com/olamidepy/valence/blob/main/app/api/cron/run-due-goals/route.ts) (Due-goal runner), [`lib/chain/execute.ts`](https://github.com/olamidepy/valence/blob/main/lib/chain/execute.ts) (Basket executor), [`app/api/mcp/route.ts`](https://github.com/olamidepy/valence/blob/main/app/api/mcp/route.ts) (MCP server), [`lib/db.ts`](https://github.com/olamidepy/valence/blob/main/lib/db.ts) (Application state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_webapp["Valence app<br/>[layout.tsx]"]
  node_goalui["Goal form<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_activityui["Activity ledger<br/>[page.tsx]"]
  node_settings["Alerts and guardrails<br/>[page.tsx]"]
end

subgraph group_goals["Goal and risk flow"]
  node_goalapi["Goal proposal API<br/>[route.ts]"]
  node_confirm["Goal confirmation API<br/>[route.ts]"]
  node_scheduler["Due-goal runner<br/>[route.ts]"]
  node_serv["SERV basket generator<br/>[basket.ts]"]
  node_guardrails["Guardrail evaluator<br/>[guardrails.ts]"]
  node_mcp["MCP server<br/>[route.ts]"]
end

subgraph group_execution["Chain execution"]
  node_execute["Basket executor<br/>[execute.ts]"]
  node_chainconfig["Chain configuration<br/>[config.ts]"]
  node_wallets["Wallet discovery"]
  node_fees["Fee logic<br/>[fees.ts]"]
end

subgraph group_accounts["Accounts and alerts"]
  node_authapi["Authentication APIs<br/>[route.ts]"]
  node_otp["OTP and wallet derivation<br/>[otp-store.ts]"]
  node_email["Email delivery<br/>[auth-email.ts]"]
  node_telegramapi["Telegram endpoints<br/>[route.ts]"]
  node_telegram["Telegram notifications<br/>[telegram.ts]"]
end

subgraph group_data["Market and state"]
  node_portfolioapi["Portfolio API<br/>[route.ts]"]
  node_activityapi["Activity API<br/>[route.ts]"]
  node_marketapi["Live market API<br/>[route.ts]"]
  node_market["Live market data<br/>[live-market.ts]"]
  node_stocks["Tokenized stock registry"]
  node_state[("Application state<br/>[db.ts]")]
  node_prisma[("Prisma database<br/>[db.ts]")]
end

node_user(("Investor"))
node_agent(("MCP client"))
node_cron(("Scheduler"))
node_chain{{"Robinhood Chain"}}
node_servservice{{"SERV or model provider"}}
node_emailservice{{"Email provider"}}
node_telegramservice{{"Telegram"}}

node_user -->|"defines goal"| node_goalui
node_goalui -->|"requests proposal"| node_goalapi
node_goalapi -->|"generates basket"| node_serv
node_serv -.->|"requests reasoning"| node_servservice
node_goalapi -->|"checks basket"| node_guardrails
node_goalapi -->|"reads guardrails"| node_state
node_goalapi -->|"returns preview"| node_confirm
node_cron -->|"triggers run"| node_scheduler
node_scheduler -->|"reads goals"| node_state
node_scheduler -->|"generates proposal"| node_serv
node_scheduler -->|"checks proposal"| node_guardrails
node_scheduler -->|"dispatches approved holdings"| node_execute
node_scheduler -->|"records rejections"| node_state
node_scheduler -->|"sends rejection alert"| node_telegram
node_mcp -->|"fetches quotes"| node_market
node_mcp -->|"reads registry"| node_stocks
node_mcp -->|"checks proposal"| node_guardrails
node_mcp -->|"reads metrics and config"| node_state
node_mcp -->|"dispatches swaps"| node_execute
node_execute -->|"uses chain settings"| node_chainconfig
node_execute -->|"executes swaps"| node_chain
node_execute -->|"calculates fees"| node_fees
node_execute -->|"discovers wallets"| node_wallets
node_user -->|"views portfolio"| node_dashboard
node_dashboard -->|"requests portfolio"| node_portfolioapi
node_user -->|"reviews trades"| node_activityui
node_activityui -->|"requests ledger"| node_activityapi
node_portfolioapi -->|"reads portfolio data"| node_state
node_activityapi -->|"reads trades"| node_state
node_marketapi -->|"fetches prices"| node_market
node_authapi -->|"verifies code"| node_otp
node_authapi -->|"upserts user"| node_prisma
node_otp -->|"creates OTP delivery"| node_email
node_email -.->|"sends code"| node_emailservice
node_telegramapi -->|"handles linking"| node_telegram
node_telegram -.->|"sends notifications"| node_telegramservice
node_user -->|"manages alerts"| node_settings

click node_webapp "https://github.com/olamidepy/valence/blob/main/app/layout.tsx"
click node_goalui "https://github.com/olamidepy/valence/blob/main/app/goals/new/page.tsx"
click node_dashboard "https://github.com/olamidepy/valence/blob/main/app/dashboard/page.tsx"
click node_activityui "https://github.com/olamidepy/valence/blob/main/app/activity/page.tsx"
click node_settings "https://github.com/olamidepy/valence/blob/main/app/settings/alerts/page.tsx"
click node_goalapi "https://github.com/olamidepy/valence/blob/main/app/api/goals/route.ts"
click node_confirm "https://github.com/olamidepy/valence/blob/main/app/api/goals/%5Bid%5D/confirm/route.ts"
click node_scheduler "https://github.com/olamidepy/valence/blob/main/app/api/cron/run-due-goals/route.ts"
click node_serv "https://github.com/olamidepy/valence/blob/main/lib/serv/basket.ts"
click node_guardrails "https://github.com/olamidepy/valence/blob/main/lib/guardrails.ts"
click node_mcp "https://github.com/olamidepy/valence/blob/main/app/api/mcp/route.ts"
click node_execute "https://github.com/olamidepy/valence/blob/main/lib/chain/execute.ts"
click node_chainconfig "https://github.com/olamidepy/valence/blob/main/lib/chain/config.ts"
click node_wallets "https://github.com/olamidepy/valence/blob/main/lib/chain/wallet-discovery.ts"
click node_fees "https://github.com/olamidepy/valence/blob/main/lib/fees.ts"
click node_authapi "https://github.com/olamidepy/valence/blob/main/app/api/auth/verify-otp/route.ts"
click node_otp "https://github.com/olamidepy/valence/blob/main/lib/otp-store.ts"
click node_email "https://github.com/olamidepy/valence/blob/main/lib/auth-email.ts"
click node_telegramapi "https://github.com/olamidepy/valence/blob/main/app/api/telegram/webhook/route.ts"
click node_telegram "https://github.com/olamidepy/valence/blob/main/lib/telegram.ts"
click node_portfolioapi "https://github.com/olamidepy/valence/blob/main/app/api/portfolio/route.ts"
click node_activityapi "https://github.com/olamidepy/valence/blob/main/app/api/activity/route.ts"
click node_marketapi "https://github.com/olamidepy/valence/blob/main/app/api/market/live/route.ts"
click node_market "https://github.com/olamidepy/valence/blob/main/lib/live-market.ts"
click node_stocks "https://github.com/olamidepy/valence/blob/main/lib/tokenized-stocks.ts"
click node_state "https://github.com/olamidepy/valence/blob/main/lib/db.ts"
click node_prisma "https://github.com/olamidepy/valence/blob/main/lib/db.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_webapp,node_goalui,node_dashboard,node_activityui,node_settings,node_agent toneBlue
class node_goalapi,node_confirm,node_scheduler,node_serv,node_guardrails,node_mcp toneAmber
class node_execute,node_chainconfig,node_wallets,node_fees toneMint
class node_authapi,node_otp,node_email,node_telegramapi,node_telegram,node_cron toneRose
class node_portfolioapi,node_activityapi,node_marketapi,node_market,node_stocks,node_state,node_prisma,node_user,node_chain,node_servservice,node_emailservice,node_telegramservice toneIndigo
```

## Components

### User experience

- [Valence app](https://github.com/olamidepy/valence/blob/main/app/layout.tsx): `app/layout.tsx`
- [Goal form](https://github.com/olamidepy/valence/blob/main/app/goals/new/page.tsx): `app/goals/new/page.tsx`
- [Dashboard](https://github.com/olamidepy/valence/blob/main/app/dashboard/page.tsx): `app/dashboard/page.tsx`
- [Activity ledger](https://github.com/olamidepy/valence/blob/main/app/activity/page.tsx): `app/activity/page.tsx`
- [Alerts and guardrails](https://github.com/olamidepy/valence/blob/main/app/settings/alerts/page.tsx): `app/settings/alerts/page.tsx`

### Goal and risk flow

- [Goal proposal API](https://github.com/olamidepy/valence/blob/main/app/api/goals/route.ts): `app/api/goals/route.ts`
- [Goal confirmation API](https://github.com/olamidepy/valence/blob/main/app/api/goals/%5Bid%5D/confirm/route.ts): `app/api/goals/[id]/confirm/route.ts`
- [Due-goal runner](https://github.com/olamidepy/valence/blob/main/app/api/cron/run-due-goals/route.ts): `app/api/cron/run-due-goals/route.ts`
- [SERV basket generator](https://github.com/olamidepy/valence/blob/main/lib/serv/basket.ts): `lib/serv/basket.ts`
- [Guardrail evaluator](https://github.com/olamidepy/valence/blob/main/lib/guardrails.ts): `lib/guardrails.ts`
- [MCP server](https://github.com/olamidepy/valence/blob/main/app/api/mcp/route.ts): `app/api/mcp/route.ts`

### Chain execution

- [Basket executor](https://github.com/olamidepy/valence/blob/main/lib/chain/execute.ts): `lib/chain/execute.ts`
- [Chain configuration](https://github.com/olamidepy/valence/blob/main/lib/chain/config.ts): `lib/chain/config.ts`
- [Wallet discovery](https://github.com/olamidepy/valence/blob/main/lib/chain/wallet-discovery.ts): `lib/chain/wallet-discovery.ts`
- [Fee logic](https://github.com/olamidepy/valence/blob/main/lib/fees.ts): `lib/fees.ts`

### Accounts and alerts

- [Authentication APIs](https://github.com/olamidepy/valence/blob/main/app/api/auth/verify-otp/route.ts): `app/api/auth/verify-otp/route.ts`
- [OTP and wallet derivation](https://github.com/olamidepy/valence/blob/main/lib/otp-store.ts): `lib/otp-store.ts`
- [Email delivery](https://github.com/olamidepy/valence/blob/main/lib/auth-email.ts): `lib/auth-email.ts`
- [Telegram endpoints](https://github.com/olamidepy/valence/blob/main/app/api/telegram/webhook/route.ts): `app/api/telegram/webhook/route.ts`
- [Telegram notifications](https://github.com/olamidepy/valence/blob/main/lib/telegram.ts): `lib/telegram.ts`

### Market and state

- [Portfolio API](https://github.com/olamidepy/valence/blob/main/app/api/portfolio/route.ts): `app/api/portfolio/route.ts`
- [Activity API](https://github.com/olamidepy/valence/blob/main/app/api/activity/route.ts): `app/api/activity/route.ts`
- [Live market API](https://github.com/olamidepy/valence/blob/main/app/api/market/live/route.ts): `app/api/market/live/route.ts`
- [Live market data](https://github.com/olamidepy/valence/blob/main/lib/live-market.ts): `lib/live-market.ts`
- [Tokenized stock registry](https://github.com/olamidepy/valence/blob/main/lib/tokenized-stocks.ts): `lib/tokenized-stocks.ts`
- [Application state](https://github.com/olamidepy/valence/blob/main/lib/db.ts): `lib/db.ts`
- [Prisma database](https://github.com/olamidepy/valence/blob/main/lib/db.ts): `lib/db.ts`

### Other components

- **Investor**
- **MCP client**
- **Scheduler**
- **Robinhood Chain**
- **SERV or model provider**
- **Email provider**
- **Telegram**

## Connections

- Investor → Goal form: defines goal
- Goal form → Goal proposal API: requests proposal
- Goal proposal API → SERV basket generator: generates basket
- SERV basket generator → SERV or model provider: requests reasoning
- Goal proposal API → Guardrail evaluator: checks basket
- Goal proposal API → Application state: reads guardrails
- Goal proposal API → Goal confirmation API: returns preview
- Scheduler → Due-goal runner: triggers run
- Due-goal runner → Application state: reads goals
- Due-goal runner → SERV basket generator: generates proposal
- Due-goal runner → Guardrail evaluator: checks proposal
- Due-goal runner → Basket executor: dispatches approved holdings
- Due-goal runner → Application state: records rejections
- Due-goal runner → Telegram notifications: sends rejection alert
- MCP server → Live market data: fetches quotes
- MCP server → Tokenized stock registry: reads registry
- MCP server → Guardrail evaluator: checks proposal
- MCP server → Application state: reads metrics and config
- MCP server → Basket executor: dispatches swaps
- Basket executor → Chain configuration: uses chain settings
- Basket executor → Robinhood Chain: executes swaps
- Basket executor → Fee logic: calculates fees
- Basket executor → Wallet discovery: discovers wallets
- Investor → Dashboard: views portfolio
- Dashboard → Portfolio API: requests portfolio
- Investor → Activity ledger: reviews trades
- Activity ledger → Activity API: requests ledger
- Portfolio API → Application state: reads portfolio data
- Activity API → Application state: reads trades
- Live market API → Live market data: fetches prices
- Authentication APIs → OTP and wallet derivation: verifies code
- Authentication APIs → Prisma database: upserts user
- OTP and wallet derivation → Email delivery: creates OTP delivery
- Email delivery → Email provider: sends code
- Telegram endpoints → Telegram notifications: handles linking
- Telegram notifications → Telegram: sends notifications
- Investor → Alerts and guardrails: manages alerts