# warlocks365/panomint architecture

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

- Interactive diagram: https://gitdiagram.com/warlocks365/panomint
- Repository: https://github.com/warlocks365/panomint

## Overview

Panomint is a self-hosted 360° photo and video library. Users upload or scan media into a searchable library, then browse timelines, maps, people, and albums; they can play panoramic media and create public shares. The graph preserves the documented AI, account, administration, and network-storage capabilities. README statements support most backend and product links; frontend-to-backend details are shown only where excerpts establish them. Backend internals were not sampled, so their wiring is intentionally limited.

Main entry points: [`src/frontend/src/main.js`](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/main.js) (Vue application), [`src/backend/internal/media/handlers.go`](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/media/handlers.go) (Media management), [`src/frontend/src/views/MapView.vue`](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/MapView.vue) (Map browsing), [`src/backend/internal/transcode/transcode.go`](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/transcode/transcode.go) (HLS transcoding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Vue application<br/>[main.js]"]
  node_timeline["Timeline browsing<br/>[TimelineView.vue]"]
  node_map["Map browsing<br/>[MapView.vue]"]
  node_player["Panorama playback<br/>[PlayerView.vue]"]
  node_sharing["Public sharing"]
  node_transcode["HLS transcoding<br/>[transcode.go]"]
end

subgraph group_ingest["Media ingestion"]
  node_upload["Media upload<br/>[uploadManager.js]"]
  node_scan["Directory scanning<br/>[handler.go]"]
  node_mounts["Network mounts<br/>[handler.go]"]
  node_storage_ui["Mount administration<br/>[StorageTab.vue]"]
  node_media_api["Media management<br/>[handlers.go]"]
end

subgraph group_discovery["Library discovery"]
  node_albums["Albums and groups<br/>[handlers.go]"]
  node_search["Semantic search<br/>[query.go]"]
  node_people["People clustering<br/>[cluster.go]"]
  node_geo["Geographic services<br/>[handlers.go]"]
end

subgraph group_intelligence["AI capabilities"]
  node_embeddings["Vector embeddings<br/>[embed.go]"]
  node_tagging["Automatic tagging<br/>[applier.go]"]
end

subgraph group_platform["Accounts and operations"]
  node_auth["Authentication and roles<br/>[handlers.go]"]
  node_admin["Administration<br/>[AdminView.vue]"]
  node_audit["Audit history<br/>[handlers.go]"]
  node_api["Go API service<br/>[main.go]"]
end

node_user(("Library user"))
node_postgres[("PostgreSQL and extensions")]
node_valkey["Valkey queue"]
node_ffmpeg["FFmpeg"]
node_map_tiles["Map tile provider"]

node_user -->|"browses"| node_frontend
node_frontend -->|"uploads media"| node_upload
node_frontend -->|"browses timeline"| node_timeline
node_frontend -->|"explores map"| node_map
node_frontend -->|"plays media"| node_player
node_frontend -->|"opens shares"| node_sharing
node_frontend -->|"manages mounts"| node_storage_ui
node_storage_ui -.->|"configures mounts"| node_mounts
node_storage_ui -->|"starts scans"| node_scan
node_upload -->|"posts upload"| node_api
node_scan -.->|"imports media"| node_media_api
node_mounts -.->|"provides media source"| node_media_api
node_media_api -.->|"persists library"| node_postgres
node_timeline -.->|"retrieves media"| node_media_api
node_map -.->|"requests locations"| node_geo
node_map -->|"loads tiles"| node_map_tiles
node_player -.->|"requests HLS"| node_transcode
node_transcode -->|"runs transcoding"| node_ffmpeg
node_transcode -.->|"queues jobs"| node_valkey
node_frontend -.->|"searches library"| node_search
node_search -.->|"retrieves vectors"| node_embeddings
node_embeddings -.->|"queries vectors"| node_postgres
node_media_api -.->|"applies tags"| node_tagging
node_media_api -.->|"detects faces"| node_people
node_media_api -.->|"organizes albums"| node_albums
node_sharing -.->|"serves shared media"| node_media_api
node_user -->|"signs in"| node_auth
node_admin -.->|"manages accounts"| node_auth
node_admin -.->|"reviews history"| node_audit
node_frontend -->|"sends API requests"| node_api
node_api -.->|"uses database"| node_postgres

click node_frontend "https://github.com/warlocks365/panomint/blob/main/src/frontend/src/main.js"
click node_timeline "https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/TimelineView.vue"
click node_map "https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/MapView.vue"
click node_player "https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/PlayerView.vue"
click node_sharing "https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/SharePublicView.vue"
click node_upload "https://github.com/warlocks365/panomint/blob/main/src/frontend/src/components/upload/uploadManager.js"
click node_scan "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/index/handler.go"
click node_mounts "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/storage/handler.go"
click node_storage_ui "https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/admin/StorageTab.vue"
click node_media_api "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/media/handlers.go"
click node_albums "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/albums/handlers.go"
click node_search "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/search/query.go"
click node_people "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/faces/cluster.go"
click node_geo "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/geo/handlers.go"
click node_embeddings "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/embed/embed.go"
click node_tagging "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/tags/applier.go"
click node_transcode "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/transcode/transcode.go"
click node_auth "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/auth/handlers.go"
click node_admin "https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/AdminView.vue"
click node_audit "https://github.com/warlocks365/panomint/blob/main/src/backend/internal/audit/handlers.go"
click node_api "https://github.com/warlocks365/panomint/blob/main/src/backend/cmd/api/main.go"

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,node_timeline,node_map,node_player,node_sharing,node_transcode,node_user toneBlue
class node_upload,node_scan,node_mounts,node_storage_ui,node_media_api,node_postgres toneAmber
class node_albums,node_search,node_people,node_geo toneMint
class node_embeddings,node_tagging,node_valkey toneRose
class node_auth,node_admin,node_audit,node_api,node_ffmpeg,node_map_tiles toneIndigo
```

## Components

### User experience

- [Vue application](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/main.js): `src/frontend/src/main.js`
- [Timeline browsing](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/TimelineView.vue): `src/frontend/src/views/TimelineView.vue`
- [Map browsing](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/MapView.vue): `src/frontend/src/views/MapView.vue`
- [Panorama playback](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/PlayerView.vue): `src/frontend/src/views/PlayerView.vue`
- [Public sharing](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/SharePublicView.vue): `src/frontend/src/views/SharePublicView.vue`
- [HLS transcoding](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/transcode/transcode.go): `src/backend/internal/transcode/transcode.go`

### Media ingestion

- [Media upload](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/components/upload/uploadManager.js): `src/frontend/src/components/upload/uploadManager.js`
- [Directory scanning](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/index/handler.go): `src/backend/internal/index/handler.go`
- [Network mounts](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/storage/handler.go): `src/backend/internal/storage/handler.go`
- [Mount administration](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/admin/StorageTab.vue): `src/frontend/src/views/admin/StorageTab.vue`
- [Media management](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/media/handlers.go): `src/backend/internal/media/handlers.go`

### Library discovery

- [Albums and groups](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/albums/handlers.go): `src/backend/internal/albums/handlers.go`
- [Semantic search](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/search/query.go): `src/backend/internal/search/query.go`
- [People clustering](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/faces/cluster.go): `src/backend/internal/faces/cluster.go`
- [Geographic services](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/geo/handlers.go): `src/backend/internal/geo/handlers.go`

### AI capabilities

- [Vector embeddings](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/embed/embed.go): `src/backend/internal/embed/embed.go`
- [Automatic tagging](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/tags/applier.go): `src/backend/internal/tags/applier.go`

### Accounts and operations

- [Authentication and roles](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/auth/handlers.go): `src/backend/internal/auth/handlers.go`
- [Administration](https://github.com/warlocks365/panomint/blob/main/src/frontend/src/views/AdminView.vue): `src/frontend/src/views/AdminView.vue`
- [Audit history](https://github.com/warlocks365/panomint/blob/main/src/backend/internal/audit/handlers.go): `src/backend/internal/audit/handlers.go`
- [Go API service](https://github.com/warlocks365/panomint/blob/main/src/backend/cmd/api/main.go): `src/backend/cmd/api/main.go`

### Other components

- **Library user**
- **PostgreSQL and extensions**
- **Valkey queue**
- **FFmpeg**
- **Map tile provider**

## Connections

- Library user → Vue application: browses
- Vue application → Media upload: uploads media
- Vue application → Timeline browsing: browses timeline
- Vue application → Map browsing: explores map
- Vue application → Panorama playback: plays media
- Vue application → Public sharing: opens shares
- Vue application → Mount administration: manages mounts (evidence: `src/frontend/src/views/admin/StorageTab.vue`)
- Mount administration → Network mounts: configures mounts
- Mount administration → Directory scanning: starts scans
- Media upload → Go API service: posts upload (evidence: `src/frontend/src/components/upload/uploadManager.js`)
- Directory scanning → Media management: imports media
- Network mounts → Media management: provides media source
- Media management → PostgreSQL and extensions: persists library
- Timeline browsing → Media management: retrieves media
- Map browsing → Geographic services: requests locations
- Map browsing → Map tile provider: loads tiles
- Panorama playback → HLS transcoding: requests HLS
- HLS transcoding → FFmpeg: runs transcoding
- HLS transcoding → Valkey queue: queues jobs
- Vue application → Semantic search: searches library
- Semantic search → Vector embeddings: retrieves vectors
- Vector embeddings → PostgreSQL and extensions: queries vectors
- Media management → Automatic tagging: applies tags
- Media management → People clustering: detects faces
- Media management → Albums and groups: organizes albums
- Public sharing → Media management: serves shared media
- Library user → Authentication and roles: signs in
- Administration → Authentication and roles: manages accounts
- Administration → Audit history: reviews history
- Vue application → Go API service: sends API requests
- Go API service → PostgreSQL and extensions: uses database
