# aossie-org/pictopy architecture

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

- Interactive diagram: https://gitdiagram.com/aossie-org/pictopy
- Repository: https://github.com/aossie-org/pictopy

## Overview

PictoPy is a privacy-first desktop photo manager: users add local folders, the backend indexes media and can analyze it with on-device AI, then the desktop supports browsing, searching, albums, and memories. A separate watcher synchronizes filesystem changes; sharing and XMP metadata export are additional capabilities. The README documents the product-level capabilities, while the excerpts and source index show selected backend, sharing, XMP, and watcher relationships. Several frontend-to-backend and unsampled subsystem links are therefore shown only as unverified.

Main entry points: [`backend/app/utils/images.py`](https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/images.py) (Media indexing and processing), [`backend/app/routes/folders.py`](https://github.com/aossie-org/pictopy/blob/dev/backend/app/routes/folders.py) (Folder indexing routes), [`frontend/src/App.tsx`](https://github.com/aossie-org/pictopy/blob/dev/frontend/src/App.tsx) (Desktop application), [`sync-microservice/app/utils/watcher.py`](https://github.com/aossie-org/pictopy/blob/dev/sync-microservice/app/utils/watcher.py) (Filesystem watcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop_app["Desktop application<br/>[App.tsx]"]
  node_gallery["Gallery and search<br/>[Home.tsx]"]
  node_album_ui["Albums and memories<br/>[Album.tsx]"]
  node_model_ui["Model manager<br/>[ModelManager.tsx]"]
  node_client_api["API client<br/>[index.ts]"]
  node_tauri["Tauri shell<br/>[main.rs]"]
end

subgraph group_backend["Backend workflows"]
  node_api["Backend API<br/>[main.py]"]
  node_folder_routes["Folder indexing routes<br/>[folders.py]"]
  node_image_processing["Media indexing and processing<br/>[images.py]"]
  node_video_processing["Video processing<br/>[videos.py]"]
end

subgraph group_ai["AI analysis"]
  node_face_search["Face recognition and search<br/>[faceSearch.py]"]
  node_semantic_search["Semantic tagging and search<br/>[semantic_labels.py]"]
  node_model_runtime["On-device model runtime"]
end

subgraph group_storage["Library data"]
  node_folder_store[("Folder records<br/>[folders.py]")]
  node_image_store[("Image records<br/>[images.py]")]
  node_video_store[("Video records<br/>[videos.py]")]
  node_memory_store[("Memories<br/>[memories.py]")]
end

subgraph group_integrations["Sync and sharing"]
  node_sync_service["Filesystem watcher<br/>[watcher.py]"]
  node_xmp["XMP metadata export<br/>[exporter.py]"]
  node_share_server["Share listener<br/>[server.py]"]
  node_share_routes["Share routes and media<br/>[routes.py]"]
end

node_user(("Photo manager user"))
node_local_media["Local media files"]

node_user -->|"uses"| node_desktop_app
node_desktop_app -->|"navigates to"| node_gallery
node_desktop_app -.->|"requests data"| node_client_api
node_client_api -.->|"calls API"| node_api
node_user -->|"selects folders"| node_local_media
node_folder_routes -->|"reads and writes"| node_folder_store
node_folder_routes -->|"dispatches indexing"| node_image_processing
node_image_processing -.->|"reads media"| node_local_media
node_image_processing -.->|"stores image data"| node_image_store
node_video_processing -.->|"stores video data"| node_video_store
node_image_processing -.->|"analyzes faces"| node_face_search
node_image_processing -.->|"tags images"| node_semantic_search
node_face_search -.->|"uses models"| node_model_runtime
node_semantic_search -.->|"uses models"| node_model_runtime
node_gallery -.->|"opens albums"| node_album_ui
node_album_ui -.->|"loads memories"| node_memory_store
node_model_ui -.->|"manages models"| node_api
node_tauri -.->|"hosts UI"| node_desktop_app
node_sync_service -->|"reads watched folders"| node_folder_store
node_sync_service -.->|"notifies changes"| node_folder_routes
node_folder_routes -->|"exports metadata"| node_xmp
node_share_server -->|"serves routes"| node_share_routes
node_share_routes -->|"serves shared media"| node_user
node_user -.->|"creates shares"| node_share_server

click node_desktop_app "https://github.com/aossie-org/pictopy/blob/dev/frontend/src/App.tsx"
click node_gallery "https://github.com/aossie-org/pictopy/blob/dev/frontend/src/pages/Home/Home.tsx"
click node_album_ui "https://github.com/aossie-org/pictopy/blob/dev/frontend/src/pages/Album/Album.tsx"
click node_model_ui "https://github.com/aossie-org/pictopy/blob/dev/frontend/src/pages/ModelManager/ModelManager.tsx"
click node_client_api "https://github.com/aossie-org/pictopy/blob/dev/frontend/src/api/api-functions/index.ts"
click node_tauri "https://github.com/aossie-org/pictopy/blob/dev/frontend/src-tauri/src/main.rs"
click node_api "https://github.com/aossie-org/pictopy/blob/dev/backend/main.py"
click node_folder_routes "https://github.com/aossie-org/pictopy/blob/dev/backend/app/routes/folders.py"
click node_image_processing "https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/images.py"
click node_video_processing "https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/videos.py"
click node_face_search "https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/faceSearch.py"
click node_semantic_search "https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/semantic_labels.py"
click node_model_runtime "https://github.com/aossie-org/pictopy/tree/dev/backend/app/models"
click node_folder_store "https://github.com/aossie-org/pictopy/blob/dev/backend/app/database/folders.py"
click node_image_store "https://github.com/aossie-org/pictopy/blob/dev/backend/app/database/images.py"
click node_video_store "https://github.com/aossie-org/pictopy/blob/dev/backend/app/database/videos.py"
click node_memory_store "https://github.com/aossie-org/pictopy/blob/dev/backend/app/database/memories.py"
click node_sync_service "https://github.com/aossie-org/pictopy/blob/dev/sync-microservice/app/utils/watcher.py"
click node_xmp "https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/xmp/exporter.py"
click node_share_server "https://github.com/aossie-org/pictopy/blob/dev/backend/app/share/server.py"
click node_share_routes "https://github.com/aossie-org/pictopy/blob/dev/backend/app/share/routes.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_desktop_app,node_gallery,node_album_ui,node_model_ui,node_client_api,node_tauri,node_user toneBlue
class node_api,node_folder_routes,node_image_processing,node_video_processing toneAmber
class node_face_search,node_semantic_search,node_model_runtime toneMint
class node_folder_store,node_image_store,node_video_store,node_memory_store toneRose
class node_sync_service,node_xmp,node_share_server,node_share_routes,node_local_media toneIndigo
```

## Components

### Desktop experience

- [Desktop application](https://github.com/aossie-org/pictopy/blob/dev/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Gallery and search](https://github.com/aossie-org/pictopy/blob/dev/frontend/src/pages/Home/Home.tsx): `frontend/src/pages/Home/Home.tsx`
- [Albums and memories](https://github.com/aossie-org/pictopy/blob/dev/frontend/src/pages/Album/Album.tsx): `frontend/src/pages/Album/Album.tsx`
- [Model manager](https://github.com/aossie-org/pictopy/blob/dev/frontend/src/pages/ModelManager/ModelManager.tsx): `frontend/src/pages/ModelManager/ModelManager.tsx`
- [API client](https://github.com/aossie-org/pictopy/blob/dev/frontend/src/api/api-functions/index.ts): `frontend/src/api/api-functions/index.ts`
- [Tauri shell](https://github.com/aossie-org/pictopy/blob/dev/frontend/src-tauri/src/main.rs): `frontend/src-tauri/src/main.rs`

### Backend workflows

- [Backend API](https://github.com/aossie-org/pictopy/blob/dev/backend/main.py): `backend/main.py`
- [Folder indexing routes](https://github.com/aossie-org/pictopy/blob/dev/backend/app/routes/folders.py): `backend/app/routes/folders.py`
- [Media indexing and processing](https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/images.py): `backend/app/utils/images.py`
- [Video processing](https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/videos.py): `backend/app/utils/videos.py`

### AI analysis

- [Face recognition and search](https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/faceSearch.py): `backend/app/utils/faceSearch.py`
- [Semantic tagging and search](https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/semantic_labels.py): `backend/app/utils/semantic_labels.py`
- [On-device model runtime](https://github.com/aossie-org/pictopy/tree/dev/backend/app/models): `backend/app/models`

### Library data

- [Folder records](https://github.com/aossie-org/pictopy/blob/dev/backend/app/database/folders.py): `backend/app/database/folders.py`
- [Image records](https://github.com/aossie-org/pictopy/blob/dev/backend/app/database/images.py): `backend/app/database/images.py`
- [Video records](https://github.com/aossie-org/pictopy/blob/dev/backend/app/database/videos.py): `backend/app/database/videos.py`
- [Memories](https://github.com/aossie-org/pictopy/blob/dev/backend/app/database/memories.py): `backend/app/database/memories.py`

### Sync and sharing

- [Filesystem watcher](https://github.com/aossie-org/pictopy/blob/dev/sync-microservice/app/utils/watcher.py): `sync-microservice/app/utils/watcher.py`
- [XMP metadata export](https://github.com/aossie-org/pictopy/blob/dev/backend/app/utils/xmp/exporter.py): `backend/app/utils/xmp/exporter.py`
- [Share listener](https://github.com/aossie-org/pictopy/blob/dev/backend/app/share/server.py): `backend/app/share/server.py`
- [Share routes and media](https://github.com/aossie-org/pictopy/blob/dev/backend/app/share/routes.py): `backend/app/share/routes.py`

### Other components

- **Photo manager user**
- **Local media files**

## Connections

- Photo manager user → Desktop application: uses (evidence: `README.md`)
- Desktop application → Gallery and search: navigates to (evidence: `frontend/src/App.tsx`)
- Desktop application → API client: requests data
- API client → Backend API: calls API
- Photo manager user → Local media files: selects folders (evidence: `README.md`)
- Folder indexing routes → Folder records: reads and writes (evidence: `backend/app/routes/folders.py`)
- Folder indexing routes → Media indexing and processing: dispatches indexing (evidence: `backend/app/routes/folders.py`)
- Media indexing and processing → Local media files: reads media
- Media indexing and processing → Image records: stores image data (evidence: `backend/app/database/images.py`)
- Video processing → Video records: stores video data
- Media indexing and processing → Face recognition and search: analyzes faces (evidence: `backend/app/utils/faceSearch.py`)
- Media indexing and processing → Semantic tagging and search: tags images
- Face recognition and search → On-device model runtime: uses models (evidence: `backend/app/utils/faceSearch.py`)
- Semantic tagging and search → On-device model runtime: uses models
- Gallery and search → Albums and memories: opens albums
- Albums and memories → Memories: loads memories
- Model manager → Backend API: manages models
- Tauri shell → Desktop application: hosts UI
- Filesystem watcher → Folder records: reads watched folders (evidence: `sync-microservice/app/utils/watcher.py`)
- Filesystem watcher → Folder indexing routes: notifies changes
- Folder indexing routes → XMP metadata export: exports metadata (evidence: `backend/app/routes/folders.py`)
- Share listener → Share routes and media: serves routes (evidence: `backend/app/share/server.py`)
- Share routes and media → Photo manager user: serves shared media (evidence: `backend/app/share/routes.py`)
- Photo manager user → Share listener: creates shares