# yayasoumah/pocket-server architecture

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

- Interactive diagram: https://gitdiagram.com/yayasoumah/pocket-server
- Repository: https://github.com/yayasoumah/pocket-server

## Overview

##### Project type and purpose
- Pocket Server is a local-first Node.js “OS”/runtime for AI agents, exposing HTTP + WebSocket APIs for a mobile app and CLI.
- It orchestrates agent sessions (OpenAI/Anthropic), filesystem & terminal operations, background “Cursor” agents, notifications, and optional Cloudflare tunneling.

##### Top-level analysis of the file tree
- CLI entrypoint: cli.ts
- Core server: src/server (router.ts, websocket.ts) using Hono for REST + WS.
- Authentication: src/auth (pairing, token, middleware, device registry).
- Agent runtime: src/agent (providers, orchestrator, tools for both OpenAI + Anthropic).
- File system API: src/file-system (handlers, service, telescope search).
- Terminal API: src/terminal (routes, manager, registry).
- Background/cloud agents: src/background-agent/cursor.
- Notifications: src/notifications.
- Tunnel: src/tunnel/cloudflare.
- Shared utilities: src/shared (logger, paths, public-URL, types).
- Session store: src/agent/store (FS based).
- Config & scripts: package.json, scripts/release.mjs, CI workflows.

##### Key architectural patterns & principles
- Server-authoritative: all state lives under ~/.pocket-server/data.
- Event-driven UI: clients subscribe over WebSocket to server-emitted events.
- Modular, adapter-based providers: OpenAI vs. Anthropic share a common interface.
- Clean separation of concerns: auth, agents, FS, terminal, background tasks, notifications, tunnel.

##### Main components & their interactions
A. External clients
- Mobile App (iOS/Android)
- CLI (local terminal commands, desktop attach)
B. Pocket Server runtime (Node.js bundled)
1. HTTP REST API (Hono router)
2. WebSocket endpoint (/ws)
3. Auth module (pairing, token issuance)
4. Agent Orchestrator
- Context Loader → injects CLAUDE.md / AGENTS.md
- Provider Adapters → OpenAI / Anthropic
- Tools → editor, bash, web-search, planning
5. File System Service → browse/edit/diff via FS handlers
6. Terminal Service → PTY sessions, streaming
7. Background-Agent (Cursor) → GitHub VM jobs, webhooks
8. Notifications Service → device push events
9. Tunnel Module → Cloudflare quick-tunnel
10. Session Store (FS) → persists all session data
C. External services
- OpenAI API
- Anthropic API
- Cloudflare tunnel
- GitHub (for background-agent jobs)

##### Relationships & data flows
- Mobile App / CLI ⇄ HTTP REST (JSON) & WebSocket (events, streaming)
- Auth tokens secure both REST & WS (`Authorization: Pocket <token>` / `?token=`)
- Agent Orchestrator calls external LLM APIs via provider adapters
- File System & Terminal API modules interact with local FS and spawn PTYs
- Background-agent triggers jobs on GitHub VMs, receives updates via webhooks
- Notifications module publishes device notifications via push API
- Tunnel module uses Cloudflare CLI under the hood to expose public URL
- Session Store persists across all modules (authoritative state)

