# heyputer/puter architecture

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

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

## Overview

Puter is a self-hostable personal cloud computer and developer platform. A user authenticates, then works with files and apps through the service; developers can also invoke AI, use cloud storage and key-value data, and run serverless workers. The graph combines those documented capabilities with backend components visible in the source index. Several product areas were not sampled, so their internal call relationships are omitted rather than inferred.

Main entry points: [`src/backend/controllers/fs/FSController.ts`](https://github.com/heyputer/puter/blob/main/src/backend/controllers/fs/FSController.ts) (File API), [`src/backend/controllers/auth/AuthController.ts`](https://github.com/heyputer/puter/blob/main/src/backend/controllers/auth/AuthController.ts) (Auth endpoints), [`src/backend/controllers/puterai/PuterAIController.ts`](https://github.com/heyputer/puter/blob/main/src/backend/controllers/puterai/PuterAIController.ts) (AI endpoints), [`src/backend/services/auth/AuthService.ts`](https://github.com/heyputer/puter/blob/main/src/backend/services/auth/AuthService.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Requests and identity"]
  node_auth_api["Auth endpoints<br/>[AuthController.ts]"]
  node_auth_service["Authentication<br/>[AuthService.ts]"]
end

subgraph group_cloud["Cloud workspace"]
  node_filesystem_api["File API<br/>[FSController.ts]"]
  node_filesystem_service["Filesystem service<br/>[FSService.ts]"]
  node_file_entries[("File metadata<br/>[FSEntryStore.ts]")]
  node_path_resolution["Path resolution<br/>[resolveNode.ts]"]
  node_path_masking["Shared path masking<br/>[sharePathMask.ts]"]
  node_app_service["App management<br/>[AppService.ts]"]
  node_app_store[("App records<br/>[AppStore.js]")]
end

subgraph group_platform["Developer platform"]
  node_ai_api["AI endpoints"]
  node_chat_driver["AI chat driver"]
  node_worker_driver["Serverless workers<br/>[WorkerDriver.ts]"]
  node_kv_driver["Key-value database<br/>[KVStoreDriver.ts]"]
end

subgraph group_infrastructure["Backend foundations"]
  node_user_store[("User accounts<br/>[UserStore.ts]")]
  node_metering["Usage metering<br/>[MeteringService.ts]"]
  node_database["Database clients<br/>[DatabaseClient.ts]"]
  node_object_storage["Object storage<br/>[S3Client.ts]"]
end

node_user(("User"))
node_developer(("App developer"))

node_user -->|"signs in"| node_auth_api
node_auth_api -->|"uses auth"| node_auth_service
node_auth_api -->|"reads accounts"| node_user_store
node_auth_service -->|"loads users"| node_user_store
node_user -->|"manages files"| node_filesystem_api
node_filesystem_api -.->|"performs operations"| node_filesystem_service
node_filesystem_api -->|"resolves paths"| node_path_resolution
node_filesystem_api -->|"masks paths"| node_path_masking
node_filesystem_api -.->|"reads and writes"| node_file_entries
node_developer -->|"publishes apps"| node_app_service
node_app_service -.->|"manages records"| node_app_store
node_developer -->|"requests AI"| node_ai_api
node_ai_api -->|"invokes chat"| node_chat_driver
node_developer -->|"runs workers"| node_worker_driver
node_developer -->|"uses key-value data"| node_kv_driver
node_developer -->|"uses cloud storage"| node_object_storage
node_ai_api -.->|"accounts usage"| node_metering
node_filesystem_service -.->|"persists metadata"| node_database

click node_auth_api "https://github.com/heyputer/puter/blob/main/src/backend/controllers/auth/AuthController.ts"
click node_auth_service "https://github.com/heyputer/puter/blob/main/src/backend/services/auth/AuthService.ts"
click node_user_store "https://github.com/heyputer/puter/blob/main/src/backend/stores/user/UserStore.ts"
click node_filesystem_api "https://github.com/heyputer/puter/blob/main/src/backend/controllers/fs/FSController.ts"
click node_filesystem_service "https://github.com/heyputer/puter/blob/main/src/backend/services/fs/FSService.ts"
click node_file_entries "https://github.com/heyputer/puter/blob/main/src/backend/stores/fs/FSEntryStore.ts"
click node_path_resolution "https://github.com/heyputer/puter/blob/main/src/backend/services/fs/resolveNode.ts"
click node_path_masking "https://github.com/heyputer/puter/blob/main/src/backend/services/fs/sharePathMask.ts"
click node_app_service "https://github.com/heyputer/puter/blob/main/src/backend/services/apps/AppService.ts"
click node_app_store "https://github.com/heyputer/puter/blob/main/src/backend/stores/app/AppStore.js"
click node_ai_api "https://github.com/heyputer/puter/blob/main/src/backend/controllers/puterai/PuterAIController.ts"
click node_chat_driver "https://github.com/heyputer/puter/blob/main/src/backend/drivers/ai-chat/ChatCompletionDriver.ts"
click node_worker_driver "https://github.com/heyputer/puter/blob/main/src/backend/drivers/workers/WorkerDriver.ts"
click node_kv_driver "https://github.com/heyputer/puter/blob/main/src/backend/drivers/kv/KVStoreDriver.ts"
click node_metering "https://github.com/heyputer/puter/blob/main/src/backend/services/metering/MeteringService.ts"
click node_database "https://github.com/heyputer/puter/blob/main/src/backend/clients/database/DatabaseClient.ts"
click node_object_storage "https://github.com/heyputer/puter/blob/main/src/backend/clients/s3/S3Client.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_auth_api,node_auth_service,node_user toneBlue
class node_filesystem_api,node_filesystem_service,node_file_entries,node_path_resolution,node_path_masking,node_app_service,node_app_store toneAmber
class node_ai_api,node_chat_driver,node_worker_driver,node_kv_driver toneMint
class node_user_store,node_metering,node_database,node_object_storage toneRose
class node_developer toneIndigo
```

## Components

### Requests and identity

- [Auth endpoints](https://github.com/heyputer/puter/blob/main/src/backend/controllers/auth/AuthController.ts): `src/backend/controllers/auth/AuthController.ts`
- [Authentication](https://github.com/heyputer/puter/blob/main/src/backend/services/auth/AuthService.ts): `src/backend/services/auth/AuthService.ts`

### Cloud workspace

- [File API](https://github.com/heyputer/puter/blob/main/src/backend/controllers/fs/FSController.ts): `src/backend/controllers/fs/FSController.ts`
- [Filesystem service](https://github.com/heyputer/puter/blob/main/src/backend/services/fs/FSService.ts): `src/backend/services/fs/FSService.ts`
- [File metadata](https://github.com/heyputer/puter/blob/main/src/backend/stores/fs/FSEntryStore.ts): `src/backend/stores/fs/FSEntryStore.ts`
- [Path resolution](https://github.com/heyputer/puter/blob/main/src/backend/services/fs/resolveNode.ts): `src/backend/services/fs/resolveNode.ts`
- [Shared path masking](https://github.com/heyputer/puter/blob/main/src/backend/services/fs/sharePathMask.ts): `src/backend/services/fs/sharePathMask.ts`
- [App management](https://github.com/heyputer/puter/blob/main/src/backend/services/apps/AppService.ts): `src/backend/services/apps/AppService.ts`
- [App records](https://github.com/heyputer/puter/blob/main/src/backend/stores/app/AppStore.js): `src/backend/stores/app/AppStore.js`

### Developer platform

- [AI endpoints](https://github.com/heyputer/puter/blob/main/src/backend/controllers/puterai/PuterAIController.ts): `src/backend/controllers/puterai/PuterAIController.ts`
- [AI chat driver](https://github.com/heyputer/puter/blob/main/src/backend/drivers/ai-chat/ChatCompletionDriver.ts): `src/backend/drivers/ai-chat/ChatCompletionDriver.ts`
- [Serverless workers](https://github.com/heyputer/puter/blob/main/src/backend/drivers/workers/WorkerDriver.ts): `src/backend/drivers/workers/WorkerDriver.ts`
- [Key-value database](https://github.com/heyputer/puter/blob/main/src/backend/drivers/kv/KVStoreDriver.ts): `src/backend/drivers/kv/KVStoreDriver.ts`

### Backend foundations

- [User accounts](https://github.com/heyputer/puter/blob/main/src/backend/stores/user/UserStore.ts): `src/backend/stores/user/UserStore.ts`
- [Usage metering](https://github.com/heyputer/puter/blob/main/src/backend/services/metering/MeteringService.ts): `src/backend/services/metering/MeteringService.ts`
- [Database clients](https://github.com/heyputer/puter/blob/main/src/backend/clients/database/DatabaseClient.ts): `src/backend/clients/database/DatabaseClient.ts`
- [Object storage](https://github.com/heyputer/puter/blob/main/src/backend/clients/s3/S3Client.ts): `src/backend/clients/s3/S3Client.ts`

### Other components

- **User**
- **App developer**

## Connections

- User → Auth endpoints: signs in (evidence: `README.md`)
- Auth endpoints → Authentication: uses auth (evidence: `src/backend/controllers/auth/AuthController.ts`)
- Auth endpoints → User accounts: reads accounts (evidence: `src/backend/controllers/auth/AuthController.ts`)
- Authentication → User accounts: loads users (evidence: `src/backend/services/auth/AuthService.ts`)
- User → File API: manages files (evidence: `README.md`)
- File API → Filesystem service: performs operations
- File API → Path resolution: resolves paths (evidence: `src/backend/controllers/fs/FSController.ts`)
- File API → Shared path masking: masks paths (evidence: `src/backend/controllers/fs/FSController.ts`)
- File API → File metadata: reads and writes
- App developer → App management: publishes apps (evidence: `README.md`)
- App management → App records: manages records
- App developer → AI endpoints: requests AI (evidence: `README.md`)
- AI endpoints → AI chat driver: invokes chat (evidence: `src/backend/controllers/puterai/PuterAIController.ts`)
- App developer → Serverless workers: runs workers (evidence: `README.md`)
- App developer → Key-value database: uses key-value data (evidence: `README.md`)
- App developer → Object storage: uses cloud storage (evidence: `README.md`)
- AI endpoints → Usage metering: accounts usage
- Filesystem service → Database clients: persists metadata
