# nickvasilescu/bops architecture

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

- Interactive diagram: https://gitdiagram.com/nickvasilescu/bops
- Repository: https://github.com/nickvasilescu/bops

## Overview

Bops is a Mac-hosted AI-bot operations app: users chat with workspace bots, which run tasks on cloud computers and report back through chat or connected channels. The Next.js app exposes the user-facing workflows; session orchestration provisions computers and coordinates task execution, while distinct services support memory, apps, communications, and monitoring. Bops Cloud brokers hosted provider access, and an optional edge relay forwards public webhooks. Several subsystem links below are based on README descriptions because their implementation excerpts were not supplied.

Main entry points: [`lib/server/sessions.ts`](https://github.com/nickvasilescu/bops/blob/main/lib/server/sessions.ts) (Task sessions), [`cloud/server.ts`](https://github.com/nickvasilescu/bops/blob/main/cloud/server.ts) (Bops Cloud), [`components/app/bops-app.tsx`](https://github.com/nickvasilescu/bops/blob/main/components/app/bops-app.tsx) (Bops interface), [`app/api/sessions/route.ts`](https://github.com/nickvasilescu/bops/blob/main/app/api/sessions/route.ts) (App API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mac app"]
  node_desktop["Desktop shell<br/>[main.cjs]"]
  node_app["Bops interface<br/>[bops-app.tsx]"]
  node_chat["Chat threads<br/>[chat-view.tsx]"]
  node_api["App API<br/>[route.ts]"]
end

subgraph group_work["Bot work"]
  node_sessions["Task sessions<br/>[sessions.ts]"]
  node_computer["Bot computers<br/>[orgo.ts]"]
  node_screen["Live screens<br/>[screens.ts]"]
  node_mac["Mac computer use<br/>[codex.ts]"]
end

subgraph group_capabilities["Bot capabilities"]
  node_memory["Long-term memory<br/>[memory.ts]"]
  node_apps["Connected apps<br/>[composio.ts]"]
  node_approval["Action approvals<br/>[route.ts]"]
  node_channels["Team channels<br/>[channels.ts]"]
  node_mail["Bot email<br/>[mail.ts]"]
  node_phone["Texts and calls<br/>[phone.ts]"]
  node_routines["Routines and watches<br/>[watches.ts]"]
end

subgraph group_state["State and services"]
  node_store[("App state<br/>[store.ts]")]
  node_persistence[("Persistence<br/>[persist.ts]")]
end

subgraph group_hosted["Hosted services"]
  node_cloudclient["Cloud client<br/>[cloud.ts]"]
  node_cloud["Bops Cloud<br/>[server.ts]"]
  node_cloudsession["Cloud accounts<br/>[session.ts]"]
  node_edge["Webhook relay<br/>[server.mjs]"]
end

node_owner(("User"))
node_providers["External providers"]

node_owner -->|"opens"| node_desktop
node_desktop -->|"loads"| node_app
node_owner -->|"uses"| node_app
node_app -.->|"offers chat"| node_chat
node_chat -.->|"submits tasks"| node_api
node_api -.->|"starts sessions"| node_sessions
node_sessions -->|"provisions"| node_computer
node_sessions -->|"updates state"| node_store
node_sessions -->|"coordinates screens"| node_screen
node_owner -->|"watches or takes over"| node_screen
node_sessions -->|"uses on request"| node_mac
node_sessions -->|"uses workspace memory"| node_memory
node_sessions -->|"uses connected apps"| node_apps
node_apps -->|"requests approval"| node_approval
node_owner -->|"asks from channels"| node_channels
node_channels -->|"starts bot tasks"| node_sessions
node_owner -->|"emails tasks"| node_mail
node_mail -->|"starts tasks"| node_sessions
node_owner -->|"texts or calls"| node_phone
node_phone -->|"starts tasks"| node_sessions
node_owner -->|"configures reminders"| node_routines
node_store -->|"saves state"| node_persistence
node_cloudclient -->|"sends authenticated requests"| node_cloud
node_cloud -->|"routes session setup"| node_cloudsession
node_cloud -->|"brokers provider access"| node_providers
node_edge -->|"forwards webhooks"| node_api
node_providers -.->|"delivers channel events"| node_channels
node_providers -.->|"provides email"| node_mail
node_providers -.->|"provides telephony"| node_phone

click node_desktop "https://github.com/nickvasilescu/bops/blob/main/desktop/main.cjs"
click node_app "https://github.com/nickvasilescu/bops/blob/main/components/app/bops-app.tsx"
click node_chat "https://github.com/nickvasilescu/bops/blob/main/components/app/chat-view.tsx"
click node_api "https://github.com/nickvasilescu/bops/blob/main/app/api/sessions/route.ts"
click node_sessions "https://github.com/nickvasilescu/bops/blob/main/lib/server/sessions.ts"
click node_computer "https://github.com/nickvasilescu/bops/blob/main/lib/server/orgo.ts"
click node_screen "https://github.com/nickvasilescu/bops/blob/main/lib/server/screens.ts"
click node_mac "https://github.com/nickvasilescu/bops/blob/main/lib/server/codex.ts"
click node_memory "https://github.com/nickvasilescu/bops/blob/main/lib/server/memory.ts"
click node_apps "https://github.com/nickvasilescu/bops/blob/main/lib/server/composio.ts"
click node_approval "https://github.com/nickvasilescu/bops/blob/main/app/api/apps/approvals/route.ts"
click node_channels "https://github.com/nickvasilescu/bops/blob/main/lib/server/channels.ts"
click node_mail "https://github.com/nickvasilescu/bops/blob/main/lib/server/mail.ts"
click node_phone "https://github.com/nickvasilescu/bops/blob/main/lib/server/phone.ts"
click node_routines "https://github.com/nickvasilescu/bops/blob/main/lib/server/watches.ts"
click node_store "https://github.com/nickvasilescu/bops/blob/main/lib/server/store.ts"
click node_persistence "https://github.com/nickvasilescu/bops/blob/main/lib/server/persist.ts"
click node_cloudclient "https://github.com/nickvasilescu/bops/blob/main/lib/server/cloud.ts"
click node_cloud "https://github.com/nickvasilescu/bops/blob/main/cloud/server.ts"
click node_cloudsession "https://github.com/nickvasilescu/bops/blob/main/cloud/session.ts"
click node_edge "https://github.com/nickvasilescu/bops/blob/main/edge/server.mjs"

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_desktop,node_app,node_chat,node_api,node_owner toneBlue
class node_sessions,node_computer,node_screen,node_mac toneAmber
class node_memory,node_apps,node_approval,node_channels,node_mail,node_phone,node_routines toneMint
class node_store,node_persistence toneRose
class node_cloudclient,node_cloud,node_cloudsession,node_edge,node_providers toneIndigo
```

## Components

### Mac app

- [Desktop shell](https://github.com/nickvasilescu/bops/blob/main/desktop/main.cjs): `desktop/main.cjs`
- [Bops interface](https://github.com/nickvasilescu/bops/blob/main/components/app/bops-app.tsx): `components/app/bops-app.tsx`
- [Chat threads](https://github.com/nickvasilescu/bops/blob/main/components/app/chat-view.tsx): `components/app/chat-view.tsx`
- [App API](https://github.com/nickvasilescu/bops/blob/main/app/api/sessions/route.ts): `app/api/sessions/route.ts`

### Bot work

- [Task sessions](https://github.com/nickvasilescu/bops/blob/main/lib/server/sessions.ts): `lib/server/sessions.ts`
- [Bot computers](https://github.com/nickvasilescu/bops/blob/main/lib/server/orgo.ts): `lib/server/orgo.ts`
- [Live screens](https://github.com/nickvasilescu/bops/blob/main/lib/server/screens.ts): `lib/server/screens.ts`
- [Mac computer use](https://github.com/nickvasilescu/bops/blob/main/lib/server/codex.ts): `lib/server/codex.ts`

### Bot capabilities

- [Long-term memory](https://github.com/nickvasilescu/bops/blob/main/lib/server/memory.ts): `lib/server/memory.ts`
- [Connected apps](https://github.com/nickvasilescu/bops/blob/main/lib/server/composio.ts): `lib/server/composio.ts`
- [Action approvals](https://github.com/nickvasilescu/bops/blob/main/app/api/apps/approvals/route.ts): `app/api/apps/approvals/route.ts`
- [Team channels](https://github.com/nickvasilescu/bops/blob/main/lib/server/channels.ts): `lib/server/channels.ts`
- [Bot email](https://github.com/nickvasilescu/bops/blob/main/lib/server/mail.ts): `lib/server/mail.ts`
- [Texts and calls](https://github.com/nickvasilescu/bops/blob/main/lib/server/phone.ts): `lib/server/phone.ts`
- [Routines and watches](https://github.com/nickvasilescu/bops/blob/main/lib/server/watches.ts): `lib/server/watches.ts`

### State and services

- [App state](https://github.com/nickvasilescu/bops/blob/main/lib/server/store.ts): `lib/server/store.ts`
- [Persistence](https://github.com/nickvasilescu/bops/blob/main/lib/server/persist.ts): `lib/server/persist.ts`

### Hosted services

- [Cloud client](https://github.com/nickvasilescu/bops/blob/main/lib/server/cloud.ts): `lib/server/cloud.ts`
- [Bops Cloud](https://github.com/nickvasilescu/bops/blob/main/cloud/server.ts): `cloud/server.ts`
- [Cloud accounts](https://github.com/nickvasilescu/bops/blob/main/cloud/session.ts): `cloud/session.ts`
- [Webhook relay](https://github.com/nickvasilescu/bops/blob/main/edge/server.mjs): `edge/server.mjs`

### Other components

- **User**
- **External providers**

## Connections

- User → Desktop shell: opens
- Desktop shell → Bops interface: loads
- User → Bops interface: uses
- Bops interface → Chat threads: offers chat
- Chat threads → App API: submits tasks
- App API → Task sessions: starts sessions
- Task sessions → Bot computers: provisions (evidence: `lib/server/sessions.ts`)
- Task sessions → App state: updates state (evidence: `lib/server/sessions.ts`)
- Task sessions → Live screens: coordinates screens (evidence: `lib/server/sessions.ts`)
- User → Live screens: watches or takes over
- Task sessions → Mac computer use: uses on request (evidence: `lib/server/sessions.ts`)
- Task sessions → Long-term memory: uses workspace memory (evidence: `lib/server/sessions.ts`)
- Task sessions → Connected apps: uses connected apps (evidence: `lib/server/sessions.ts`)
- Connected apps → Action approvals: requests approval
- User → Team channels: asks from channels
- Team channels → Task sessions: starts bot tasks (evidence: `lib/server/sessions.ts`)
- User → Bot email: emails tasks
- Bot email → Task sessions: starts tasks (evidence: `lib/server/sessions.ts`)
- User → Texts and calls: texts or calls
- Texts and calls → Task sessions: starts tasks (evidence: `lib/server/sessions.ts`)
- User → Routines and watches: configures reminders
- App state → Persistence: saves state (evidence: `lib/server/store.ts`)
- Cloud client → Bops Cloud: sends authenticated requests (evidence: `lib/server/cloud.ts`)
- Bops Cloud → Cloud accounts: routes session setup (evidence: `cloud/server.ts`)
- Bops Cloud → External providers: brokers provider access
- Webhook relay → App API: forwards webhooks
- External providers → Team channels: delivers channel events
- External providers → Bot email: provides email
- External providers → Texts and calls: provides telephony
