# project-25-26/photo_app_g architecture

> Architecture diagram of the GitHub repository project-25-26/photo_app_g, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/project-25-26/photo_app_g
- Repository: https://github.com/project-25-26/photo_app_g

## Overview

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: [`photo_server/app/routers`](https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/routers) (API routers), [`photo_server/app/main.py`](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/main.py) (App entry), [`photo_app/photoapp_mobile/lib/api`](https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/api) (API client), [`photo_server/app/database.py`](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/database.py) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["photo_server"]
  node_server_main["App entry<br/>FastAPI entrypoint<br/>[main.py]"]
  node_server_routers["API routers<br/>HTTP boundary"]
  node_server_models["Domain model<br/>ORM/domain<br/>[models.py]"]
  node_server_db[("Database<br/>PostgreSQL access<br/>[database.py]")]
  node_server_config["Config<br/>[config.py]"]
  node_server_celery["Celery app<br/>worker runtime<br/>[celery_app.py]"]
  node_server_tasks["Tasks<br/>async jobs"]
  node_server_ml["ML service<br/>inference coordination<br/>[ml_service.py]"]
  node_server_ml_models["ML models<br/>vision inference"]
  node_server_face_service["Face service<br/>identity processing<br/>[face_service.py]"]
  node_server_search["Search services<br/>multi-modal search"]
  node_server_media_utils["Media utils<br/>media pipeline"]
  node_server_admin_ui["Admin UI<br/>Jinja web UI"]
  node_server_workflows["Ops scripts<br/>bootstrap/backfill"]
end

subgraph group_client["photo_app"]
  node_client_main["Flutter app<br/>mobile entrypoint<br/>[main.dart]"]
  node_client_api["API client<br/>HTTP client"]
  node_client_models["Client models<br/>DTO/domain"]
  node_client_pages["Pages<br/>UI screens"]
  node_client_services["Client services<br/>state/behavior"]
  node_client_widgets["Widgets<br/>UI components"]
  node_client_theme["Theme<br/>styling"]
  node_client_android["Android host<br/>native shell<br/>[MainActivity.kt]"]
end

node_server_main -->|"mounts"| node_server_routers
node_server_main -->|"uses"| node_server_db
node_server_main -->|"reads"| node_server_config
node_server_main -->|"starts"| node_server_celery
node_server_routers -->|"maps"| node_server_models
node_server_routers -->|"persists"| node_server_db
node_server_routers -->|"delegates"| node_server_search
node_server_routers -->|"delegates"| node_server_face_service
node_server_routers -->|"inspects"| node_server_media_utils
node_server_celery -->|"runs"| node_server_tasks
node_server_tasks -->|"calls"| node_server_ml
node_server_tasks -->|"processes"| node_server_media_utils
node_server_ml -->|"uses"| node_server_ml_models
node_server_ml -->|"feeds"| node_server_face_service
node_server_face_service -->|"updates"| node_server_models
node_server_search -->|"queries"| node_server_db
node_server_media_utils -->|"indexes"| node_server_db
node_server_admin_ui -->|"served by"| node_server_main
node_server_workflows -->|"bootstraps"| node_server_ml_models
node_server_workflows -->|"hydrates"| node_server_db
node_client_main -->|"uses"| node_client_api
node_client_main -->|"navigates"| node_client_pages
node_client_api -->|"parses"| node_client_models
node_client_pages -->|"uses"| node_client_services
node_client_pages -->|"composes"| node_client_widgets
node_client_pages -->|"fetches"| node_client_api
node_client_services -->|"authenticates"| node_client_api
node_client_widgets -->|"controls"| node_client_services
node_client_android -->|"hosts"| node_client_main
node_client_main -->|"styles"| node_client_theme
node_client_api -->|"calls"| node_server_routers

