How project-25-26/photo_app_g works
1. Top-level layout
- The repo is split into two major deployable subsystems: photo_server/ and photo_app/.
- photo_server is the backend brain: API, database access, background workers, ML pipeline, and admin web UI.
- photo_app is the Flutter Android client that connects to the server over the local network.
2. Server as the central system
- The server is a FastAPI application backed by PostgreSQL, Redis, and Celery.
- It owns all persistent media state: users, albums, photos/videos, face identities, search indexes, secure-folder metadata, and sharing permissions.
- The server also serves a framework-light HTML admin dashboard using Jinja templates, separate from the mobile client.
3. Request/API boundary
- app/routers/ is the main HTTP boundary for functional areas: auth, users, photos, albums, faces, search, shared albums, secure folder, video search, and admin.
- app/main.py is the app entrypoint that wires routers, middleware/config, and startup behavior.
- This makes the server the authoritative source for all media operations; the mobile app is a client of those APIs, not a peer datastore.
4. Data layer and domain model
- app/models.py and app/models/ define the core domain objects, including Face and Person, with the rest of the data model implied by the routers and services.
- app/database.py centralizes DB access, while app/config.py holds runtime configuration.
- PostgreSQL is used for both relational records and search-oriented metadata, including full-text search and embedding-style lookups mentioned in the README.
5. Asynchronous processing pipeline
- Slow work is pushed into Celery workers defined by app/celery_app.py and task modules in app/tasks/.
- There are at least two operational task domains: face processing and video processing.
- This separates upload/interaction latency from CPU-heavy ML inference and media transcoding.
6. Machine learning subsystem
- app/ml/ contains local inference implementations for image and face intelligence.
- Face detection/recognition uses InsightFace and ArcFace-style components; scene tagging and captioning are handled by OpenCLIP and BLIP modules.
- app/ml_service.py and app/face_service.py likely coordinate model execution and post-processing logic such as clustering faces into persons.
7. Search subsystem
- app/services/hybrid_search_service.py, caption_service.py, and video_search_service.py point to a multi-modal search architecture.
- Text search, caption-based semantic search, and video similarity search are handled as separate but related capabilities.
- The README indicates PostgreSQL full-text search plus embedding-based matching for natural-language queries and clip-based reverse video search.
8. Media-specific workflows
- app/utils/metadata.py, video.py, video_hash.py, and network.py support upload-time media inspection and indexing.
- Video processing includes transcoding, thumbnail/keyframe extraction, and perceptual hashing for similarity search.
- app/backfill_metadata.py and the caption-generation script suggest offline or migration-style jobs for populating derived media metadata.
9. Security and privacy boundaries
- Authentication is JWT-based, with auth and user-management routes on the server and a Flutter login flow on the client.
- secure_folder exists as a distinct product boundary: PIN-protected, metadata-scrubbed storage separate from the main library.
- app/utils/security.py and the secure-folder service/widget pair show that privacy rules are enforced across both backend and client UI.
10. Mobile client architecture
- photo_app/photoapp_mobile/lib/ is organized by concern: api/ for HTTP clients, models/ for DTOs/domain objects, pages/ for screens, services/ for client-side state/behavior, widgets/ for reusable UI, and theme/ for styling.
- The app is a Flutter Android application with a single native entry point in android/app/src/main/kotlin/.../MainActivity.kt.
- The client’s main role is browsing, uploading, search, album management, secure-folder access, and media playback/viewing.
11. Feature-to-UI mapping on the client
- The mobile pages map closely to backend capabilities: library, albums, shared albums, people/faces, search, favorites, trash, secure folder, media viewer, and server entry/login screens.
- home_tabs.dart and the tab pages indicate the primary navigation model is content-centric rather than settings-centric.
- video_player_controls.dart and video_preferences.dart suggest custom playback behavior on the device side, while actual media availability still comes from the server.
12. Deployment and operational tooling
- Docker is the main deployment boundary for the server stack, with docker-compose.yml and a Dockerfile driving local/self-hosted setup.
- Redis and Celery imply at-least-one worker tier in addition to the API process and PostgreSQL database.
- Utility scripts such as download_models.py, setup_admin.py, and the admin dashboards indicate first-run provisioning and model-bootstrap operations are part of the architecture.
Main entry points: routers API routers · main.py App entry · api API client · database.py Database
Components 22
photo_server
FastAPI backend, database, workers, ML, and admin UI
- App entry · Wires routes, middleware, config, and startup behavior
photo_server/app/main.py - API routers · Functional API surface for auth, media, search, people, sharing, and admin
photo_server/app/routers - Domain model · Core persistent objects such as Face and Person
photo_server/app/models.py - Database · Central database layer and persistence for media state
photo_server/app/database.py - Config · Server runtime settings and environment-driven options
photo_server/app/config.py - Celery app · Async task runtime for background processing
photo_server/app/celery_app.py - Tasks · Background face and video processing jobs
photo_server/app/tasks - ML service · Coordinates local model execution and post-processing
photo_server/app/ml_service.py - ML models · InsightFace, OpenCLIP, and BLIP implementations
photo_server/app/ml - Face service · Face clustering, recognition, and person association
photo_server/app/face_service.py - Search services · Hybrid text, caption, and video similarity search
photo_server/app/services - Media utils · Metadata, video inspection, hashes, and network helpers
photo_server/app/utils - Admin UI · Framework-light admin and user management pages
photo_server/app/templates - Ops scripts · Model download, admin setup, and metadata backfill scripts
photo_server
photo_app
Flutter mobile client for browsing and upload
- Flutter app · Android Flutter application shell and app startup
photo_app/photoapp_mobile/lib/main.dart - API client · Client-side networking for server-backed media features
photo_app/photoapp_mobile/lib/api - Client models · Mobile data models for media, albums, users, and people
photo_app/photoapp_mobile/lib/models - Pages · Primary navigation and feature screens
photo_app/photoapp_mobile/lib/pages - Client services · Auth, secure-folder behavior, and playback preferences
photo_app/photoapp_mobile/lib/services - Widgets · Reusable dialogs and video controls
photo_app/photoapp_mobile/lib/widgets - Theme · App-wide visual styling
photo_app/photoapp_mobile/lib/theme - Android host · Native Android entrypoint for the Flutter app
photo_app/photoapp_mobile/android/app/src/main/kotlin/com/example/photoapp_mobile/MainActivity.kt
Connections 31
- App entry → API routers: mounts · Registers HTTP routers and endpoints
- App entry → Database: uses · Initializes and uses database access
- App entry → Config: reads · Loads runtime settings
- App entry → Celery app: starts · Connects app startup to background worker infrastructure
- API routers → Domain model: maps · Exposes domain objects through API resources
- API routers → Database: persists · Reads and writes persistent media state
- API routers → Search services: delegates · Routes search requests to search services
- API routers → Face service: delegates · Routes face-related operations to face processing
- API routers → Media utils: inspects · Uses media metadata and upload helpers
- Celery app → Tasks: runs · Executes asynchronous job modules
- Tasks → ML service: calls · Invokes inference and post-processing
- Tasks → Media utils: processes · Handles media inspection and transformation work
- ML service → ML models: uses · Coordinates model backends for vision tasks
- ML service → Face service: feeds · Supports clustering and identity logic
- Face service → Domain model: updates · Maintains face and person records
- Search services → Database: queries · Combines relational and search-oriented lookups
- Media utils → Database: indexes · Produces derived metadata for persistence
- Admin UI → App entry: served by · Admin pages are hosted by the server app
- Ops scripts → ML models: bootstraps · Downloads or prepares model assets
- Ops scripts → Database: hydrates · Populates or backfills derived data
- Flutter app → API client: uses · App shell depends on server API clients
- Flutter app → Pages: navigates · Launches the screen hierarchy
- API client → Client models: parses · Maps server payloads into mobile models
- Pages → Client services: uses · Screens rely on client-side state and behavior
- Pages → Widgets: composes · Screens build reusable controls and dialogs
- Pages → API client: fetches · Screens call server-backed feature APIs
- Client services → API client: authenticates · Auth and secure-folder flows use HTTP services
- Widgets → Client services: controls · Widgets support playback and secure-folder interactions
- Android host → Flutter app: hosts · Native Android wrapper for Flutter entrypoint
- Flutter app → Theme: styles · Applies app-wide theme configuration
- API client → API routers: calls · Mobile client talks to server HTTP boundary