# helsome/folio architecture

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

- Interactive diagram: https://gitdiagram.com/helsome/folio
- Repository: https://github.com/helsome/folio

## Overview

Folio is a local-first desktop investment research workbench, not a trading system. The user selects a security or portfolio context in the UI, requests streamed agent research, and receives cited evidence and structured reports; findings can continue into saved theses, monitoring, and outcome tracking. Capabilities and provider adapters supply typed financial data, while shared services support research, screening, alerts, risk, and evaluation. The README documents these major branches; unsampled UI and main-process wiring is represented only where the README or excerpts support it.

Main entry points: [`packages/shared/src/kernel/agent-kernel.ts`](https://github.com/helsome/folio/blob/main/packages/shared/src/kernel/agent-kernel.ts) (Agent kernel), [`packages/shared/src/capabilities/executor.ts`](https://github.com/helsome/folio/blob/main/packages/shared/src/capabilities/executor.ts) (Capability executor), [`packages/shared/src/research/service.ts`](https://github.com/helsome/folio/blob/main/packages/shared/src/research/service.ts) (Deep research), [`packages/shared/src/capabilities/registry.ts`](https://github.com/helsome/folio/blob/main/packages/shared/src/capabilities/registry.ts) (Capability registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_workbench["Research workbench"]
  node_ui_client["UI client<br/>[client.tsx]"]
  node_electron_renderer["Electron renderer<br/>[App.tsx]"]
  node_renderer_bridge["Renderer IPC client<br/>[finagentClient.ts]"]
  node_preload["Preload bridge<br/>[index.ts]"]
  node_electron_main["Electron main process<br/>[index.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_kernel_host["Kernel host<br/>[kernelHost.ts]"]
  node_agent_kernel["Agent kernel<br/>[agent-kernel.ts]"]
  node_run_manager["Run manager<br/>[run-manager.ts]"]
  node_session_manager["Session manager<br/>[session-manager.ts]"]
  node_agent_backend["Agent backend"]
  node_local_storage[("Local session storage<br/>[json-file-store.ts]")]
end

subgraph group_data["Data capabilities"]
  node_capability_registry["Capability registry<br/>[registry.ts]"]
  node_capability_executor["Capability executor<br/>[executor.ts]"]
  node_provider_router["Provider router<br/>[router.ts]"]
  node_longbridge["Longbridge adapter<br/>[adapter.ts]"]
  node_massive["Massive adapter<br/>[adapter.ts]"]
  node_longbridge_tools["Longbridge tools<br/>[parser.ts]"]
end

subgraph group_research["Research workflows"]
  node_research_service["Deep research<br/>[service.ts]"]
  node_screening["Discovery screening<br/>[service.ts]"]
  node_research_diff["Research diff<br/>[diff-service.ts]"]
  node_thesis["Thesis tracking<br/>[service.ts]"]
end

subgraph group_monitoring["Portfolio monitoring"]
  node_portfolio_risk["Portfolio risk<br/>[service.ts]"]
  node_alerts["Alert engine<br/>[engine.ts]"]
  node_outcomes["Outcome tracking<br/>[engine.ts]"]
end

subgraph group_evaluation["Evaluation and observability"]
  node_evaluation["Evaluation service"]
  node_evaluation_backend["Evaluation backends<br/>[backend.ts]"]
end

node_investor(("Investor"))

node_investor -->|"selects context"| node_workbench
node_workbench -.->|"requests operations"| node_ui_client
node_electron_renderer -->|"invokes IPC client"| node_renderer_bridge
node_renderer_bridge -->|"calls exposed API"| node_preload
node_preload -.->|"dispatches IPC"| node_electron_main
node_electron_main -.->|"hosts kernel"| node_kernel_host
node_kernel_host -.->|"configures runtime"| node_agent_kernel
node_agent_kernel -.->|"manages runs"| node_run_manager
node_run_manager -->|"persists sessions"| node_session_manager
node_session_manager -.->|"stores session data"| node_local_storage
node_agent_kernel -.->|"runs agent"| node_agent_backend
node_agent_backend -.->|"uses capabilities"| node_capability_registry
node_capability_executor -->|"executes registered"| node_capability_registry
node_provider_router -.->|"routes provider calls"| node_longbridge
node_provider_router -.->|"routes provider calls"| node_massive
node_longbridge -.->|"parses responses"| node_longbridge_tools
node_research_service -.->|"fetches evidence"| node_capability_executor
node_screening -.->|"screens candidates"| node_capability_executor
node_thesis -.->|"reevaluates findings"| node_research_service
node_research_diff -.->|"compares research"| node_thesis
node_portfolio_risk -->|"loads financial data"| node_capability_executor
node_alerts -->|"loads market status"| node_capability_registry
node_alerts -.->|"persists rule events"| node_local_storage
node_outcomes -.->|"tracks opinions"| node_research_service
node_evaluation -->|"runs benchmark cases"| node_agent_kernel
node_evaluation -.->|"records evaluations"| node_evaluation_backend

click node_workbench "https://github.com/helsome/folio/tree/main/packages/ui/src/components"
click node_ui_client "https://github.com/helsome/folio/blob/main/packages/ui/src/client.tsx"
click node_electron_renderer "https://github.com/helsome/folio/blob/main/apps/electron/src/renderer/App.tsx"
click node_renderer_bridge "https://github.com/helsome/folio/blob/main/apps/electron/src/renderer/finagentClient.ts"
click node_preload "https://github.com/helsome/folio/blob/main/apps/electron/src/preload/index.ts"
click node_electron_main "https://github.com/helsome/folio/blob/main/apps/electron/src/main/index.ts"
click node_kernel_host "https://github.com/helsome/folio/blob/main/apps/electron/src/main/kernelHost.ts"
click node_agent_kernel "https://github.com/helsome/folio/blob/main/packages/shared/src/kernel/agent-kernel.ts"
click node_run_manager "https://github.com/helsome/folio/blob/main/packages/shared/src/kernel/run-manager.ts"
click node_session_manager "https://github.com/helsome/folio/blob/main/packages/shared/src/kernel/session-manager.ts"
click node_agent_backend "https://github.com/helsome/folio/blob/main/packages/shared/src/agent/local-finance-agent-backend.ts"
click node_capability_registry "https://github.com/helsome/folio/blob/main/packages/shared/src/capabilities/registry.ts"
click node_capability_executor "https://github.com/helsome/folio/blob/main/packages/shared/src/capabilities/executor.ts"
click node_provider_router "https://github.com/helsome/folio/blob/main/packages/shared/src/providers/router.ts"
click node_longbridge "https://github.com/helsome/folio/blob/main/packages/shared/src/providers/longbridge/adapter.ts"
click node_massive "https://github.com/helsome/folio/blob/main/packages/shared/src/providers/massive/adapter.ts"
click node_longbridge_tools "https://github.com/helsome/folio/blob/main/packages/longbridge-tools/src/parser.ts"
click node_research_service "https://github.com/helsome/folio/blob/main/packages/shared/src/research/service.ts"
click node_screening "https://github.com/helsome/folio/blob/main/packages/shared/src/screening/service.ts"
click node_research_diff "https://github.com/helsome/folio/blob/main/packages/shared/src/research-diff/diff-service.ts"
click node_thesis "https://github.com/helsome/folio/blob/main/packages/shared/src/thesis/service.ts"
click node_portfolio_risk "https://github.com/helsome/folio/blob/main/packages/shared/src/portfolio-risk/service.ts"
click node_alerts "https://github.com/helsome/folio/blob/main/packages/shared/src/alerts/engine.ts"
click node_outcomes "https://github.com/helsome/folio/blob/main/packages/shared/src/outcome/engine.ts"
click node_evaluation "https://github.com/helsome/folio/blob/main/packages/shared/src/evaluation/experiment-service.ts"
click node_evaluation_backend "https://github.com/helsome/folio/blob/main/packages/shared/src/evaluation/backend.ts"
click node_local_storage "https://github.com/helsome/folio/blob/main/packages/shared/src/storage/json-file-store.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_workbench,node_ui_client,node_electron_renderer,node_renderer_bridge,node_preload,node_electron_main toneBlue
class node_kernel_host,node_agent_kernel,node_run_manager,node_session_manager,node_agent_backend,node_local_storage toneAmber
class node_capability_registry,node_capability_executor,node_provider_router,node_longbridge,node_massive,node_longbridge_tools toneMint
class node_research_service,node_screening,node_research_diff,node_thesis toneRose
class node_portfolio_risk,node_alerts,node_outcomes,node_investor toneIndigo
class node_evaluation,node_evaluation_backend toneTeal
```

## Components

### Desktop application

- [Research workbench](https://github.com/helsome/folio/tree/main/packages/ui/src/components): `packages/ui/src/components`
- [UI client](https://github.com/helsome/folio/blob/main/packages/ui/src/client.tsx): `packages/ui/src/client.tsx`
- [Electron renderer](https://github.com/helsome/folio/blob/main/apps/electron/src/renderer/App.tsx): `apps/electron/src/renderer/App.tsx`
- [Renderer IPC client](https://github.com/helsome/folio/blob/main/apps/electron/src/renderer/finagentClient.ts): `apps/electron/src/renderer/finagentClient.ts`
- [Preload bridge](https://github.com/helsome/folio/blob/main/apps/electron/src/preload/index.ts): `apps/electron/src/preload/index.ts`
- [Electron main process](https://github.com/helsome/folio/blob/main/apps/electron/src/main/index.ts): `apps/electron/src/main/index.ts`

### Agent runtime

- [Kernel host](https://github.com/helsome/folio/blob/main/apps/electron/src/main/kernelHost.ts): `apps/electron/src/main/kernelHost.ts`
- [Agent kernel](https://github.com/helsome/folio/blob/main/packages/shared/src/kernel/agent-kernel.ts): `packages/shared/src/kernel/agent-kernel.ts`
- [Run manager](https://github.com/helsome/folio/blob/main/packages/shared/src/kernel/run-manager.ts): `packages/shared/src/kernel/run-manager.ts`
- [Session manager](https://github.com/helsome/folio/blob/main/packages/shared/src/kernel/session-manager.ts): `packages/shared/src/kernel/session-manager.ts`
- [Agent backend](https://github.com/helsome/folio/blob/main/packages/shared/src/agent/local-finance-agent-backend.ts): `packages/shared/src/agent/local-finance-agent-backend.ts`
- [Local session storage](https://github.com/helsome/folio/blob/main/packages/shared/src/storage/json-file-store.ts): `packages/shared/src/storage/json-file-store.ts`

### Data capabilities

- [Capability registry](https://github.com/helsome/folio/blob/main/packages/shared/src/capabilities/registry.ts): `packages/shared/src/capabilities/registry.ts`
- [Capability executor](https://github.com/helsome/folio/blob/main/packages/shared/src/capabilities/executor.ts): `packages/shared/src/capabilities/executor.ts`
- [Provider router](https://github.com/helsome/folio/blob/main/packages/shared/src/providers/router.ts): `packages/shared/src/providers/router.ts`
- [Longbridge adapter](https://github.com/helsome/folio/blob/main/packages/shared/src/providers/longbridge/adapter.ts): `packages/shared/src/providers/longbridge/adapter.ts`
- [Massive adapter](https://github.com/helsome/folio/blob/main/packages/shared/src/providers/massive/adapter.ts): `packages/shared/src/providers/massive/adapter.ts`
- [Longbridge tools](https://github.com/helsome/folio/blob/main/packages/longbridge-tools/src/parser.ts): `packages/longbridge-tools/src/parser.ts`

### Research workflows

- [Deep research](https://github.com/helsome/folio/blob/main/packages/shared/src/research/service.ts): `packages/shared/src/research/service.ts`
- [Discovery screening](https://github.com/helsome/folio/blob/main/packages/shared/src/screening/service.ts): `packages/shared/src/screening/service.ts`
- [Research diff](https://github.com/helsome/folio/blob/main/packages/shared/src/research-diff/diff-service.ts): `packages/shared/src/research-diff/diff-service.ts`
- [Thesis tracking](https://github.com/helsome/folio/blob/main/packages/shared/src/thesis/service.ts): `packages/shared/src/thesis/service.ts`

### Portfolio monitoring

- [Portfolio risk](https://github.com/helsome/folio/blob/main/packages/shared/src/portfolio-risk/service.ts): `packages/shared/src/portfolio-risk/service.ts`
- [Alert engine](https://github.com/helsome/folio/blob/main/packages/shared/src/alerts/engine.ts): `packages/shared/src/alerts/engine.ts`
- [Outcome tracking](https://github.com/helsome/folio/blob/main/packages/shared/src/outcome/engine.ts): `packages/shared/src/outcome/engine.ts`

### Evaluation and observability

- [Evaluation service](https://github.com/helsome/folio/blob/main/packages/shared/src/evaluation/experiment-service.ts): `packages/shared/src/evaluation/experiment-service.ts`
- [Evaluation backends](https://github.com/helsome/folio/blob/main/packages/shared/src/evaluation/backend.ts): `packages/shared/src/evaluation/backend.ts`

### Other components

- **Investor**

## Connections

- Investor → Research workbench: selects context (evidence: `README.md`)
- Research workbench → UI client: requests operations (evidence: `packages/ui/src/components/settings/useSkillToggle.ts`)
- Electron renderer → Renderer IPC client: invokes IPC client (evidence: `apps/electron/src/renderer/finagentClient.ts`)
- Renderer IPC client → Preload bridge: calls exposed API (evidence: `apps/electron/src/renderer/finagentClient.ts`)
- Preload bridge → Electron main process: dispatches IPC
- Electron main process → Kernel host: hosts kernel
- Kernel host → Agent kernel: configures runtime
- Agent kernel → Run manager: manages runs
- Run manager → Session manager: persists sessions (evidence: `packages/shared/src/kernel/run-manager.ts`)
- Session manager → Local session storage: stores session data
- Agent kernel → Agent backend: runs agent
- Agent backend → Capability registry: uses capabilities
- Capability executor → Capability registry: executes registered (evidence: `packages/shared/src/capabilities/executor.ts`)
- Provider router → Longbridge adapter: routes provider calls
- Provider router → Massive adapter: routes provider calls
- Longbridge adapter → Longbridge tools: parses responses
- Deep research → Capability executor: fetches evidence
- Discovery screening → Capability executor: screens candidates
- Thesis tracking → Deep research: reevaluates findings
- Research diff → Thesis tracking: compares research
- Portfolio risk → Capability executor: loads financial data (evidence: `packages/shared/src/portfolio-risk/service.ts`)
- Alert engine → Capability registry: loads market status (evidence: `packages/shared/src/alerts/engine.ts`)
- Alert engine → Local session storage: persists rule events
- Outcome tracking → Deep research: tracks opinions
- Evaluation service → Agent kernel: runs benchmark cases (evidence: `packages/shared/src/evaluation/experiment-service.ts`)
- Evaluation service → Evaluation backends: records evaluations (evidence: `packages/shared/src/evaluation/experiment-service.ts`)
