# kirtan1432darji/contextvault architecture

> Architecture diagram of the GitHub repository kirtan1432darji/contextvault, 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/kirtan1432darji/contextvault
- Repository: https://github.com/kirtan1432darji/contextvault

## Overview

ContextVault is a privacy-first screenshot organizer: the Android app detects screenshots, extracts and classifies their content locally, then makes it searchable and conversational through smart folders, memory views, and AI features. JSON text and metadata can sync to a FastAPI backend for account, classification, context, and chat capabilities; the README says raw image binaries remain on-device. The graph follows documented product flows and sampled service behavior. Backend routes and some client-to-backend wiring are represented at subsystem level because their implementations were not sampled.

Main entry points: [`frontend/src/database/database.ts`](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/database/database.ts) (Local SQLite), [`frontend/src/services/screenshotScannerService.ts`](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/screenshotScannerService.ts) (Screenshot scanner), [`frontend/src/services/visionAIService.ts`](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/visionAIService.ts) (On-device vision), [`frontend/src/services/contextChat/ContextRetrievalService.ts`](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/contextChat/ContextRetrievalService.ts) (Context retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile capture"]
  node_app["Mobile app<br/>[App.tsx]"]
  node_listener["Media detection"]
  node_scanner["Screenshot scanner"]
  node_sync["Sync service<br/>[syncService.ts]"]
end

subgraph group_local["Local intelligence"]
  node_ocr["On-device vision<br/>[visionAIService.ts]"]
  node_classifier["Smart classification"]
  node_folders["Smart folders"]
  node_search["Global AI search"]
  node_chat["Folder context chat"]
  node_retrieval["Context retrieval"]
  node_memory["Memory timeline"]
end

subgraph group_backend["Backend services"]
  node_api["FastAPI routes"]
  node_classification["Backend classification<br/>[classification.py]"]
  node_context["Folder context engine"]
  node_backendchat["Backend chat engine"]
end

subgraph group_storage["Persistence"]
  node_clientdb[("Local SQLite<br/>[database.ts]")]
  node_backenddb[("Backend database<br/>[database.py]")]
end

subgraph group_web["Web access"]
  node_webclient["Web client<br/>[App.tsx]"]
  node_webapi["Web API client<br/>[vaultApi.ts]"]
end

node_user(("Screenshot user"))
node_android(("Android media source"))

node_user -->|"uses"| node_app
node_android -->|"signals media"| node_listener
node_listener -->|"detects screenshots"| node_scanner
node_scanner -->|"processes locally"| node_ocr
node_ocr -->|"provides extracted text"| node_classifier
node_classifier -->|"assigns categories"| node_folders
node_scanner -->|"stores screenshot metadata"| node_clientdb
node_ocr -->|"caches vision results"| node_clientdb
node_folders -->|"stores folder data"| node_clientdb
node_search -->|"searches local index"| node_clientdb
node_chat -->|"retrieves grounding"| node_retrieval
node_retrieval -->|"reads timeline"| node_memory
node_retrieval -->|"reads local context"| node_clientdb
node_sync -->|"syncs text metadata"| node_api
node_api -->|"dispatches classification"| node_classification
node_api -->|"dispatches context"| node_context
node_api -->|"dispatches chat"| node_backendchat
node_classification -->|"reads and writes"| node_backenddb
node_context -->|"reads and writes"| node_backenddb
node_backendchat -->|"uses folder context"| node_context
node_backendchat -->|"persists chat history"| node_backenddb
node_user -->|"uses"| node_webclient
node_webclient -->|"requests vault data"| node_webapi
node_webapi -->|"calls REST API"| node_api

click node_app "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/App.tsx"
click node_listener "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/ScreenshotListenerService.ts"
click node_scanner "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/screenshotScannerService.ts"
click node_ocr "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/visionAIService.ts"
click node_classifier "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/SmartFolderClassificationService.ts"
click node_folders "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/SmartFolderService.ts"
click node_search "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/search/SemanticSearchService.ts"
click node_chat "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/contextChat/ContextChatService.ts"
click node_retrieval "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/contextChat/ContextRetrievalService.ts"
click node_memory "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/memory/MemoryTimelineService.ts"
click node_sync "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/syncService.ts"
click node_clientdb "https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/database/database.ts"
click node_classification "https://github.com/kirtan1432darji/contextvault/blob/main/backend/app/api/v1/classification.py"
click node_context "https://github.com/kirtan1432darji/contextvault/blob/main/backend/app/services/context_engine_service.py"
click node_backendchat "https://github.com/kirtan1432darji/contextvault/blob/main/backend/app/services/chat_engine_service.py"
click node_backenddb "https://github.com/kirtan1432darji/contextvault/blob/main/backend/app/database/database.py"
click node_webclient "https://github.com/kirtan1432darji/contextvault/blob/main/web-client/src/App.tsx"
click node_webapi "https://github.com/kirtan1432darji/contextvault/blob/main/web-client/src/api/vaultApi.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_app,node_listener,node_scanner,node_sync,node_user toneBlue
class node_ocr,node_classifier,node_folders,node_search,node_chat,node_retrieval,node_memory toneAmber
class node_api,node_classification,node_context,node_backendchat toneMint
class node_clientdb,node_backenddb toneRose
class node_webclient,node_webapi,node_android toneIndigo
```

## Components

### Mobile capture

- [Mobile app](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/App.tsx): `frontend/App.tsx`
- [Media detection](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/ScreenshotListenerService.ts): `frontend/src/services/ScreenshotListenerService.ts`
- [Screenshot scanner](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/screenshotScannerService.ts): `frontend/src/services/screenshotScannerService.ts`
- [Sync service](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/syncService.ts): `frontend/src/services/syncService.ts`

### Local intelligence

- [On-device vision](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/visionAIService.ts): `frontend/src/services/visionAIService.ts`
- [Smart classification](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/SmartFolderClassificationService.ts): `frontend/src/services/SmartFolderClassificationService.ts`
- [Smart folders](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/SmartFolderService.ts): `frontend/src/services/SmartFolderService.ts`
- [Global AI search](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/search/SemanticSearchService.ts): `frontend/src/services/search/SemanticSearchService.ts`
- [Folder context chat](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/contextChat/ContextChatService.ts): `frontend/src/services/contextChat/ContextChatService.ts`
- [Context retrieval](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/contextChat/ContextRetrievalService.ts): `frontend/src/services/contextChat/ContextRetrievalService.ts`
- [Memory timeline](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/services/memory/MemoryTimelineService.ts): `frontend/src/services/memory/MemoryTimelineService.ts`

### Backend services

- **FastAPI routes**
- [Backend classification](https://github.com/kirtan1432darji/contextvault/blob/main/backend/app/api/v1/classification.py): `backend/app/api/v1/classification.py`
- [Folder context engine](https://github.com/kirtan1432darji/contextvault/blob/main/backend/app/services/context_engine_service.py): `backend/app/services/context_engine_service.py`
- [Backend chat engine](https://github.com/kirtan1432darji/contextvault/blob/main/backend/app/services/chat_engine_service.py): `backend/app/services/chat_engine_service.py`

### Persistence

- [Local SQLite](https://github.com/kirtan1432darji/contextvault/blob/main/frontend/src/database/database.ts): `frontend/src/database/database.ts`
- [Backend database](https://github.com/kirtan1432darji/contextvault/blob/main/backend/app/database/database.py): `backend/app/database/database.py`

### Web access

- [Web client](https://github.com/kirtan1432darji/contextvault/blob/main/web-client/src/App.tsx): `web-client/src/App.tsx`
- [Web API client](https://github.com/kirtan1432darji/contextvault/blob/main/web-client/src/api/vaultApi.ts): `web-client/src/api/vaultApi.ts`

### Other components

- **Screenshot user**
- **Android media source**

## Connections

- Screenshot user → Mobile app: uses
- Android media source → Media detection: signals media
- Media detection → Screenshot scanner: detects screenshots
- Screenshot scanner → On-device vision: processes locally
- On-device vision → Smart classification: provides extracted text
- Smart classification → Smart folders: assigns categories
- Screenshot scanner → Local SQLite: stores screenshot metadata
- On-device vision → Local SQLite: caches vision results
- Smart folders → Local SQLite: stores folder data
- Global AI search → Local SQLite: searches local index
- Folder context chat → Context retrieval: retrieves grounding
- Context retrieval → Memory timeline: reads timeline
- Context retrieval → Local SQLite: reads local context
- Sync service → FastAPI routes: syncs text metadata
- FastAPI routes → Backend classification: dispatches classification
- FastAPI routes → Folder context engine: dispatches context
- FastAPI routes → Backend chat engine: dispatches chat
- Backend classification → Backend database: reads and writes
- Folder context engine → Backend database: reads and writes
- Backend chat engine → Folder context engine: uses folder context
- Backend chat engine → Backend database: persists chat history
- Screenshot user → Web client: uses
- Web client → Web API client: requests vault data
- Web API client → FastAPI routes: calls REST API