# arceusomkar7/clustr architecture

> Architecture diagram of the GitHub repository arceusomkar7/clustr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arceusomkar7/clustr
- Repository: https://github.com/arceusomkar7/clustr

## Overview

##### Project type and purpose
- This is a full-stack web application (CLUSTR MVP) that lets users upload photos, automatically captions them, detects and clusters faces, and organizes albums by scene and people.
- Frontend: React + TypeScript + Tailwind (Vite).
- Backend: Python (FastAPI), local file storage, SQLite/JSON metadata.
- ML services: BLIP captioning, MTCNN + FaceNet for face embeddings, DBSCAN for clustering.

##### File structure
- Top level:
- backend/ – Python API server, ML & DB logic.
- frontend/ – React UI.
- backend/app/:
- routers/ – upload and base endpoints.
- services/ – upload_service, mongodb_service.
- ml/ – caption_service.
- db/ – mongodb.py wrapper (or SQLite stub).
- models/ – Pydantic models.
- utils/ – image preprocessing.
- frontend/src/:
- pages/ – Home, Gallery, Profile.
- components/ – UploadComponent, GalleryItem, ImageDetailModal, theme.
- services/ – api.ts, uploadService, galleryService.
- hooks/ – useGallery, useImageUpload.
- assets & ui primitives.
- Config & deployment:
- Dockerfile, .env-example in backend.
- vite.config.ts, tsconfig, package.json in frontend.

##### Key README insights
- Four phases:
1. Upload pipeline
2. Captioning (BLIP)
3. Face detection & clustering (MTCNN, FaceNet, DBSCAN)
4. Album generation by scene & people
- Tech summary: FastAPI/Flask, local storage, SQLite/JSON, HuggingFace BLIP, MTCNN + FaceNet, DBSCAN.

a. Main components
- User’s browser (React UI)
- Frontend app (static assets served by Vite / CDN)
- Backend API (FastAPI)
- File storage (local disk or cloud bucket)
- Metadata database (SQLite or MongoDB)
- ML modules (Captioning, Face Detection & Embedding, Clustering)
- (Optional) Message broker / task queue if asynchronous
b. Relationships & interactions
1. User → UploadComponent → POST /upload → Backend API
2. Backend receives file, saves to storage, writes metadata record
3. Backend synchronously (or via task queue) calls:
– caption_service.generate_caption(image) → returns text → update DB
– mtcnn.detect_faces(image) & facenet.embed(crops) → embeddings → DB
– clustering_service.cluster_all_embeddings() → person IDs → DB
4. Frontend polls or GETs /gallery endpoint → Backend reads DB, returns list of images + captions + person clusters
5. UI renders grid, modals, filters by scene keywords or person ID
c. Architectural patterns
- MVC-style separation: routers (controllers) → services (business logic) → models (data)
- Pipeline pattern for ML processing
- Client-Server REST API
- (Future) microservices for each ML component or async task queue
d. Relevant technologies
- React + Vite + Tailwind
- FastAPI
- Python ML libs: transformers (BLIP), facenet-pytorch (MTCNN, FaceNet), scikit-learn (DBSCAN)
- Pydantic models
- SQLite / MongoDB
- Docker for containerization

