How kevinjose102/cloud-storage-phone-cluster works
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: main.py FastAPI App · FileRepository.kt File Repository · WebSocketManager.kt Node WebSocket · models Cluster Metadata
Components 23
Android Client
- Client Screens
PhoneClusterApp/app/src/main/java/com/phonecluster/app/screens - File Repository
PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileRepository.kt - Text Extraction
PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileTextExtractor.kt - Summary Engine
PhoneClusterApp/app/src/main/java/com/phonecluster/app/ml/SummaryEngine.kt - Embedding Engine
PhoneClusterApp/app/src/main/java/com/phonecluster/app/ml/EmbeddingEngine.kt - File Encryption
PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/AsconFileCrypto.kt - File Chunking
PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/FileChunker.kt - API Client
PhoneClusterApp/app/src/main/java/com/phonecluster/app/network/ApiClient.kt
Backend Coordination
- FastAPI App
backend/app/main.py - File Routes
backend/app/api/routes/files.py - Chunk Routes
backend/app/api/routes/chunks.py - Device Routes
backend/app/api/routes/devices.py - Cluster Metadata
backend/app/models - Chunk Distribution
backend/app/services/distribute_chunk.py - Replication Repair
backend/app/services/repair_manager.py - Connection Manager
backend/app/core/connection_manager.py - Dashboard Route
backend/app/api/routes/dashboard.py
Cluster Storage
- Node Service
PhoneClusterApp/app/src/main/java/com/phonecluster/app/storage/StorageNodeService.kt - Node WebSocket
PhoneClusterApp/app/src/main/java/com/phonecluster/app/utils/websocket/WebSocketManager.kt - Local Chunk Store
PhoneClusterApp/app/src/main/java/com/phonecluster/app/storage/ChunkStorage.kt - Phone Storage Nodes
Cluster Dashboard
- Dashboard UI
backend/dashboard/app.js
Other components
- User
Connections 27
- 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