yuvaraj-0/ai_face_finder

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.