# kingjetkong/puter architecture

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

- Interactive diagram: https://gitdiagram.com/kingjetkong/puter
- Repository: https://github.com/kingjetkong/puter

## Overview

Puter is a self-hostable personal-cloud platform: users access files and apps through its backend, while developers build and publish apps that can use cloud storage, databases, workers, and AI. The graph highlights the request/controller and filesystem stages, plus authentication and AI entry points. Several major capabilities are documented but their runtime wiring was not sampled, so those relationships are left out rather than inferred.

Main entry points: [`src/backend/controllers/fs/FSController.ts`](https://github.com/kingjetkong/puter/blob/main/src/backend/controllers/fs/FSController.ts) (File endpoints), [`src/backend/services/fs/resolveNode.ts`](https://github.com/kingjetkong/puter/blob/main/src/backend/services/fs/resolveNode.ts) (Path resolution), [`src/backend/stores/user/UserStore.ts`](https://github.com/kingjetkong/puter/blob/main/src/backend/stores/user/UserStore.ts) (User store), [`src/backend/core/http/PuterRouter.ts`](https://github.com/kingjetkong/puter/blob/main/src/backend/core/http/PuterRouter.ts) (HTTP routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request and identity"]
  node_http["HTTP routing<br/>[PuterRouter.ts]"]
  node_auth_controller["Auth endpoints<br/>[AuthController.ts]"]
  node_auth_service["Authentication<br/>[AuthService.ts]"]
  node_actor["Request actor<br/>[actor.ts]"]
  node_user_store[("User store<br/>[UserStore.ts]")]
end

subgraph group_cloud["Cloud services"]
  node_fs_controller["File endpoints<br/>[FSController.ts]"]
  node_fs_service["Filesystem service<br/>[FSService.ts]"]
  node_path_resolution["Path resolution<br/>[resolveNode.ts]"]
  node_share_mask["Share path masking<br/>[sharePathMask.ts]"]
  node_fs_entries["File metadata<br/>[FSEntry.ts]"]
  node_fs_store[("File metadata store<br/>[FSEntryStore.ts]")]
  node_object_storage[("Object storage<br/>[S3ObjectStore.ts]")]
end

subgraph group_developer["Developer platform"]
  node_app_platform["App platform<br/>[AppDriver.js]"]
  node_worker_platform["Serverless workers<br/>[WorkerDriver.ts]"]
  node_kv_store["Key-value database<br/>[KVStoreDriver.ts]"]
  node_dev_center["Developer center<br/>[apps.js]"]
end

subgraph group_ai["AI capabilities"]
  node_ai_controller["AI endpoints"]
  node_chat_driver["Chat completion"]
  node_image_driver["Image generation"]
  node_speech_driver["Speech services<br/>[TTSDriver.ts]"]
end

node_user(("User"))

node_user -.->|"makes requests"| node_http
node_http -.->|"routes requests"| node_auth_controller
node_auth_controller -->|"reads accounts"| node_user_store
node_auth_service -->|"looks up users"| node_user_store
node_user_store -->|"provides user rows"| node_actor
node_fs_controller -->|"resolves paths"| node_path_resolution
node_fs_controller -->|"masks shared paths"| node_share_mask
node_path_resolution -->|"reads entries"| node_fs_store
node_path_resolution -->|"uses entry records"| node_fs_entries
node_share_mask -->|"reads entries"| node_fs_store
node_fs_controller -->|"moves files"| node_fs_service
node_app_platform -.->|"publishes apps"| node_user
node_dev_center -.->|"builds and publishes"| node_app_platform
node_worker_platform -.->|"offers workers"| node_user
node_kv_store -.->|"offers app database"| node_user
node_fs_service -.->|"stores file content"| node_object_storage
node_user -.->|"requests AI"| node_ai_controller
node_ai_controller -->|"invokes chat"| node_chat_driver
node_user -.->|"uses AI creation"| node_image_driver
node_user -.->|"uses AI services"| node_speech_driver

click node_http "https://github.com/kingjetkong/puter/blob/main/src/backend/core/http/PuterRouter.ts"
click node_auth_controller "https://github.com/kingjetkong/puter/blob/main/src/backend/controllers/auth/AuthController.ts"
click node_auth_service "https://github.com/kingjetkong/puter/blob/main/src/backend/services/auth/AuthService.ts"
click node_actor "https://github.com/kingjetkong/puter/blob/main/src/backend/core/actor.ts"
click node_fs_controller "https://github.com/kingjetkong/puter/blob/main/src/backend/controllers/fs/FSController.ts"
click node_fs_service "https://github.com/kingjetkong/puter/blob/main/src/backend/services/fs/FSService.ts"
click node_path_resolution "https://github.com/kingjetkong/puter/blob/main/src/backend/services/fs/resolveNode.ts"
click node_share_mask "https://github.com/kingjetkong/puter/blob/main/src/backend/services/fs/sharePathMask.ts"
click node_fs_entries "https://github.com/kingjetkong/puter/blob/main/src/backend/stores/fs/FSEntry.ts"
click node_fs_store "https://github.com/kingjetkong/puter/blob/main/src/backend/stores/fs/FSEntryStore.ts"
click node_object_storage "https://github.com/kingjetkong/puter/blob/main/src/backend/stores/fs/S3ObjectStore.ts"
click node_user_store "https://github.com/kingjetkong/puter/blob/main/src/backend/stores/user/UserStore.ts"
click node_app_platform "https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/apps/AppDriver.js"
click node_worker_platform "https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/workers/WorkerDriver.ts"
click node_kv_store "https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/kv/KVStoreDriver.ts"
click node_dev_center "https://github.com/kingjetkong/puter/blob/main/src/dev-center/js/apps.js"
click node_ai_controller "https://github.com/kingjetkong/puter/blob/main/src/backend/controllers/puterai/PuterAIController.ts"
click node_chat_driver "https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/ai-chat/ChatCompletionDriver.ts"
click node_image_driver "https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/ai-image/ImageGenerationDriver.ts"
click node_speech_driver "https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/ai-tts/TTSDriver.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_http,node_auth_controller,node_auth_service,node_actor,node_user_store,node_user toneBlue
class node_fs_controller,node_fs_service,node_path_resolution,node_share_mask,node_fs_entries,node_fs_store,node_object_storage toneAmber
class node_app_platform,node_worker_platform,node_kv_store,node_dev_center toneMint
class node_ai_controller,node_chat_driver,node_image_driver,node_speech_driver toneRose
```

## Components

### Request and identity

- [HTTP routing](https://github.com/kingjetkong/puter/blob/main/src/backend/core/http/PuterRouter.ts): `src/backend/core/http/PuterRouter.ts`
- [Auth endpoints](https://github.com/kingjetkong/puter/blob/main/src/backend/controllers/auth/AuthController.ts): `src/backend/controllers/auth/AuthController.ts`
- [Authentication](https://github.com/kingjetkong/puter/blob/main/src/backend/services/auth/AuthService.ts): `src/backend/services/auth/AuthService.ts`
- [Request actor](https://github.com/kingjetkong/puter/blob/main/src/backend/core/actor.ts): `src/backend/core/actor.ts`
- [User store](https://github.com/kingjetkong/puter/blob/main/src/backend/stores/user/UserStore.ts): `src/backend/stores/user/UserStore.ts`

### Cloud services

- [File endpoints](https://github.com/kingjetkong/puter/blob/main/src/backend/controllers/fs/FSController.ts): `src/backend/controllers/fs/FSController.ts`
- [Filesystem service](https://github.com/kingjetkong/puter/blob/main/src/backend/services/fs/FSService.ts): `src/backend/services/fs/FSService.ts`
- [Path resolution](https://github.com/kingjetkong/puter/blob/main/src/backend/services/fs/resolveNode.ts): `src/backend/services/fs/resolveNode.ts`
- [Share path masking](https://github.com/kingjetkong/puter/blob/main/src/backend/services/fs/sharePathMask.ts): `src/backend/services/fs/sharePathMask.ts`
- [File metadata](https://github.com/kingjetkong/puter/blob/main/src/backend/stores/fs/FSEntry.ts): `src/backend/stores/fs/FSEntry.ts`
- [File metadata store](https://github.com/kingjetkong/puter/blob/main/src/backend/stores/fs/FSEntryStore.ts): `src/backend/stores/fs/FSEntryStore.ts`
- [Object storage](https://github.com/kingjetkong/puter/blob/main/src/backend/stores/fs/S3ObjectStore.ts): `src/backend/stores/fs/S3ObjectStore.ts`

### Developer platform

- [App platform](https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/apps/AppDriver.js): `src/backend/drivers/apps/AppDriver.js`
- [Serverless workers](https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/workers/WorkerDriver.ts): `src/backend/drivers/workers/WorkerDriver.ts`
- [Key-value database](https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/kv/KVStoreDriver.ts): `src/backend/drivers/kv/KVStoreDriver.ts`
- [Developer center](https://github.com/kingjetkong/puter/blob/main/src/dev-center/js/apps.js): `src/dev-center/js/apps.js`

### AI capabilities

- [AI endpoints](https://github.com/kingjetkong/puter/blob/main/src/backend/controllers/puterai/PuterAIController.ts): `src/backend/controllers/puterai/PuterAIController.ts`
- [Chat completion](https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/ai-chat/ChatCompletionDriver.ts): `src/backend/drivers/ai-chat/ChatCompletionDriver.ts`
- [Image generation](https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/ai-image/ImageGenerationDriver.ts): `src/backend/drivers/ai-image/ImageGenerationDriver.ts`
- [Speech services](https://github.com/kingjetkong/puter/blob/main/src/backend/drivers/ai-tts/TTSDriver.ts): `src/backend/drivers/ai-tts/TTSDriver.ts`

### Other components

- **User**

## Connections

- User → HTTP routing: makes requests
- HTTP routing → Auth endpoints: routes requests
- Auth endpoints → User store: reads accounts (evidence: `src/backend/controllers/auth/AuthController.ts`)
- Authentication → User store: looks up users (evidence: `src/backend/services/auth/AuthService.ts`)
- User store → Request actor: provides user rows (evidence: `src/backend/core/actor.ts`)
- File endpoints → Path resolution: resolves paths (evidence: `src/backend/controllers/fs/FSController.ts`)
- File endpoints → Share path masking: masks shared paths (evidence: `src/backend/controllers/fs/FSController.ts`)
- Path resolution → File metadata store: reads entries (evidence: `src/backend/services/fs/resolveNode.ts`)
- Path resolution → File metadata: uses entry records (evidence: `src/backend/services/fs/resolveNode.ts`)
- Share path masking → File metadata store: reads entries (evidence: `src/backend/services/fs/sharePathMask.ts`)
- File endpoints → Filesystem service: moves files (evidence: `src/backend/controllers/fs/FSController.ts`)
- App platform → User: publishes apps (evidence: `README.md`)
- Developer center → App platform: builds and publishes (evidence: `README.md`)
- Serverless workers → User: offers workers (evidence: `README.md`)
- Key-value database → User: offers app database (evidence: `README.md`)
- Filesystem service → Object storage: stores file content
- User → AI endpoints: requests AI (evidence: `README.md`)
- AI endpoints → Chat completion: invokes chat (evidence: `src/backend/controllers/puterai/PuterAIController.ts`)
- User → Image generation: uses AI creation (evidence: `README.md`)
- User → Speech services: uses AI services (evidence: `README.md`)
