# tanuj-manikanta-2007/snapcluster architecture

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

- Interactive diagram: https://gitdiagram.com/tanuj-manikanta-2007/snapcluster
- Repository: https://github.com/tanuj-manikanta-2007/snapcluster

## Overview

SnapCluster is a Django-backed AI photo organizer. Users authenticate, create or join a room, upload media, and retrieve its images; the backend stores media in Supabase and records room, URL, and face-embedding metadata. Face utilities detect and embed faces, while separate API operations cluster faces or search by a query photo. Upload, room, and AI API components are shown as distinct domain stages. The excerpts establish key calls, but do not expose every media-processing path or frontend request, so those links are omitted where uncertain.

Main entry points: [`photos/urls.py`](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/urls.py) (URL Routing), [`photos/views/media_views.py`](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/media_views.py) (Media Upload & Retrieval), [`photos/views/ai_views.py`](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/ai_views.py) (Cluster & Search APIs), [`photos/models.py`](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/models.py) (Room & Image Records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity &amp; UI"]
  node_auth["Authentication &amp; Pages<br/>[auth_views.py]"]
  node_web["Photo Organizer UI<br/>[app.js]"]
  node_api_routes["URL Routing<br/>[urls.py]"]
end

subgraph group_rooms["Room Management"]
  node_room_api["Room Operations<br/>[room_views.py]"]
  node_room_codes["Room Code Generator<br/>[utils.py]"]
end

subgraph group_media["Media Handling"]
  node_media_api["Media Upload &amp; Retrieval<br/>[media_views.py]"]
end

subgraph group_intelligence["Face Intelligence"]
  node_ai_api["Cluster &amp; Search APIs<br/>[ai_views.py]"]
  node_face_utils["Face Detection &amp; Embeddings<br/>[face_utils.py]"]
  node_cluster["Face Clustering<br/>[face_cluster.py]"]
end

subgraph group_persistence["Persistence"]
  node_records[("Room &amp; Image Records<br/>[models.py]")]
  node_storage_client["Storage Client<br/>[supabase_client.py]"]
end

node_user(("User"))
node_supabase[("Supabase Storage")]
node_database[("Configured Database")]

node_user -->|"signs in"| node_auth
node_user -.->|"uses"| node_web
node_user -.->|"requests"| node_api_routes
node_api_routes -->|"routes to"| node_auth
node_api_routes -->|"routes to"| node_room_api
node_api_routes -->|"routes to"| node_media_api
node_api_routes -->|"routes to"| node_ai_api
node_room_api -->|"generates code"| node_room_codes
node_room_api -->|"reads/writes"| node_records
node_media_api -->|"reads/writes"| node_records
node_media_api -->|"uploads media"| node_storage_client
node_media_api -->|"extracts faces"| node_face_utils
node_ai_api -->|"reads/writes embeddings"| node_records
node_ai_api -->|"detects query faces"| node_face_utils
node_ai_api -->|"clusters embeddings"| node_cluster
node_storage_client -->|"connects"| node_supabase
node_records -.->|"persists records"| node_database

click node_auth "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/auth_views.py"
click node_web "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/static/js/app.js"
click node_api_routes "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/urls.py"
click node_room_api "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/room_views.py"
click node_room_codes "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/utils.py"
click node_media_api "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/media_views.py"
click node_ai_api "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/ai_views.py"
click node_face_utils "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/face_utils.py"
click node_cluster "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/face_cluster.py"
click node_records "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/models.py"
click node_storage_client "https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/supabase_client.py"

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,node_web,node_api_routes,node_user toneBlue
class node_room_api,node_room_codes,node_supabase,node_database toneAmber
class node_media_api toneMint
class node_ai_api,node_face_utils,node_cluster toneRose
class node_records,node_storage_client toneIndigo
```

## Components

### Identity & UI

- [Authentication & Pages](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/auth_views.py): `photos/views/auth_views.py`
- [Photo Organizer UI](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/static/js/app.js): `photos/static/js/app.js`
- [URL Routing](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/urls.py): `photos/urls.py`

### Room Management

- [Room Operations](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/room_views.py): `photos/views/room_views.py`
- [Room Code Generator](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/utils.py): `photos/utils.py`

### Media Handling

- [Media Upload & Retrieval](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/media_views.py): `photos/views/media_views.py`

### Face Intelligence

- [Cluster & Search APIs](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/views/ai_views.py): `photos/views/ai_views.py`
- [Face Detection & Embeddings](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/face_utils.py): `photos/face_utils.py`
- [Face Clustering](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/face_cluster.py): `photos/face_cluster.py`

### Persistence

- [Room & Image Records](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/models.py): `photos/models.py`
- [Storage Client](https://github.com/tanuj-manikanta-2007/snapcluster/blob/main/photos/supabase_client.py): `photos/supabase_client.py`

### Other components

- **User**
- **Supabase Storage**
- **Configured Database**

## Connections

- User → Authentication & Pages: signs in (evidence: `photos/views/auth_views.py`)
- User → Photo Organizer UI: uses
- User → URL Routing: requests
- URL Routing → Authentication & Pages: routes to (evidence: `photos/urls.py`)
- URL Routing → Room Operations: routes to (evidence: `photos/urls.py`)
- URL Routing → Media Upload & Retrieval: routes to (evidence: `photos/urls.py`)
- URL Routing → Cluster & Search APIs: routes to (evidence: `photos/urls.py`)
- Room Operations → Room Code Generator: generates code (evidence: `photos/views/room_views.py`)
- Room Operations → Room & Image Records: reads/writes (evidence: `photos/views/room_views.py`)
- Media Upload & Retrieval → Room & Image Records: reads/writes (evidence: `photos/views/media_views.py`)
- Media Upload & Retrieval → Storage Client: uploads media (evidence: `photos/views/media_views.py`)
- Media Upload & Retrieval → Face Detection & Embeddings: extracts faces (evidence: `photos/views/media_views.py`)
- Cluster & Search APIs → Room & Image Records: reads/writes embeddings (evidence: `photos/views/ai_views.py`)
- Cluster & Search APIs → Face Detection & Embeddings: detects query faces (evidence: `photos/views/ai_views.py`)
- Cluster & Search APIs → Face Clustering: clusters embeddings (evidence: `photos/views/ai_views.py`)
- Storage Client → Supabase Storage: connects (evidence: `photos/supabase_client.py`)
- Room & Image Records → Configured Database: persists records