##### Architectural patterns & design principles
- Adapter pattern for LLM providers (common interface for OpenAI/Anthropic)
- Modular plugin-style tools for agents (editor, bash, search)
- Event-driven communication over WebSocket for UIs
- Server-authoritative state with FS-backed store
- CLI orchestrates lifecycle (pair, start, stop, attach, update)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        direction TB
        MobileApp["Mobile App"]:::clients
        CLIEntrypoint["CLI Entrypoint"]:::clients
    end

    %% Server Core Modules
    subgraph "Server Core" 
        direction TB
        HTTPRouter["HTTP REST API"]:::core
        WebSocketEndpoint["WebSocket Endpoint (/ws)"]:::core

        subgraph "Auth Module"
            direction TB
            Pairing["Pairing"]:::core
            TokenIssuance["Token Issuance"]:::core
            Middleware["Middleware"]:::core
            DeviceRegistry["Device Registry"]:::core
            AuthRoutes["Auth Routes"]:::core
            LocalWSAuth["Local WS Auth"]:::core
        end

        subgraph "Agent Orchestrator"
            direction TB
            AgentEntry["Agent Entry & Initialization"]:::core
            OrchestratorCore["Orchestrator Core"]:::core
            ContextLoader["Context Loader"]:::core
            ContextConfig["Context Config"]:::core
            subgraph "LLM Provider Adapters"
                direction TB
                OpenAIAdapter["OpenAI Adapter"]:::core
                AnthropicAdapter["Anthropic Adapter"]:::core
            end
        end

        subgraph "OpenAI Agent Module"
            direction TB
            OpenAICore["OpenAI Core Service"]:::core
            OpenAIStreaming["OpenAI Streaming"]:::core
            OpenAIPrompt["Prompts"]:::core
            OpenAIApprovals["Approvals"]:::core
        end

        subgraph "Anthropic Agent Module"
            direction TB
            AnthropicCore["Anthropic Core Service"]:::core
            AnthropicStreaming["Anthropic Streaming"]:::core
            AnthropicPrompt["Prompts"]:::core
        end

        subgraph "File System Service"
            direction TB
            FSIndex["Index"]:::core
            FSService["Service Layer"]:::core
            FSHandlers["Handlers"]:::core
            TelescopeSearch["Telescope Search"]:::core
        end

        subgraph "Terminal Service"
            direction TB
            TerminalRoutes["Terminal Routes"]:::core
            TerminalManager["Terminal Manager"]:::core
            TerminalRegistry["Terminal Registry"]:::core
        end

        subgraph "Background-Agent (Cursor)"
            direction TB
            BACore["Core & Client"]:::core
            GHItegration["GitHub Integration"]:::core
            BARoutes["Routes"]:::core
            WebhookHandler["Webhook Handling"]:::core
        end

        NotificationsService["Notifications Service"]:::core
        TunnelModule["Tunnel Module"]:::core
        SessionStoreFS["Session Store (FS)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAIAPI["OpenAI API"]:::external
        AnthropicAPI["Anthropic API"]:::external
        CloudflareTunnel["Cloudflare Tunnel"]:::external
        GitHub["GitHub"]:::external
    end

    %% Connections
    MobileApp -->|REST/JSON| HTTPRouter
    MobileApp -->|WS| WebSocketEndpoint
    CLIEntrypoint -->|launch/server| HTTPRouter
    CLIEntrypoint -->|attach WS| WebSocketEndpoint

    HTTPRouter -->|secures via token| Middleware
    WebSocketEndpoint -->|secures via token| LocalWSAuth

    Middleware --> AuthRoutes
    AuthRoutes --> TokenIssuance
    AuthRoutes --> Pairing
    AuthRoutes --> DeviceRegistry

    HTTPRouter --> FSHandlers
    FSHandlers --> FSService
    FSService --> TelescopeSearch

    HTTPRouter --> TerminalRoutes
    TerminalRoutes --> TerminalManager
    TerminalManager --> TerminalRegistry

    HTTPRouter --> BARoutes
    BARoutes --> BACore
    BACore --> GHItegration
    GHItegration --> GitHub
    WEBHOOK -->|webhook| WebhookHandler

    HTTPRouter --> NotificationsService
    NotificationsService -->|push| MobileApp

    HTTPRouter --> TunnelModule
    TunnelModule --> CloudflareTunnel

    HTTPRouter --> AgentEntry
    AgentEntry --> OrchestratorCore
    OrchestratorCore --> ContextLoader
    OrchestratorCore --> ContextConfig
    OrchestratorCore --> OpenAIAdapter
    OrchestratorCore --> AnthropicAdapter

    OpenAIAdapter --> OpenAICore
    OpenAICore --> OpenAIStreaming
    OpenAICore --> OpenAIPrompt
    OpenAIPrompt --> OpenAIApprovals

    AnthropicAdapter --> AnthropicCore
    AnthropicCore --> AnthropicStreaming
    AnthropicCore --> AnthropicPrompt

    OpenAICore -->|HTTP| OpenAIAPI
    AnthropicCore -->|HTTP| AnthropicAPI

    SessionStoreFS --> OrchestratorCore
    SessionStoreFS --> FSService
    SessionStoreFS --> TerminalManager
    SessionStoreFS --> BACore

    %% Click Events
    click CLIEntrypoint "https://github.com/yayasoumah/pocket-server/blob/main/cli.ts"
    click HTTPRouter "https://github.com/yayasoumah/pocket-server/blob/main/src/server/router.ts"
    click WebSocketEndpoint "https://github.com/yayasoumah/pocket-server/blob/main/src/server/websocket.ts"
    click Pairing "https://github.com/yayasoumah/pocket-server/blob/main/src/auth/pairing.ts"
    click TokenIssuance "https://github.com/yayasoumah/pocket-server/blob/main/src/auth/token.ts"
    click Middleware "https://github.com/yayasoumah/pocket-server/blob/main/src/auth/middleware.ts"
    click DeviceRegistry "https://github.com/yayasoumah/pocket-server/blob/main/src/auth/device-registry.ts"
    click AuthRoutes "https://github.com/yayasoumah/pocket-server/blob/main/src/auth/routes.ts"
    click LocalWSAuth "https://github.com/yayasoumah/pocket-server/blob/main/src/auth/local-ws.ts"
    click AgentEntry "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/index.ts"
    click OrchestratorCore "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/core/orchestrator.ts"
    click ContextLoader "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/context/loader.ts"
    click ContextConfig "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/context/config.ts"
    click OpenAIAdapter "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/providers/openai/adapter.ts"
    click AnthropicAdapter "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/providers/anthropic/adapter.ts"
    click OpenAICore "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/openai/service.ts"
    click OpenAIStreaming "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/openai/streaming.ts"
    click OpenAIPrompt "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/openai/prompt.ts"
    click OpenAIApprovals "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/openai/approvals.ts"
    click AnthropicCore "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/anthropic/anthropic.ts"
    click AnthropicStreaming "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/anthropic/streaming.ts"
    click AnthropicPrompt "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/anthropic/prompt.ts"
    click SessionStoreFS "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/store/session-store-fs.ts"
    click FSService "https://github.com/yayasoumah/pocket-server/blob/main/src/file-system/service.ts"
    click FSHandlers "https://github.com/yayasoumah/pocket-server/blob/main/src/file-system/handlers.ts"
    click TelescopeSearch "https://github.com/yayasoumah/pocket-server/blob/main/src/file-system/telescope-search.ts"
    click TerminalManager "https://github.com/yayasoumah/pocket-server/blob/main/src/terminal/terminal-manager.ts"
    click TerminalRegistry "https://github.com/yayasoumah/pocket-server/blob/main/src/terminal/registry.ts"
    click TerminalRoutes "https://github.com/yayasoumah/pocket-server/blob/main/src/terminal/routes.ts"
    click BACore "https://github.com/yayasoumah/pocket-server/blob/main/src/background-agent/cursor/index.ts"
    click GHItegration "https://github.com/yayasoumah/pocket-server/blob/main/src/background-agent/cursor/github.ts"
    click BARoutes "https://github.com/yayasoumah/pocket-server/blob/main/src/background-agent/cursor/routes.ts"
    click WebhookHandler "https://github.com/yayasoumah/pocket-server/blob/main/src/background-agent/cursor/webhook.ts"
    click NotificationsService "https://github.com/yayasoumah/pocket-server/blob/main/src/notifications/index.ts"
    click TunnelModule "https://github.com/yayasoumah/pocket-server/blob/main/src/tunnel/cloudflare.ts"
    click SessionStoreFS "https://github.com/yayasoumah/pocket-server/blob/main/src/agent/store/session-store-fs.ts"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1976d2,color:#0d47a1;
    classDef clients fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
    classDef external fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
    classDef storage fill:#eeeeee,stroke:#757575,color:#424242;
```
