# airencracken/imvault architecture

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

- Interactive diagram: https://gitdiagram.com/airencracken/imvault
- Repository: https://github.com/airencracken/imvault

## Overview

Imvault is a self-hosted, server-rendered media library and clubhouse. Members browse and organize a library, while the HTTP server handles sign-in and uploads; uploads are classified, processed, and stored with associated metadata. The product also includes albums, tags, favorites, moderation, account/security features, and operator maintenance such as backup and restore. The graph preserves these documented capabilities, but some subsystem links are omitted because their implementation was not sampled; edges cite only visible wiring or README statements.

Main entry points: [`internal/web/server.go`](https://github.com/airencracken/imvault/blob/master/internal/web/server.go) (HTTP server), [`internal/web/handlers_upload.go`](https://github.com/airencracken/imvault/blob/master/internal/web/handlers_upload.go) (Upload handling), [`internal/media/media.go`](https://github.com/airencracken/imvault/blob/master/internal/media/media.go) (Media processing), [`cmd/imvault/main.go`](https://github.com/airencracken/imvault/blob/master/cmd/imvault/main.go) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_web["HTTP server<br/>[server.go]"]
  node_frontend["Browser enhancements<br/>[app.js]"]
end

subgraph group_media["Media pipeline"]
  node_upload["Upload handling<br/>[handlers_upload.go]"]
  node_media_proc["Media processing<br/>[media.go]"]
  node_video["Video processing<br/>[video.go]"]
  node_metadata["Metadata handling<br/>[details.go]"]
  node_metadata_strip["Metadata stripping<br/>[strip.go]"]
  node_exif["EXIF writing<br/>[exifwrite.go]"]
end

subgraph group_library["Library features"]
  node_library["Library browsing<br/>[handlers_files.go]"]
  node_albums_tags["Albums and tags<br/>[api_albums.go]"]
  node_favorites["Favorites"]
  node_bulk["Bulk organization<br/>[bulk_library.go]"]
  node_moderation["Moderation"]
end

subgraph group_identity["Identity and access"]
  node_auth["Web authentication<br/>[handlers_auth.go]"]
  node_oidc["OpenID Connect<br/>[oidc.go]"]
  node_twofactor["Two-factor auth"]
  node_suite["Community sign-in<br/>[auth.go]"]
  node_mail["Mail delivery<br/>[mailqueue.go]"]
end

subgraph group_operations["Storage and operations"]
  node_command["CLI commands<br/>[main.go]"]
  node_db[("SQLite database<br/>[db.go]")]
  node_store["Persistence layer<br/>[files.go]"]
  node_storage["Object storage<br/>[disk.go]"]
  node_s3["S3 backend<br/>[s3.go]"]
  node_maintenance["Backup and restore<br/>[backup.go]"]
end

node_member(("Member / visitor"))
node_operator(("Operator"))

node_member -->|"uses"| node_web
node_operator -->|"runs"| node_command
node_command -->|"opens"| node_db
node_command -->|"constructs"| node_web
node_web -->|"routes"| node_auth
node_member -->|"submits media"| node_upload
node_upload -->|"classifies"| node_media_proc
node_upload -->|"records files"| node_store
node_upload -->|"deletes objects"| node_storage
node_upload -.->|"extracts details"| node_metadata
node_media_proc -->|"handles clips"| node_video
node_media_proc -.->|"strips metadata"| node_metadata_strip
node_media_proc -.->|"writes metadata"| node_exif
node_member -->|"browses"| node_library
node_member -->|"organizes"| node_albums_tags
node_member -->|"favorites media"| node_favorites
node_member -->|"organizes in bulk"| node_bulk
node_member -->|"reports content"| node_moderation
node_frontend -->|"enhances pages"| node_web
node_web -->|"supports sign-in"| node_oidc
node_web -->|"handles second factor"| node_twofactor
node_web -.->|"offers community sign-in"| node_suite
node_web -->|"queues mail"| node_mail
node_store -.->|"persists records"| node_db
node_storage -.->|"selects optionally"| node_s3
node_operator -->|"backs up or restores"| node_maintenance
node_maintenance -.->|"migrates objects"| node_storage

click node_command "https://github.com/airencracken/imvault/blob/master/cmd/imvault/main.go"
click node_web "https://github.com/airencracken/imvault/blob/master/internal/web/server.go"
click node_auth "https://github.com/airencracken/imvault/blob/master/internal/web/handlers_auth.go"
click node_upload "https://github.com/airencracken/imvault/blob/master/internal/web/handlers_upload.go"
click node_media_proc "https://github.com/airencracken/imvault/blob/master/internal/media/media.go"
click node_video "https://github.com/airencracken/imvault/blob/master/internal/media/video.go"
click node_metadata "https://github.com/airencracken/imvault/blob/master/internal/metadata/details.go"
click node_metadata_strip "https://github.com/airencracken/imvault/blob/master/internal/metadata/strip.go"
click node_exif "https://github.com/airencracken/imvault/blob/master/internal/exifwrite/exifwrite.go"
click node_library "https://github.com/airencracken/imvault/blob/master/internal/web/handlers_files.go"
click node_albums_tags "https://github.com/airencracken/imvault/blob/master/internal/web/api_albums.go"
click node_favorites "https://github.com/airencracken/imvault/blob/master/internal/web/handlers_favorites.go"
click node_bulk "https://github.com/airencracken/imvault/blob/master/internal/web/bulk_library.go"
click node_moderation "https://github.com/airencracken/imvault/blob/master/internal/web/handlers_moderation.go"
click node_frontend "https://github.com/airencracken/imvault/blob/master/internal/web/static/js/app.js"
click node_db "https://github.com/airencracken/imvault/blob/master/internal/db/db.go"
click node_store "https://github.com/airencracken/imvault/blob/master/internal/store/files.go"
click node_storage "https://github.com/airencracken/imvault/blob/master/internal/storage/disk.go"
click node_s3 "https://github.com/airencracken/imvault/blob/master/internal/storage/s3.go"
click node_maintenance "https://github.com/airencracken/imvault/blob/master/internal/maintenance/backup.go"
click node_oidc "https://github.com/airencracken/imvault/blob/master/internal/oidc/oidc.go"
click node_twofactor "https://github.com/airencracken/imvault/blob/master/internal/web/handlers_twofactor.go"
click node_suite "https://github.com/airencracken/imvault/blob/master/internal/suite/auth.go"
click node_mail "https://github.com/airencracken/imvault/blob/master/internal/web/mailqueue.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_web,node_frontend toneBlue
class node_upload,node_media_proc,node_video,node_metadata,node_metadata_strip,node_exif toneAmber
class node_library,node_albums_tags,node_favorites,node_bulk,node_moderation toneMint
class node_auth,node_oidc,node_twofactor,node_suite,node_mail toneRose
class node_command,node_db,node_store,node_storage,node_s3,node_maintenance,node_member,node_operator toneIndigo
```

## Components

### Server runtime

- [HTTP server](https://github.com/airencracken/imvault/blob/master/internal/web/server.go): `internal/web/server.go`
- [Browser enhancements](https://github.com/airencracken/imvault/blob/master/internal/web/static/js/app.js): `internal/web/static/js/app.js`

### Media pipeline

- [Upload handling](https://github.com/airencracken/imvault/blob/master/internal/web/handlers_upload.go): `internal/web/handlers_upload.go`
- [Media processing](https://github.com/airencracken/imvault/blob/master/internal/media/media.go): `internal/media/media.go`
- [Video processing](https://github.com/airencracken/imvault/blob/master/internal/media/video.go): `internal/media/video.go`
- [Metadata handling](https://github.com/airencracken/imvault/blob/master/internal/metadata/details.go): `internal/metadata/details.go`
- [Metadata stripping](https://github.com/airencracken/imvault/blob/master/internal/metadata/strip.go): `internal/metadata/strip.go`
- [EXIF writing](https://github.com/airencracken/imvault/blob/master/internal/exifwrite/exifwrite.go): `internal/exifwrite/exifwrite.go`

### Library features

- [Library browsing](https://github.com/airencracken/imvault/blob/master/internal/web/handlers_files.go): `internal/web/handlers_files.go`
- [Albums and tags](https://github.com/airencracken/imvault/blob/master/internal/web/api_albums.go): `internal/web/api_albums.go`
- [Favorites](https://github.com/airencracken/imvault/blob/master/internal/web/handlers_favorites.go): `internal/web/handlers_favorites.go`
- [Bulk organization](https://github.com/airencracken/imvault/blob/master/internal/web/bulk_library.go): `internal/web/bulk_library.go`
- [Moderation](https://github.com/airencracken/imvault/blob/master/internal/web/handlers_moderation.go): `internal/web/handlers_moderation.go`

### Identity and access

- [Web authentication](https://github.com/airencracken/imvault/blob/master/internal/web/handlers_auth.go): `internal/web/handlers_auth.go`
- [OpenID Connect](https://github.com/airencracken/imvault/blob/master/internal/oidc/oidc.go): `internal/oidc/oidc.go`
- [Two-factor auth](https://github.com/airencracken/imvault/blob/master/internal/web/handlers_twofactor.go): `internal/web/handlers_twofactor.go`
- [Community sign-in](https://github.com/airencracken/imvault/blob/master/internal/suite/auth.go): `internal/suite/auth.go`
- [Mail delivery](https://github.com/airencracken/imvault/blob/master/internal/web/mailqueue.go): `internal/web/mailqueue.go`

### Storage and operations

- [CLI commands](https://github.com/airencracken/imvault/blob/master/cmd/imvault/main.go): `cmd/imvault/main.go`
- [SQLite database](https://github.com/airencracken/imvault/blob/master/internal/db/db.go): `internal/db/db.go`
- [Persistence layer](https://github.com/airencracken/imvault/blob/master/internal/store/files.go): `internal/store/files.go`
- [Object storage](https://github.com/airencracken/imvault/blob/master/internal/storage/disk.go): `internal/storage/disk.go`
- [S3 backend](https://github.com/airencracken/imvault/blob/master/internal/storage/s3.go): `internal/storage/s3.go`
- [Backup and restore](https://github.com/airencracken/imvault/blob/master/internal/maintenance/backup.go): `internal/maintenance/backup.go`

### Other components

- **Member / visitor**
- **Operator**

## Connections

- Member / visitor → HTTP server: uses (evidence: `README.md`)
- Operator → CLI commands: runs (evidence: `README.md`)
- CLI commands → SQLite database: opens (evidence: `cmd/imvault/main.go`)
- CLI commands → HTTP server: constructs (evidence: `cmd/imvault/main.go`)
- HTTP server → Web authentication: routes (evidence: `internal/web/server.go`)
- Member / visitor → Upload handling: submits media (evidence: `README.md`)
- Upload handling → Media processing: classifies (evidence: `internal/web/handlers_upload.go`)
- Upload handling → Persistence layer: records files (evidence: `internal/web/handlers_upload.go`)
- Upload handling → Object storage: deletes objects (evidence: `internal/web/handlers_upload.go`)
- Upload handling → Metadata handling: extracts details
- Media processing → Video processing: handles clips (evidence: `README.md`)
- Media processing → Metadata stripping: strips metadata
- Media processing → EXIF writing: writes metadata
- Member / visitor → Library browsing: browses (evidence: `README.md`)
- Member / visitor → Albums and tags: organizes (evidence: `README.md`)
- Member / visitor → Favorites: favorites media (evidence: `README.md`)
- Member / visitor → Bulk organization: organizes in bulk (evidence: `README.md`)
- Member / visitor → Moderation: reports content (evidence: `README.md`)
- Browser enhancements → HTTP server: enhances pages (evidence: `README.md`)
- HTTP server → OpenID Connect: supports sign-in (evidence: `README.md`)
- HTTP server → Two-factor auth: handles second factor (evidence: `internal/web/server.go`)
- HTTP server → Community sign-in: offers community sign-in
- HTTP server → Mail delivery: queues mail (evidence: `README.md`)
- Persistence layer → SQLite database: persists records
- Object storage → S3 backend: selects optionally (evidence: `README.md`)
- Operator → Backup and restore: backs up or restores (evidence: `README.md`)
- Backup and restore → Object storage: migrates objects