##### Detail
- Data schemas or key fields (image_id, caption_text, person_ids) if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "Frontend" 
        direction TB
        Browser["User Browser"]:::user
        ReactApp["React App"]:::frontend
        MainTSX["main.tsx"]:::frontend
        AppTSX["App.tsx"]:::frontend
        HomePage["Home.tsx"]:::frontend
        GalleryPage["Gallery.tsx"]:::frontend
        ProfilePage["Profile.tsx"]:::frontend
        UploadComp["UploadComponent.tsx"]:::frontend
        GalleryItem["GalleryItem.tsx"]:::frontend
        ImageDetailModal["ImageDetailModal.tsx"]:::frontend
        APIWrapper["api.ts"]:::frontend
        UploadServiceFE["uploadService.ts"]:::frontend
        GalleryServiceFE["galleryService.ts"]:::frontend
        UseUploadHook["useImageUpload.ts"]:::frontend
        UseGalleryHook["useGallery.ts"]:::frontend
    end

    subgraph "Backend" 
        direction TB
        RunCLI["run.py"]:::backend
        FastAPIApp["main.py"]:::backend
        Config["config.py"]:::backend
        UploadRouter["upload.py"]:::backend
        BaseRouter["base.py"]:::backend
        UploadServiceBE["upload_service.py"]:::backend
        DBService["mongodb_service.py"]:::backend
        DBWrapper["mongodb.py"]:::backend
        CaptionService["caption_service.py"]:::ml
        FaceDetectService["Face Detection & Embedding"]:::ml
        ClusteringService["Clustering Service"]:::ml
        ImageUtils["image_utils.py"]:::backend
        Helpers["helpers.py"]:::backend
        Dockerfile["Dockerfile/.env-example"]:::backend
    end

    subgraph "Persistence & Storage"
        direction TB
        FileStorage["File Storage"]:::storage
        MetadataDB["Metadata DB (SQLite/MongoDB)"]:::storage
    end

    %% Flows
    Browser -->|interacts| ReactApp
    ReactApp --> MainTSX
    MainTSX --> AppTSX
    AppTSX --> HomePage
    AppTSX --> GalleryPage
    AppTSX --> ProfilePage
    HomePage --> UploadComp
    GalleryPage --> GalleryItem
    GalleryPage --> ImageDetailModal

    UploadComp -->|uses| UploadServiceFE
    UploadServiceFE -->|POST /upload| APIWrapper
    GalleryPage -->|uses| GalleryServiceFE
    GalleryServiceFE -->|GET /gallery| APIWrapper
    UploadServiceFE --- UseUploadHook
    GalleryServiceFE --- UseGalleryHook

    APIWrapper -->|calls| FastAPIApp
    RunCLI --> FastAPIApp
    FastAPIApp --> Config
    FastAPIApp --> UploadRouter
    FastAPIApp --> BaseRouter

    UploadRouter -->|uses| UploadServiceBE
    UploadServiceBE --> FileStorage
    UploadServiceBE --> DBService
    DBService --> DBWrapper
    DBWrapper --> MetadataDB

    UploadServiceBE -->|sync calls| CaptionService
    UploadServiceBE -->|sync calls| FaceDetectService
    UploadServiceBE -->|sync calls| ClusteringService

    CaptionService --> MetadataDB
    FaceDetectService --> MetadataDB
    ClusteringService --> MetadataDB

    UploadServiceBE --> ImageUtils
    UploadServiceBE --> Helpers

    FastAPIApp --> Dockerfile

    %% Styles
    classDef user fill:#D6E9FE,stroke:#4A90E2,color:#1A202C;
    classDef frontend fill:#E0F2FE,stroke:#0284C7,color:#1A202C;
    classDef backend fill:#ECFDF5,stroke:#10B981,color:#1A202C;
    classDef ml fill:#F5F3FF,stroke:#8B5CF6,color:#1A202C,stroke-dasharray: 5 5;
    classDef storage fill:#FEF3C7,stroke:#F59E0B,color:#1A202C,stroke-dasharray: 2 2;

    %% Click Events
    click MainTSX "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/main.tsx"
    click AppTSX "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/App.tsx"
    click HomePage "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/pages/Home.tsx"
    click GalleryPage "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/pages/Gallery.tsx"
    click ProfilePage "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/pages/Profile.tsx"
    click UploadComp "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/components/UploadComponent.tsx"
    click GalleryItem "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/components/GalleryItem.tsx"
    click ImageDetailModal "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/components/ImageDetailModal.tsx"
    click APIWrapper "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/services/api.ts"
    click UploadServiceFE "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/services/uploadService.ts"
    click GalleryServiceFE "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/services/galleryService.ts"
    click UseUploadHook "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/hooks/useImageUpload.ts"
    click UseGalleryHook "https://github.com/arceusomkar7/clustr/blob/main/frontend/src/hooks/useGallery.ts"
    click FastAPIApp "https://github.com/arceusomkar7/clustr/blob/main/backend/app/main.py"
    click RunCLI "https://github.com/arceusomkar7/clustr/blob/main/backend/run.py"
    click UploadRouter "https://github.com/arceusomkar7/clustr/blob/main/backend/app/routers/upload.py"
    click BaseRouter "https://github.com/arceusomkar7/clustr/blob/main/backend/app/routers/base.py"
    click UploadServiceBE "https://github.com/arceusomkar7/clustr/blob/main/backend/app/services/upload_service.py"
    click DBService "https://github.com/arceusomkar7/clustr/blob/main/backend/app/services/mongodb_service.py"
    click DBWrapper "https://github.com/arceusomkar7/clustr/blob/main/backend/app/db/mongodb.py"
    click CaptionService "https://github.com/arceusomkar7/clustr/blob/main/backend/app/ml/caption_service.py"
    click ImageUtils "https://github.com/arceusomkar7/clustr/blob/main/backend/app/utils/image_utils.py"
    click Helpers "https://github.com/arceusomkar7/clustr/blob/main/backend/app/utils/helpers.py"
    click Config "https://github.com/arceusomkar7/clustr/blob/main/backend/app/config.py"
    click Dockerfile "https://github.com/arceusomkar7/clustr/tree/main/backend/Dockerfile"
```
