# yuvaraj-0/ai_face_finder architecture

> Architecture diagram of the GitHub repository yuvaraj-0/ai_face_finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yuvaraj-0/ai_face_finder
- Repository: https://github.com/yuvaraj-0/ai_face_finder

## Overview

#### Purpose and entry points
This repository is a two-part photo/event platform: a Python backend (`b`) with authentication, uploads, background processing, face/search capabilities, and a Vite React frontend (`f`). Backend startup is `b/main.py`; Celery worker startup is represented by `b/celerry/worker.py`. The browser client enters through `f/src/main.tsx` and `f/src/App.tsx`.

#### HTTP API boundary
Route modules expose the backend’s public operations for auth, events, photos, and search:
- `b/routes/auth.py`
- `b/routes/event_router.py`
- `b/routes/photo.py`
- `b/routes/search.py`

`b/main.py` composes the application, while middleware and dependency modules enforce request-level cross-cutting concerns before route/service execution:
- `b/middleware/auth_middleware.py`
- `b/middleware/rate_limit_middleware.py`
- `b/dependencies/auth.py`

#### Authentication and access lifecycle
Auth is split into route handling, service orchestration, JWT creation/validation, password handling, and token blacklisting. User and blacklist persistence models define the authorization state:
- `b/services/auth_service.py`
- `b/services/jwt_service.py`
- `b/services/blacklist_service.py`
- `b/models/user.py`
- `b/models/token_blacklist.py`

The frontend maintains client-side authentication state in `f/src/context/AuthContext.tsx`; login and registration screens are `f/src/pages/Login.tsx` and `f/src/pages/Register.tsx`.

#### Event and photo domain workflow
Events and photos are distinct domain entities, with routes delegating business logic to service layers and models defining storage shape:
- `b/models/event.py`
- `b/models/photo.py`
- `b/services/event_service.py`
- `b/services/photo_service.py`

The likely main flow is: authenticated user creates or accesses an event, uploads a photo under that event, then the photo is persisted and scheduled for further processing. The frontend upload boundary is `f/src/pages/ImageUpload.jsx`.

#### Media, asynchronous processing, and queue boundary
Cloudinary is the media-storage integration, separated behind core/service adapters:
- `b/core/cloudinary.py`
- `b/cloudinary/uploader.py`
- `b/services/cloudinary_service.py`

Celery provides asynchronous execution, with job publication separated from task definitions and worker setup:
- `b/job_queue/publisher.py`
- `b/celerry/celery_app.py`
- `b/celerry/tasks.py`

This is the key durability boundary between synchronous API upload/event requests and longer-running work such as media or face processing.

#### Search and face-recognition pipeline
Face processing and search are service-level capabilities. Qdrant is the vector-search backend; face-derived representations are expected to be indexed/queryable there:
- `b/services/face_service.py`
- `b/services/search_service.py`
- `b/services/qdrant_service.py`
- `b/core/qdrant.py`

The search route is the API boundary for retrieval, likely translating a face/image query into vector search results associated with stored photos/events.

#### Persistence, runtime, and infrastructure
Database access is abstracted in both `b/core/db.py` and `b/database/db.py`; Redis is represented by `b/core/redis.py` and likely supports Celery transport and/or rate limiting. Docker deployment artifacts are:
- `b/Dockerfile`
- `b/docker-compose.yml`

Material external services are Cloudinary for image hosting, Qdrant for vector search, Redis for queue/cache-related functions, and a database for users, events, photos, and revoked tokens. The frontend is a TypeScript/React Vite application using `f/src/api/client.ts` as its API-client boundary.

