# theprismsystem/beans-web architecture

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

- Interactive diagram: https://gitdiagram.com/theprismsystem/beans-web
- Repository: https://github.com/theprismsystem/beans-web

## Overview

beans-web is a local-first web interface for discovering and managing beans projects stored as Markdown files. Users browse project overviews and hierarchies, inspect and edit individual beans and their relationships, search across projects, and view analytics. The React app sends API requests to a Hono server, which discovers projects and proxies GraphQL operations to the beans CLI; search and analytics aggregate across projects, while file-change events are streamed to the UI. The README documents these capabilities; some internal route wiring is represented at the subsystem level because its source was not sampled.

Main entry points: [`apps/server/src/app.ts`](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/app.ts) (Hono server), [`apps/web/src/router.tsx`](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/router.tsx) (App routes), [`apps/web/src/api/client.ts`](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/api/client.ts) (API client), [`apps/web/src/hooks/useBeans.ts`](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/hooks/useBeans.ts) (Data hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_spa["React app<br/>[main.tsx]"]
  node_router["App routes<br/>[router.tsx]"]
  node_project_views["Project views<br/>[projectList.tsx]"]
  node_bean_detail["Bean detail<br/>[beanDetail.tsx]"]
  node_search_view["Search view<br/>[search.tsx]"]
  node_analytics_view["Analytics view<br/>[analytics.tsx]"]
  node_web_hooks["Data hooks<br/>[useBeans.ts]"]
  node_mutations["Bean mutations<br/>[useMutations.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["Server API"]
  node_server["Hono server<br/>[app.ts]"]
  node_project_routes["Project routes<br/>[projects.ts]"]
  node_graphql_routes["GraphQL routes<br/>[graphql.ts]"]
  node_search_routes["Search route<br/>[search.ts]"]
  node_analytics_routes["Analytics route<br/>[analytics.ts]"]
  node_events_routes["Events route<br/>[events.ts]"]
end

subgraph group_domain["Project services"]
  node_discovery["Project discovery<br/>[scan.ts]"]
  node_executor["CLI executor<br/>[executor.ts]"]
  node_search_aggregate["Search aggregation<br/>[search.ts]"]
  node_analytics_aggregate["Analytics aggregation<br/>[analytics.ts]"]
  node_watcher["File watcher<br/>[watcher.ts]"]
end

subgraph group_data["Local project data"]
  node_project_files[("Beans project files")]
end

node_user(("User"))
node_beans_cli(("beans CLI"))
node_browser_events(("Browser event stream"))

node_user -->|"uses"| node_spa
node_spa -->|"renders"| node_router
node_router -->|"routes"| node_project_views
node_router -->|"routes"| node_bean_detail
node_router -->|"routes"| node_search_view
node_router -->|"routes"| node_analytics_view
node_project_views -->|"loads project data"| node_web_hooks
node_bean_detail -->|"loads bean data"| node_web_hooks
node_search_view -->|"searches"| node_api_client
node_analytics_view -->|"loads analytics"| node_api_client
node_web_hooks -->|"requests data"| node_api_client
node_mutations -->|"sends changes"| node_api_client
node_api_client -->|"HTTP requests"| node_server
node_browser_events -->|"opens event stream"| node_server
node_server -->|"registers"| node_project_routes
node_server -->|"registers"| node_graphql_routes
node_server -->|"registers"| node_search_routes
node_server -->|"registers"| node_analytics_routes
node_server -->|"registers"| node_events_routes
node_project_routes -->|"lists projects"| node_discovery
node_graphql_routes -->|"runs operations"| node_executor
node_search_routes -->|"aggregates search"| node_search_aggregate
node_analytics_routes -->|"aggregates analytics"| node_analytics_aggregate
node_events_routes -->|"streams changes"| node_watcher
node_discovery -->|"scans roots"| node_project_files
node_executor -->|"invokes"| node_beans_cli
node_beans_cli -->|"reads and writes"| node_project_files
node_search_aggregate -->|"searches projects"| node_beans_cli
node_analytics_aggregate -->|"reads project data"| node_beans_cli
node_watcher -->|"watches changes"| node_project_files

click node_spa "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/main.tsx"
click node_router "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/router.tsx"
click node_project_views "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/routes/projectList.tsx"
click node_bean_detail "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/routes/beanDetail.tsx"
click node_search_view "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/routes/search.tsx"
click node_analytics_view "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/routes/analytics.tsx"
click node_web_hooks "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/hooks/useBeans.ts"
click node_mutations "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/hooks/useMutations.ts"
click node_api_client "https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/api/client.ts"
click node_server "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/app.ts"
click node_project_routes "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/projects.ts"
click node_graphql_routes "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/graphql.ts"
click node_search_routes "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/search.ts"
click node_analytics_routes "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/analytics.ts"
click node_events_routes "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/events.ts"
click node_discovery "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/discovery/scan.ts"
click node_executor "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/beans/executor.ts"
click node_search_aggregate "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/aggregate/search.ts"
click node_analytics_aggregate "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/aggregate/analytics.ts"
click node_watcher "https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/watch/watcher.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_spa,node_router,node_project_views,node_bean_detail,node_search_view,node_analytics_view,node_web_hooks,node_mutations,node_api_client,node_user,node_browser_events toneBlue
class node_server,node_project_routes,node_graphql_routes,node_search_routes,node_analytics_routes,node_events_routes toneAmber
class node_discovery,node_executor,node_search_aggregate,node_analytics_aggregate,node_watcher toneMint
class node_project_files toneRose
class node_beans_cli toneIndigo
```

## Components

### Web interface

- [React app](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [App routes](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/router.tsx): `apps/web/src/router.tsx`
- [Project views](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/routes/projectList.tsx): `apps/web/src/routes/projectList.tsx`
- [Bean detail](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/routes/beanDetail.tsx): `apps/web/src/routes/beanDetail.tsx`
- [Search view](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/routes/search.tsx): `apps/web/src/routes/search.tsx`
- [Analytics view](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/routes/analytics.tsx): `apps/web/src/routes/analytics.tsx`
- [Data hooks](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/hooks/useBeans.ts): `apps/web/src/hooks/useBeans.ts`
- [Bean mutations](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/hooks/useMutations.ts): `apps/web/src/hooks/useMutations.ts`
- [API client](https://github.com/theprismsystem/beans-web/blob/main/apps/web/src/api/client.ts): `apps/web/src/api/client.ts`

### Server API

- [Hono server](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [Project routes](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/projects.ts): `apps/server/src/routes/projects.ts`
- [GraphQL routes](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/graphql.ts): `apps/server/src/routes/graphql.ts`
- [Search route](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/search.ts): `apps/server/src/routes/search.ts`
- [Analytics route](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/analytics.ts): `apps/server/src/routes/analytics.ts`
- [Events route](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/routes/events.ts): `apps/server/src/routes/events.ts`

### Project services

- [Project discovery](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/discovery/scan.ts): `apps/server/src/discovery/scan.ts`
- [CLI executor](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/beans/executor.ts): `apps/server/src/beans/executor.ts`
- [Search aggregation](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/aggregate/search.ts): `apps/server/src/aggregate/search.ts`
- [Analytics aggregation](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/aggregate/analytics.ts): `apps/server/src/aggregate/analytics.ts`
- [File watcher](https://github.com/theprismsystem/beans-web/blob/main/apps/server/src/watch/watcher.ts): `apps/server/src/watch/watcher.ts`

### Local project data

- **Beans project files**

### Other components

- **User**
- **beans CLI**
- **Browser event stream**

## Connections

- User → React app: uses
- React app → App routes: renders
- App routes → Project views: routes
- App routes → Bean detail: routes
- App routes → Search view: routes
- App routes → Analytics view: routes
- Project views → Data hooks: loads project data
- Bean detail → Data hooks: loads bean data
- Search view → API client: searches
- Analytics view → API client: loads analytics
- Data hooks → API client: requests data
- Bean mutations → API client: sends changes
- API client → Hono server: HTTP requests
- Browser event stream → Hono server: opens event stream
- Hono server → Project routes: registers
- Hono server → GraphQL routes: registers
- Hono server → Search route: registers
- Hono server → Analytics route: registers
- Hono server → Events route: registers
- Project routes → Project discovery: lists projects
- GraphQL routes → CLI executor: runs operations
- Search route → Search aggregation: aggregates search
- Analytics route → Analytics aggregation: aggregates analytics
- Events route → File watcher: streams changes
- Project discovery → Beans project files: scans roots
- CLI executor → beans CLI: invokes
- beans CLI → Beans project files: reads and writes
- Search aggregation → beans CLI: searches projects
- Analytics aggregation → beans CLI: reads project data
- File watcher → Beans project files: watches changes