# puppyone-ai/puppyone architecture

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

- Interactive diagram: https://gitdiagram.com/puppyone-ai/puppyone
- Repository: https://github.com/puppyone-ai/puppyone

## Overview

puppyone is a desktop workspace for local folders and coding agents, with optional Cloud access for sharing folders across agents and teammates. The principal flow is opening a folder, working with its files and Git history, and optionally connecting it to Cloud so agents can reach it; local agents can also run in the app. The graph emphasizes documented capabilities and relationships visible in the supplied excerpts or source index. Several subsystems are represented at directory level because their implementation was not sampled.

Main entry points: [`src/App.tsx`](https://github.com/puppyone-ai/puppyone/blob/main/src/App.tsx) (Desktop App UI), [`src/app/useProjectOpeningSurfaces.tsx`](https://github.com/puppyone-ai/puppyone/blob/main/src/app/useProjectOpeningSurfaces.tsx) (Project Opening), [`src/lib/cloudApi.ts`](https://github.com/puppyone-ai/puppyone/blob/main/src/lib/cloudApi.ts) (Cloud API), [`src/features/source-control/useDesktopGitController.ts`](https://github.com/puppyone-ai/puppyone/blob/main/src/features/source-control/useDesktopGitController.ts) (Git Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace and Files"]
  node_app_ui["Desktop App UI<br/>[App.tsx]"]
  node_project_opening["Project Opening"]
  node_local_file_api["Local File API<br/>[path-policy.mjs]"]
  node_editor["Document Editor"]
  node_app_preview["App Preview"]
  node_database_preview["Database Preview"]
end

subgraph group_agents["Agent Runtime"]
  node_agent_ui["Agent UI"]
  node_agent_runtime["Agent Runtime<br/>[agent-service.mjs]"]
  node_agent_protocols["Agent Protocols<br/>[acp-client.mjs]"]
  node_agent_host["Agent Host"]
end

subgraph group_cloud["Cloud and Sharing"]
  node_cloud_auth["Cloud Authentication"]
  node_cloud_context["Repository Cloud Context"]
  node_cloud_api["Cloud API<br/>[cloudApi.ts]"]
  node_cloud_catalog["Cloud Project Catalog"]
  node_cloud_preview["Cloud Preview"]
  node_cloud_folder[("Cloud Folder")]
end

subgraph group_source_control["Source Control"]
  node_git_controller["Git Controller"]
  node_git_lifecycle["Git Lifecycle"]
end

subgraph group_desktop["Desktop Services"]
  node_desktop_auth["Desktop Auth Service"]
  node_local_git["Local Git Operations<br/>[runner.mjs]"]
end

node_user(("User"))
node_external_agents(("Connected Agents"))

node_user -.->|"opens app"| node_app_ui
node_app_ui -->|"opens projects"| node_project_opening
node_project_opening -.->|"opens local files"| node_local_file_api
node_app_ui -.->|"manages Git"| node_git_controller
node_git_controller -.->|"calls operations"| node_local_git
node_git_controller -->|"uses lifecycle"| node_git_lifecycle
node_project_opening -.->|"shows documents"| node_editor
node_project_opening -.->|"previews apps"| node_app_preview
node_project_opening -.->|"previews databases"| node_database_preview
node_app_ui -.->|"uses agents"| node_agent_ui
node_agent_ui -.->|"submits references"| node_agent_runtime
node_agent_runtime -.->|"uses protocols"| node_agent_protocols
node_agent_host -.->|"creates runtime"| node_agent_runtime
node_app_ui -.->|"starts sign-in"| node_cloud_auth
node_cloud_auth -.->|"starts OAuth"| node_desktop_auth
node_cloud_context -->|"resolves project"| node_cloud_api
node_cloud_api -.->|"accesses folders"| node_cloud_folder
node_app_ui -.->|"browses projects"| node_cloud_catalog
node_cloud_api -.->|"requests preview"| node_cloud_preview
node_external_agents -.->|"reads and writes"| node_cloud_folder
node_user -.->|"shares folder"| node_cloud_folder

click node_app_ui "https://github.com/puppyone-ai/puppyone/blob/main/src/App.tsx"
click node_project_opening "https://github.com/puppyone-ai/puppyone/blob/main/src/app/useProjectOpeningSurfaces.tsx"
click node_local_file_api "https://github.com/puppyone-ai/puppyone/blob/main/electron/local-api/files/path-policy.mjs"
click node_editor "https://github.com/puppyone-ai/puppyone/blob/main/src/shared-ui/editor/document-session/documentStorageReads.ts"
click node_app_preview "https://github.com/puppyone-ai/puppyone/blob/main/src/shared-ui/editor/viewers/app/useAppPreviewSession.ts"
click node_database_preview "https://github.com/puppyone-ai/puppyone/blob/main/src/platform/databasePreviewClient.ts"
click node_git_controller "https://github.com/puppyone-ai/puppyone/blob/main/src/features/source-control/useDesktopGitController.ts"
click node_git_lifecycle "https://github.com/puppyone-ai/puppyone/blob/main/src/features/source-control/useGitRepositoryLifecycle.ts"
click node_cloud_auth "https://github.com/puppyone-ai/puppyone/blob/main/src/features/cloud/hooks/useCloudAuthController.ts"
click node_cloud_context "https://github.com/puppyone-ai/puppyone/blob/main/src/features/cloud/project/context/useCurrentRepositoryCloudContext.ts"
click node_cloud_api "https://github.com/puppyone-ai/puppyone/blob/main/src/lib/cloudApi.ts"
click node_cloud_catalog "https://github.com/puppyone-ai/puppyone/blob/main/archive/desktop-cloud-catalog/src/features/cloud/data/useCloudProjectCatalog.ts"
click node_cloud_preview "https://github.com/puppyone-ai/puppyone/blob/main/electron/main/cloud-native-preview-service.mjs"
click node_agent_ui "https://github.com/puppyone-ai/puppyone/blob/main/src/features/desktop-agent/ui/useAgentReferenceIngestion.ts"
click node_agent_runtime "https://github.com/puppyone-ai/puppyone/blob/main/electron/main/agent/application/agent-service.mjs"
click node_agent_protocols "https://github.com/puppyone-ai/puppyone/blob/main/electron/main/agent/protocols/acp/acp-client.mjs"
click node_agent_host "https://github.com/puppyone-ai/puppyone/blob/main/electron/main/agent/bootstrap/create-agent-runtime-host.mjs"
click node_desktop_auth "https://github.com/puppyone-ai/puppyone/blob/main/electron/cloud-auth-service.mjs"
click node_local_git "https://github.com/puppyone-ai/puppyone/blob/main/electron/local-api/git/runner.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_app_ui,node_project_opening,node_local_file_api,node_editor,node_app_preview,node_database_preview,node_user toneBlue
class node_agent_ui,node_agent_runtime,node_agent_protocols,node_agent_host toneAmber
class node_cloud_auth,node_cloud_context,node_cloud_api,node_cloud_catalog,node_cloud_preview,node_cloud_folder toneMint
class node_git_controller,node_git_lifecycle toneRose
class node_desktop_auth,node_local_git,node_external_agents toneIndigo
```

## Components

### Workspace and Files

- [Desktop App UI](https://github.com/puppyone-ai/puppyone/blob/main/src/App.tsx): `src/App.tsx`
- [Project Opening](https://github.com/puppyone-ai/puppyone/blob/main/src/app/useProjectOpeningSurfaces.tsx): `src/app/useProjectOpeningSurfaces.tsx`
- [Local File API](https://github.com/puppyone-ai/puppyone/blob/main/electron/local-api/files/path-policy.mjs): `electron/local-api/files/path-policy.mjs`
- [Document Editor](https://github.com/puppyone-ai/puppyone/blob/main/src/shared-ui/editor/document-session/documentStorageReads.ts): `src/shared-ui/editor/document-session/documentStorageReads.ts`
- [App Preview](https://github.com/puppyone-ai/puppyone/blob/main/src/shared-ui/editor/viewers/app/useAppPreviewSession.ts): `src/shared-ui/editor/viewers/app/useAppPreviewSession.ts`
- [Database Preview](https://github.com/puppyone-ai/puppyone/blob/main/src/platform/databasePreviewClient.ts): `src/platform/databasePreviewClient.ts`

### Agent Runtime

- [Agent UI](https://github.com/puppyone-ai/puppyone/blob/main/src/features/desktop-agent/ui/useAgentReferenceIngestion.ts): `src/features/desktop-agent/ui/useAgentReferenceIngestion.ts`
- [Agent Runtime](https://github.com/puppyone-ai/puppyone/blob/main/electron/main/agent/application/agent-service.mjs): `electron/main/agent/application/agent-service.mjs`
- [Agent Protocols](https://github.com/puppyone-ai/puppyone/blob/main/electron/main/agent/protocols/acp/acp-client.mjs): `electron/main/agent/protocols/acp/acp-client.mjs`
- [Agent Host](https://github.com/puppyone-ai/puppyone/blob/main/electron/main/agent/bootstrap/create-agent-runtime-host.mjs): `electron/main/agent/bootstrap/create-agent-runtime-host.mjs`

### Cloud and Sharing

- [Cloud Authentication](https://github.com/puppyone-ai/puppyone/blob/main/src/features/cloud/hooks/useCloudAuthController.ts): `src/features/cloud/hooks/useCloudAuthController.ts`
- [Repository Cloud Context](https://github.com/puppyone-ai/puppyone/blob/main/src/features/cloud/project/context/useCurrentRepositoryCloudContext.ts): `src/features/cloud/project/context/useCurrentRepositoryCloudContext.ts`
- [Cloud API](https://github.com/puppyone-ai/puppyone/blob/main/src/lib/cloudApi.ts): `src/lib/cloudApi.ts`
- [Cloud Project Catalog](https://github.com/puppyone-ai/puppyone/blob/main/archive/desktop-cloud-catalog/src/features/cloud/data/useCloudProjectCatalog.ts): `archive/desktop-cloud-catalog/src/features/cloud/data/useCloudProjectCatalog.ts`
- [Cloud Preview](https://github.com/puppyone-ai/puppyone/blob/main/electron/main/cloud-native-preview-service.mjs): `electron/main/cloud-native-preview-service.mjs`
- **Cloud Folder**

### Source Control

- [Git Controller](https://github.com/puppyone-ai/puppyone/blob/main/src/features/source-control/useDesktopGitController.ts): `src/features/source-control/useDesktopGitController.ts`
- [Git Lifecycle](https://github.com/puppyone-ai/puppyone/blob/main/src/features/source-control/useGitRepositoryLifecycle.ts): `src/features/source-control/useGitRepositoryLifecycle.ts`

### Desktop Services

- [Desktop Auth Service](https://github.com/puppyone-ai/puppyone/blob/main/electron/cloud-auth-service.mjs): `electron/cloud-auth-service.mjs`
- [Local Git Operations](https://github.com/puppyone-ai/puppyone/blob/main/electron/local-api/git/runner.mjs): `electron/local-api/git/runner.mjs`

### Other components

- **User**
- **Connected Agents**

## Connections

- User → Desktop App UI: opens app (evidence: `README.md`)
- Desktop App UI → Project Opening: opens projects (evidence: `src/App.tsx`)
- Project Opening → Local File API: opens local files
- Desktop App UI → Git Controller: manages Git
- Git Controller → Local Git Operations: calls operations
- Git Controller → Git Lifecycle: uses lifecycle (evidence: `src/features/source-control/useDesktopGitController.ts`)
- Project Opening → Document Editor: shows documents
- Project Opening → App Preview: previews apps
- Project Opening → Database Preview: previews databases
- Desktop App UI → Agent UI: uses agents
- Agent UI → Agent Runtime: submits references
- Agent Runtime → Agent Protocols: uses protocols
- Agent Host → Agent Runtime: creates runtime
- Desktop App UI → Cloud Authentication: starts sign-in
- Cloud Authentication → Desktop Auth Service: starts OAuth
- Repository Cloud Context → Cloud API: resolves project (evidence: `src/features/cloud/project/context/useCurrentRepositoryCloudContext.ts`)
- Cloud API → Cloud Folder: accesses folders (evidence: `README.md`)
- Desktop App UI → Cloud Project Catalog: browses projects
- Cloud API → Cloud Preview: requests preview
- Connected Agents → Cloud Folder: reads and writes (evidence: `README.md`)
- User → Cloud Folder: shares folder (evidence: `README.md`)