Main entry points: [`b/routes/auth.py`](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/routes/auth.py) (Public routes), [`b/core/db.py`](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/db.py) (Application database), [`b/services/photo_service.py`](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/photo_service.py) (Photo service), [`b/main.py`](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/main.py) (Backend application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_frontend_app["Vite React app<br/>browser app<br/>[main.tsx]"]
  node_frontend_auth["Auth UI state<br/>React context/pages<br/>[AuthContext.tsx]"]
  node_frontend_upload["Image upload UI<br/>React page<br/>[ImageUpload.jsx]"]
  node_api_client["API client<br/>HTTP client<br/>[client.ts]"]
end

subgraph group_api["Backend API"]
  node_backend_app["Backend application<br/>Python API runtime<br/>[main.py]"]
  node_request_guard["Request guards<br/>auth and rate-limit middleware<br/>[auth_middleware.py]"]
  node_routes["Public routes<br/>[auth.py]"]
end

subgraph group_services["Domain &amp; processing"]
  node_auth_service["Authentication service<br/>auth orchestration<br/>[auth_service.py]"]
  node_jwt_blacklist["JWT and revocation<br/>token services<br/>[jwt_service.py]"]
  node_event_service["Event service<br/>domain service<br/>[event_service.py]"]
  node_photo_service["Photo service<br/>domain service<br/>[photo_service.py]"]
  node_media_service["Cloudinary media adapter<br/>media service"]
  node_job_publisher["Job publisher<br/>async dispatch<br/>[publisher.py]"]
  node_celery_worker["Celery worker<br/>background runtime<br/>[worker.py]"]
  node_face_service["Face processing<br/>processing service<br/>[face_service.py]"]
  node_search_service["Face search service<br/>retrieval service<br/>[search_service.py]"]
end

subgraph group_infrastructure["Data &amp; infrastructure"]
  node_database[("Application database<br/>[db.py]")]
  node_cloudinary[("Cloudinary<br/>external media storage<br/>[cloudinary.py]")]
  node_redis[("Redis<br/>queue/cache backend<br/>[redis.py]")]
  node_qdrant[("Qdrant<br/>vector search backend<br/>[qdrant.py]")]
end

node_frontend_app -->|"provides auth state"| node_frontend_auth
node_frontend_app -->|"renders"| node_frontend_upload
node_frontend_auth -->|"auth requests"| node_api_client
node_frontend_upload -->|"upload requests"| node_api_client
node_api_client -->|"HTTP API"| node_backend_app
node_backend_app -->|"applies"| node_request_guard
node_request_guard -->|"authorizes requests"| node_routes
node_backend_app -->|"mounts"| node_routes
node_routes -->|"auth operations"| node_auth_service
node_routes -->|"event operations"| node_event_service
node_routes -->|"photo operations"| node_photo_service
node_routes -->|"search queries"| node_search_service
node_auth_service -->|"issues and validates tokens"| node_jwt_blacklist
node_auth_service -->|"users and revoked tokens"| node_database
node_jwt_blacklist -->|"checks revocation"| node_database
node_event_service -->|"events"| node_database
node_photo_service -->|"photos"| node_database
node_photo_service -->|"stores uploads"| node_media_service
node_media_service -->|"media objects"| node_cloudinary
node_photo_service -->|"schedules processing"| node_job_publisher
node_job_publisher -->|"publishes jobs"| node_redis
node_redis -->|"delivers jobs"| node_celery_worker
node_celery_worker -->|"runs processing tasks"| node_face_service
node_face_service -->|"indexes face vectors"| node_qdrant
node_search_service -->|"queries vectors"| node_qdrant
node_search_service -->|"resolves photo results"| node_database

click node_frontend_app "https://github.com/yuvaraj-0/ai_face_finder/blob/main/f/src/main.tsx"
click node_frontend_auth "https://github.com/yuvaraj-0/ai_face_finder/blob/main/f/src/context/AuthContext.tsx"
click node_frontend_upload "https://github.com/yuvaraj-0/ai_face_finder/blob/main/f/src/pages/ImageUpload.jsx"
click node_api_client "https://github.com/yuvaraj-0/ai_face_finder/blob/main/f/src/api/client.ts"
click node_backend_app "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/main.py"
click node_request_guard "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/middleware/auth_middleware.py"
click node_routes "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/routes/auth.py"
click node_auth_service "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/auth_service.py"
click node_jwt_blacklist "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/jwt_service.py"
click node_event_service "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/event_service.py"
click node_photo_service "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/photo_service.py"
click node_media_service "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/cloudinary_service.py"
click node_job_publisher "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/job_queue/publisher.py"
click node_celery_worker "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/celerry/worker.py"
click node_face_service "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/face_service.py"
click node_search_service "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/search_service.py"
click node_database "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/db.py"
click node_cloudinary "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/cloudinary.py"
click node_redis "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/redis.py"
click node_qdrant "https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/qdrant.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_frontend_app,node_frontend_auth,node_frontend_upload,node_api_client toneBlue
class node_backend_app,node_request_guard,node_routes toneAmber
class node_auth_service,node_jwt_blacklist,node_event_service,node_photo_service,node_media_service,node_job_publisher,node_celery_worker,node_face_service,node_search_service toneMint
class node_database,node_cloudinary,node_redis,node_qdrant toneRose
```

## Components

### React frontend

- [Vite React app](https://github.com/yuvaraj-0/ai_face_finder/blob/main/f/src/main.tsx): browser app · Browser entry point and application shell. · `f/src/main.tsx`
- [Auth UI state](https://github.com/yuvaraj-0/ai_face_finder/blob/main/f/src/context/AuthContext.tsx): React context/pages · `f/src/context/AuthContext.tsx`
- [Image upload UI](https://github.com/yuvaraj-0/ai_face_finder/blob/main/f/src/pages/ImageUpload.jsx): React page · `f/src/pages/ImageUpload.jsx`
- [API client](https://github.com/yuvaraj-0/ai_face_finder/blob/main/f/src/api/client.ts): HTTP client · `f/src/api/client.ts`

### Backend API

- [Backend application](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/main.py): Python API runtime · Composes the HTTP application and route modules. · `b/main.py`
- [Request guards](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/middleware/auth_middleware.py): auth and rate-limit middleware · `b/middleware/auth_middleware.py`
- [Public routes](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/routes/auth.py): auth, event, photo, search routes · `b/routes/auth.py`

### Domain & processing

- [Authentication service](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/auth_service.py): auth orchestration · `b/services/auth_service.py`
- [JWT and revocation](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/jwt_service.py): token services · `b/services/jwt_service.py`
- [Event service](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/event_service.py): domain service · `b/services/event_service.py`
- [Photo service](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/photo_service.py): domain service · Persists uploads and schedules downstream work. · `b/services/photo_service.py`
- [Cloudinary media adapter](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/cloudinary_service.py): media service · `b/services/cloudinary_service.py`
- [Job publisher](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/job_queue/publisher.py): async dispatch · `b/job_queue/publisher.py`
- [Celery worker](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/celerry/worker.py): background runtime · `b/celerry/worker.py`
- [Face processing](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/face_service.py): processing service · `b/services/face_service.py`
- [Face search service](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/services/search_service.py): retrieval service · `b/services/search_service.py`

### Data & infrastructure

- [Application database](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/db.py): user, event, photo, token storage · `b/core/db.py`
- [Cloudinary](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/cloudinary.py): external media storage · `b/core/cloudinary.py`
- [Redis](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/redis.py): queue/cache backend · `b/core/redis.py`
- [Qdrant](https://github.com/yuvaraj-0/ai_face_finder/blob/main/b/core/qdrant.py): vector search backend · `b/core/qdrant.py`

## Connections

- Vite React app → Auth UI state: provides auth state
- Vite React app → Image upload UI: renders
- Auth UI state → API client: auth requests
- Image upload UI → API client: upload requests
- API client → Backend application: HTTP API
- Backend application → Request guards: applies
- Request guards → Public routes: authorizes requests
- Backend application → Public routes: mounts
- Public routes → Authentication service: auth operations
- Public routes → Event service: event operations
- Public routes → Photo service: photo operations
- Public routes → Face search service: search queries
- Authentication service → JWT and revocation: issues and validates tokens
- Authentication service → Application database: users and revoked tokens
- JWT and revocation → Application database: checks revocation
- Event service → Application database: events
- Photo service → Application database: photos
- Photo service → Cloudinary media adapter: stores uploads
- Cloudinary media adapter → Cloudinary: media objects
- Photo service → Job publisher: schedules processing
- Job publisher → Redis: publishes jobs
- Redis → Celery worker: delivers jobs
- Celery worker → Face processing: runs processing tasks
- Face processing → Qdrant: indexes face vectors
- Face search service → Qdrant: queries vectors
- Face search service → Application database: resolves photo results