# kevinjose102/cloud-storage-phone-cluster architecture

> Architecture diagram of the GitHub repository kevinjose102/cloud-storage-phone-cluster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kevinjose102/cloud-storage-phone-cluster
- Repository: https://github.com/kevinjose102/cloud-storage-phone-cluster

## Overview

PocketCluster uses Android phones as encrypted storage nodes, coordinated by a FastAPI backend. The principal workflow is file selection, text extraction and summarization, embedding generation, encryption and chunking, then distributed storage with metadata and replication. Search matches query embeddings against stored semantic representations; downloads retrieve chunks for client-side reconstruction. The Android service maintains node connectivity, while the web dashboard presents cluster health. The README documents the upload and download stages; some Android and backend wiring is unsampled, so uncertain call relationships are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/main.py) (FastAPI App), [`PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileRepository.kt`](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileRepository.kt) (File Repository), [`PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/websocket/WebSocketManager.kt`](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/websocket/WebSocketManager.kt) (Node WebSocket), [`backend/app/models`](https://github.com/kevinjose102/cloud-storage-phone-cluster/tree/main/backend/app/models) (Cluster Metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android Client"]
  node_android_ui["Client Screens"]
  node_file_repo["File Repository<br/>[FileRepository.kt]"]
  node_text_extract["Text Extraction"]
  node_summarize["Summary Engine<br/>[SummaryEngine.kt]"]
  node_embedding["Embedding Engine<br/>[EmbeddingEngine.kt]"]
  node_crypto["File Encryption<br/>[AsconFileCrypto.kt]"]
  node_chunker["File Chunking<br/>[FileChunker.kt]"]
  node_api_client["API Client<br/>[ApiClient.kt]"]
end

subgraph group_backend["Backend Coordination"]
  node_backend_app["FastAPI App<br/>[main.py]"]
  node_file_routes["File Routes<br/>[files.py]"]
  node_chunk_routes["Chunk Routes<br/>[chunks.py]"]
  node_device_routes["Device Routes<br/>[devices.py]"]
  node_metadata[("Cluster Metadata")]
  node_distribution["Chunk Distribution"]
  node_repair["Replication Repair<br/>[repair_manager.py]"]
  node_connection_manager["Connection Manager"]
  node_dashboard_route["Dashboard Route<br/>[dashboard.py]"]
end

subgraph group_cluster["Cluster Storage"]
  node_node_service["Node Service"]
  node_ws_manager["Node WebSocket"]
  node_chunk_store[("Local Chunk Store<br/>[ChunkStorage.kt]")]
  node_storage_nodes(("Phone Storage Nodes"))
end

subgraph group_dashboard["Cluster Dashboard"]
  node_dashboard_ui["Dashboard UI<br/>[app.js]"]
end

node_user(("User"))

node_user -->|"selects or searches"| node_android_ui
node_android_ui -->|"handles files"| node_file_repo
node_file_repo -->|"extracts text"| node_text_extract
node_file_repo -->|"summarizes content"| node_summarize
node_summarize -->|"embeds summary"| node_embedding
node_file_repo -->|"encrypts file"| node_crypto
node_crypto -->|"chunks ciphertext"| node_chunker
node_file_repo -->|"uploads metadata"| node_api_client
node_api_client -->|"HTTP requests"| node_backend_app
node_backend_app -->|"dispatches"| node_file_routes
node_backend_app -->|"dispatches"| node_chunk_routes
node_backend_app -->|"dispatches"| node_device_routes
node_file_routes -->|"stores file records"| node_metadata
node_chunk_routes -->|"stores chunk records"| node_metadata
node_chunk_routes -->|"requests distribution"| node_distribution
node_distribution -->|"dispatches node commands"| node_connection_manager
node_connection_manager -->|"sends commands"| node_storage_nodes
node_node_service -->|"starts connection"| node_ws_manager
node_ws_manager -->|"opens WebSocket"| node_backend_app
node_ws_manager -->|"reads and writes chunks"| node_chunk_store
node_ws_manager -->|"serves chunk transfers"| node_storage_nodes
node_repair -->|"checks replicas"| node_metadata
node_repair -->|"redistributes chunks"| node_distribution
node_backend_app -->|"dispatches"| node_dashboard_route
node_dashboard_ui -->|"fetches dashboard data"| node_dashboard_route
node_dashboard_route -->|"reads cluster state"| node_metadata
node_user -->|"views status"| node_dashboard_ui

click node_android_ui "https://github.com/kevinjose102/cloud-storage-phone-cluster/tree/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/screens"
click node_file_repo "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileRepository.kt"
click node_text_extract "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileTextExtractor.kt"
click node_summarize "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/ml/SummaryEngine.kt"
click node_embedding "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/ml/EmbeddingEngine.kt"
click node_crypto "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/AsconFileCrypto.kt"
click node_chunker "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileChunker.kt"
click node_api_client "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/network/ApiClient.kt"
click node_node_service "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/storage/StorageNodeService.kt"
click node_ws_manager "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/websocket/WebSocketManager.kt"
click node_chunk_store "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/storage/ChunkStorage.kt"
click node_backend_app "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/main.py"
click node_file_routes "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/api/routes/files.py"
click node_chunk_routes "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/api/routes/chunks.py"
click node_device_routes "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/api/routes/devices.py"
click node_metadata "https://github.com/kevinjose102/cloud-storage-phone-cluster/tree/main/backend/app/models"
click node_distribution "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/services/distribute_chunk.py"
click node_repair "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/services/repair_manager.py"
click node_connection_manager "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/core/connection_manager.py"
click node_dashboard_route "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/api/routes/dashboard.py"
click node_dashboard_ui "https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/dashboard/app.js"

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_android_ui,node_file_repo,node_text_extract,node_summarize,node_embedding,node_crypto,node_chunker,node_api_client,node_user toneBlue
class node_backend_app,node_file_routes,node_chunk_routes,node_device_routes,node_metadata,node_distribution,node_repair,node_connection_manager,node_dashboard_route toneAmber
class node_node_service,node_ws_manager,node_chunk_store,node_storage_nodes toneMint
class node_dashboard_ui toneRose
```

## Components

### Android Client

- [Client Screens](https://github.com/kevinjose102/cloud-storage-phone-cluster/tree/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/screens): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/screens`
- [File Repository](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileRepository.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileRepository.kt`
- [Text Extraction](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileTextExtractor.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileTextExtractor.kt`
- [Summary Engine](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/ml/SummaryEngine.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/ml/SummaryEngine.kt`
- [Embedding Engine](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/ml/EmbeddingEngine.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/ml/EmbeddingEngine.kt`
- [File Encryption](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/AsconFileCrypto.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/AsconFileCrypto.kt`
- [File Chunking](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileChunker.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileChunker.kt`
- [API Client](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/network/ApiClient.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/network/ApiClient.kt`

### Backend Coordination

- [FastAPI App](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/main.py): `backend/app/main.py`
- [File Routes](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/api/routes/files.py): `backend/app/api/routes/files.py`
- [Chunk Routes](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/api/routes/chunks.py): `backend/app/api/routes/chunks.py`
- [Device Routes](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/api/routes/devices.py): `backend/app/api/routes/devices.py`
- [Cluster Metadata](https://github.com/kevinjose102/cloud-storage-phone-cluster/tree/main/backend/app/models): `backend/app/models`
- [Chunk Distribution](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/services/distribute_chunk.py): `backend/app/services/distribute_chunk.py`
- [Replication Repair](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/services/repair_manager.py): `backend/app/services/repair_manager.py`
- [Connection Manager](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/core/connection_manager.py): `backend/app/core/connection_manager.py`
- [Dashboard Route](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/app/api/routes/dashboard.py): `backend/app/api/routes/dashboard.py`

### Cluster Storage

- [Node Service](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/storage/StorageNodeService.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/storage/StorageNodeService.kt`
- [Node WebSocket](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/websocket/WebSocketManager.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/websocket/WebSocketManager.kt`
- [Local Chunk Store](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/PhoneClusterApp/app/src/main/java/com/phonecluster/app/storage/ChunkStorage.kt): `PhoneClusterApp/app/src/main/java/com/phonecluster/app/storage/ChunkStorage.kt`
- **Phone Storage Nodes**

### Cluster Dashboard

- [Dashboard UI](https://github.com/kevinjose102/cloud-storage-phone-cluster/blob/main/backend/dashboard/app.js): `backend/dashboard/app.js`

### Other components

- **User**

## Connections

- User → Client Screens: selects or searches
- Client Screens → File Repository: handles files
- File Repository → Text Extraction: extracts text
- File Repository → Summary Engine: summarizes content
- Summary Engine → Embedding Engine: embeds summary
- File Repository → File Encryption: encrypts file
- File Encryption → File Chunking: chunks ciphertext
- File Repository → API Client: uploads metadata
- API Client → FastAPI App: HTTP requests
- FastAPI App → File Routes: dispatches
- FastAPI App → Chunk Routes: dispatches
- FastAPI App → Device Routes: dispatches
- File Routes → Cluster Metadata: stores file records
- Chunk Routes → Cluster Metadata: stores chunk records
- Chunk Routes → Chunk Distribution: requests distribution
- Chunk Distribution → Connection Manager: dispatches node commands
- Connection Manager → Phone Storage Nodes: sends commands
- Node Service → Node WebSocket: starts connection
- Node WebSocket → FastAPI App: opens WebSocket
- Node WebSocket → Local Chunk Store: reads and writes chunks
- Node WebSocket → Phone Storage Nodes: serves chunk transfers
- Replication Repair → Cluster Metadata: checks replicas
- Replication Repair → Chunk Distribution: redistributes chunks
- FastAPI App → Dashboard Route: dispatches
- Dashboard UI → Dashboard Route: fetches dashboard data
- Dashboard Route → Cluster Metadata: reads cluster state
- User → Dashboard UI: views status