# happier-dev/happier architecture

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

- Interactive diagram: https://gitdiagram.com/happier-dev/happier
- Repository: https://github.com/happier-dev/happier

## Overview

Happier is a multi-device control room for running coding agents on users’ machines. The main workflow is to choose a machine, project folder, and agent, start or attach to a session, then follow the transcript and steer or approve work from another device. Sessions can also delegate runs to other agents, switch engines, and support reviews. The graph includes the documented client/server/daemon roles and distinct agent, permission, replication, and connected-service capabilities. Source excerpts are partial, so some documented links are shown with README evidence rather than inferred source calls.

Main entry points: [`apps/cli/src/agent/runtime/initializeBackendRunSession.ts`](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/runtime/initializeBackendRunSession.ts) (Agent runtime), [`apps/ui/sources/components/sessions/transcript/items/useTranscriptItemsPipeline.tsx`](https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/components/sessions/transcript/items/useTranscriptItemsPipeline.tsx) (Happier app), [`apps/cli/src/daemon/connectedServices/accountGroups/switching/pipeline/switchPipeline.ts`](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/daemon/connectedServices/accountGroups/switching/pipeline/switchPipeline.ts) (Connected-service groups), [`apps/cli/bin/happier.mjs`](https://github.com/happier-dev/happier/blob/dev/apps/cli/bin/happier.mjs) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_ui["Happier app"]
  node_cli["CLI entry<br/>[happier.mjs]"]
  node_connected_ui["Service auth controls"]
  node_group_query["Group query"]
  node_new_session["New-session setup"]
end

subgraph group_coordination["Session coordination"]
  node_server["Happier server"]
  node_session["Session writes"]
  node_usage_sources[("Usage sources<br/>[sourceStorage.ts]")]
end

subgraph group_agents["Agent execution"]
  node_agent_runtime["Agent runtime"]
  node_acp["ACP agents"]
  node_execution_runs["Subagent runs"]
end

subgraph group_machine["Machine services"]
  node_daemon["Machine daemon<br/>[relayHostEngine.ts]"]
end

subgraph group_capabilities["Session capabilities"]
  node_permissions["Approvals"]
  node_reviews["Code reviews"]
  node_replication["Workspace replication"]
  node_job_store[("Replication jobs")]
  node_connected_groups["Connected-service groups<br/>[switchPipeline.ts]"]
  node_storage_policy["Transcript storage policy"]
end

node_user(("User"))

node_user -->|"starts session"| node_ui
node_user -->|"starts session"| node_cli
node_ui -->|"configures"| node_new_session
node_new_session -.->|"resolves storage"| node_storage_policy
node_ui -->|"follows session"| node_server
node_cli -->|"runs on machine"| node_daemon
node_daemon -.->|"launches agent"| node_agent_runtime
node_agent_runtime -.->|"supports ACP"| node_acp
node_agent_runtime -.->|"coordinates runs"| node_execution_runs
node_agent_runtime -.->|"requests approval"| node_permissions
node_agent_runtime -.->|"publishes updates"| node_session
node_server -.->|"routes updates"| node_session
node_ui -->|"steers and approves"| node_permissions
node_execution_runs -.->|"runs review"| node_reviews
node_user -.->|"replicates workspace"| node_replication
node_replication -->|"stores job state"| node_job_store
node_connected_ui -.->|"switches auth"| node_connected_groups
node_group_query -.->|"loads groups"| node_connected_groups
node_connected_groups -.->|"binds usage"| node_usage_sources

click node_ui "https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/components/sessions/transcript/items/useTranscriptItemsPipeline.tsx"
click node_cli "https://github.com/happier-dev/happier/blob/dev/apps/cli/bin/happier.mjs"
click node_server "https://github.com/happier-dev/happier/blob/dev/apps/server/sources/app/api/socket/sessionUpdateHandler.ts"
click node_session "https://github.com/happier-dev/happier/blob/dev/apps/server/sources/app/session/sessionWriteService.ts"
click node_daemon "https://github.com/happier-dev/happier/blob/dev/packages/cli-common/src/relayHost/relayHostEngine.ts"
click node_agent_runtime "https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/runtime/initializeBackendRunSession.ts"
click node_acp "https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/acp/createAcpBackend.ts"
click node_execution_runs "https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/executionRuns/runtime/ExecutionRunManager.ts"
click node_permissions "https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/permissions/permissionRequestCoordinator.ts"
click node_reviews "https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/reviews/engines/nativeReviewEngines.ts"
click node_replication "https://github.com/happier-dev/happier/blob/dev/apps/cli/src/workspaces/replication/createWorkspaceReplicationEngine.ts"
click node_job_store "https://github.com/happier-dev/happier/blob/dev/apps/cli/src/workspaces/replication/jobs/workspaceReplicationJobStore.ts"
click node_connected_groups "https://github.com/happier-dev/happier/blob/dev/apps/cli/src/daemon/connectedServices/accountGroups/switching/pipeline/switchPipeline.ts"
click node_connected_ui "https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/components/sessions/agentInput/hooks/useSessionConnectedServicesAuthSwitch.tsx"
click node_group_query "https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/hooks/server/connectedServices/useConnectedServiceAuthGroupsQuery.ts"
click node_usage_sources "https://github.com/happier-dev/happier/blob/dev/apps/server/sources/app/api/routes/connect/providerAccountUsage/sourceStorage.ts"
click node_storage_policy "https://github.com/happier-dev/happier/blob/dev/packages/protocol/src/encryption/storagePolicyDecisions.ts"
click node_new_session "https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/components/sessions/new/hooks/screenModel/useNewSessionTranscriptStorageState.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_ui,node_cli,node_connected_ui,node_group_query,node_new_session,node_user toneBlue
class node_server,node_session,node_usage_sources toneAmber
class node_agent_runtime,node_acp,node_execution_runs toneMint
class node_daemon toneRose
class node_permissions,node_reviews,node_replication,node_job_store,node_connected_groups,node_storage_policy toneIndigo
```

## Components

### User clients

- [Happier app](https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/components/sessions/transcript/items/useTranscriptItemsPipeline.tsx): `apps/ui/sources/components/sessions/transcript/items/useTranscriptItemsPipeline.tsx`
- [CLI entry](https://github.com/happier-dev/happier/blob/dev/apps/cli/bin/happier.mjs): `apps/cli/bin/happier.mjs`
- [Service auth controls](https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/components/sessions/agentInput/hooks/useSessionConnectedServicesAuthSwitch.tsx): `apps/ui/sources/components/sessions/agentInput/hooks/useSessionConnectedServicesAuthSwitch.tsx`
- [Group query](https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/hooks/server/connectedServices/useConnectedServiceAuthGroupsQuery.ts): `apps/ui/sources/hooks/server/connectedServices/useConnectedServiceAuthGroupsQuery.ts`
- [New-session setup](https://github.com/happier-dev/happier/blob/dev/apps/ui/sources/components/sessions/new/hooks/screenModel/useNewSessionTranscriptStorageState.ts): `apps/ui/sources/components/sessions/new/hooks/screenModel/useNewSessionTranscriptStorageState.ts`

### Session coordination

- [Happier server](https://github.com/happier-dev/happier/blob/dev/apps/server/sources/app/api/socket/sessionUpdateHandler.ts): `apps/server/sources/app/api/socket/sessionUpdateHandler.ts`
- [Session writes](https://github.com/happier-dev/happier/blob/dev/apps/server/sources/app/session/sessionWriteService.ts): `apps/server/sources/app/session/sessionWriteService.ts`
- [Usage sources](https://github.com/happier-dev/happier/blob/dev/apps/server/sources/app/api/routes/connect/providerAccountUsage/sourceStorage.ts): `apps/server/sources/app/api/routes/connect/providerAccountUsage/sourceStorage.ts`

### Agent execution

- [Agent runtime](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/runtime/initializeBackendRunSession.ts): `apps/cli/src/agent/runtime/initializeBackendRunSession.ts`
- [ACP agents](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/acp/createAcpBackend.ts): `apps/cli/src/agent/acp/createAcpBackend.ts`
- [Subagent runs](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/executionRuns/runtime/ExecutionRunManager.ts): `apps/cli/src/agent/executionRuns/runtime/ExecutionRunManager.ts`

### Machine services

- [Machine daemon](https://github.com/happier-dev/happier/blob/dev/packages/cli-common/src/relayHost/relayHostEngine.ts): `packages/cli-common/src/relayHost/relayHostEngine.ts`

### Session capabilities

- [Approvals](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/permissions/permissionRequestCoordinator.ts): `apps/cli/src/agent/permissions/permissionRequestCoordinator.ts`
- [Code reviews](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/agent/reviews/engines/nativeReviewEngines.ts): `apps/cli/src/agent/reviews/engines/nativeReviewEngines.ts`
- [Workspace replication](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/workspaces/replication/createWorkspaceReplicationEngine.ts): `apps/cli/src/workspaces/replication/createWorkspaceReplicationEngine.ts`
- [Replication jobs](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/workspaces/replication/jobs/workspaceReplicationJobStore.ts): `apps/cli/src/workspaces/replication/jobs/workspaceReplicationJobStore.ts`
- [Connected-service groups](https://github.com/happier-dev/happier/blob/dev/apps/cli/src/daemon/connectedServices/accountGroups/switching/pipeline/switchPipeline.ts): `apps/cli/src/daemon/connectedServices/accountGroups/switching/pipeline/switchPipeline.ts`
- [Transcript storage policy](https://github.com/happier-dev/happier/blob/dev/packages/protocol/src/encryption/storagePolicyDecisions.ts): `packages/protocol/src/encryption/storagePolicyDecisions.ts`

### Other components

- **User**

## Connections

- User → Happier app: starts session (evidence: `README.md`)
- User → CLI entry: starts session (evidence: `README.md`)
- Happier app → New-session setup: configures (evidence: `apps/ui/sources/components/sessions/new/hooks/screenModel/useNewSessionTranscriptStorageState.ts`)
- New-session setup → Transcript storage policy: resolves storage
- Happier app → Happier server: follows session (evidence: `README.md`)
- CLI entry → Machine daemon: runs on machine (evidence: `README.md`)
- Machine daemon → Agent runtime: launches agent
- Agent runtime → ACP agents: supports ACP
- Agent runtime → Subagent runs: coordinates runs
- Agent runtime → Approvals: requests approval
- Agent runtime → Session writes: publishes updates
- Happier server → Session writes: routes updates
- Happier app → Approvals: steers and approves (evidence: `README.md`)
- Subagent runs → Code reviews: runs review
- User → Workspace replication: replicates workspace
- Workspace replication → Replication jobs: stores job state (evidence: `apps/cli/src/workspaces/replication/createWorkspaceReplicationEngine.ts`)
- Service auth controls → Connected-service groups: switches auth
- Group query → Connected-service groups: loads groups
- Connected-service groups → Usage sources: binds usage