click node_server_main "https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/main.py"
click node_server_routers "https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/routers"
click node_server_models "https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/models.py"
click node_server_db "https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/database.py"
click node_server_config "https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/config.py"
click node_server_celery "https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/celery_app.py"
click node_server_tasks "https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/tasks"
click node_server_ml "https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/ml_service.py"
click node_server_ml_models "https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/ml"
click node_server_face_service "https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/face_service.py"
click node_server_search "https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/services"
click node_server_media_utils "https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/utils"
click node_server_admin_ui "https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/templates"
click node_server_workflows "https://github.com/project-25-26/photo_app_g/tree/main/photo_server"
click node_client_main "https://github.com/project-25-26/photo_app_g/blob/main/photo_app/photoapp_mobile/lib/main.dart"
click node_client_api "https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/api"
click node_client_models "https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/models"
click node_client_pages "https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/pages"
click node_client_services "https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/services"
click node_client_widgets "https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/widgets"
click node_client_theme "https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/theme"
click node_client_android "https://github.com/project-25-26/photo_app_g/blob/main/photo_app/photoapp_mobile/android/app/src/main/kotlin/com/example/photoapp_mobile/MainActivity.kt"

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_server_main,node_server_routers,node_server_models,node_server_db,node_server_config,node_server_celery,node_server_tasks,node_server_ml,node_server_ml_models,node_server_face_service,node_server_search,node_server_media_utils,node_server_admin_ui,node_server_workflows toneBlue
class node_client_main,node_client_api,node_client_models,node_client_pages,node_client_services,node_client_widgets,node_client_theme,node_client_android toneAmber
```

## Components

### photo_server

FastAPI backend, database, workers, ML, and admin UI

- [App entry](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/main.py): FastAPI entrypoint · Wires routes, middleware, config, and startup behavior · `photo_server/app/main.py`
- [API routers](https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/routers): HTTP boundary · Functional API surface for auth, media, search, people, sharing, and admin · `photo_server/app/routers`
- [Domain model](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/models.py): ORM/domain · Core persistent objects such as Face and Person · `photo_server/app/models.py`
- [Database](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/database.py): PostgreSQL access · Central database layer and persistence for media state · `photo_server/app/database.py`
- [Config](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/config.py): runtime config · Server runtime settings and environment-driven options · `photo_server/app/config.py`
- [Celery app](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/celery_app.py): worker runtime · Async task runtime for background processing · `photo_server/app/celery_app.py`
- [Tasks](https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/tasks): async jobs · Background face and video processing jobs · `photo_server/app/tasks`
- [ML service](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/ml_service.py): inference coordination · Coordinates local model execution and post-processing · `photo_server/app/ml_service.py`
- [ML models](https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/ml): vision inference · InsightFace, OpenCLIP, and BLIP implementations · `photo_server/app/ml`
- [Face service](https://github.com/project-25-26/photo_app_g/blob/main/photo_server/app/face_service.py): identity processing · Face clustering, recognition, and person association · `photo_server/app/face_service.py`
- [Search services](https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/services): multi-modal search · Hybrid text, caption, and video similarity search · `photo_server/app/services`
- [Media utils](https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/utils): media pipeline · Metadata, video inspection, hashes, and network helpers · `photo_server/app/utils`
- [Admin UI](https://github.com/project-25-26/photo_app_g/tree/main/photo_server/app/templates): Jinja web UI · Framework-light admin and user management pages · `photo_server/app/templates`
- [Ops scripts](https://github.com/project-25-26/photo_app_g/tree/main/photo_server): bootstrap/backfill · Model download, admin setup, and metadata backfill scripts · `photo_server`

### photo_app

Flutter mobile client for browsing and upload

- [Flutter app](https://github.com/project-25-26/photo_app_g/blob/main/photo_app/photoapp_mobile/lib/main.dart): mobile entrypoint · Android Flutter application shell and app startup · `photo_app/photoapp_mobile/lib/main.dart`
- [API client](https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/api): HTTP client · Client-side networking for server-backed media features · `photo_app/photoapp_mobile/lib/api`
- [Client models](https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/models): DTO/domain · Mobile data models for media, albums, users, and people · `photo_app/photoapp_mobile/lib/models`
- [Pages](https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/pages): UI screens · Primary navigation and feature screens · `photo_app/photoapp_mobile/lib/pages`
- [Client services](https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/services): state/behavior · Auth, secure-folder behavior, and playback preferences · `photo_app/photoapp_mobile/lib/services`
- [Widgets](https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/widgets): UI components · Reusable dialogs and video controls · `photo_app/photoapp_mobile/lib/widgets`
- [Theme](https://github.com/project-25-26/photo_app_g/tree/main/photo_app/photoapp_mobile/lib/theme): styling · App-wide visual styling · `photo_app/photoapp_mobile/lib/theme`
- [Android host](https://github.com/project-25-26/photo_app_g/blob/main/photo_app/photoapp_mobile/android/app/src/main/kotlin/com/example/photoapp_mobile/MainActivity.kt): native shell · Native Android entrypoint for the Flutter app · `photo_app/photoapp_mobile/android/app/src/main/kotlin/com/example/photoapp_mobile/MainActivity.kt`

## Connections

- 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
