# sh3ldr0id/ameryd architecture

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

- Interactive diagram: https://gitdiagram.com/sh3ldr0id/ameryd
- Repository: https://github.com/sh3ldr0id/ameryd

## Overview

1. **What this repo is**
   - Ameryd is a single-process Flask application for browsing and administering media galleries.
   - It is intentionally **filesystem-first**: there is no database or ORM. Persistent state is split between a JSON registry and files on disk.

2. **Top-level runtime boundaries**
   - **`app.py`** is the main web server and route controller.
   - **`sync.py`** is a separate maintenance CLI for reconciling disk contents with the registry.
   - **`utils.py`** contains shared media helpers, mainly thumbnail generation and metadata extraction.
   - The rest of the repo is presentation (`templates/`, `static/`) and deployment (`Dockerfile`, `docker-compose.yml`).

3. **Persistent data model**
   - All structured metadata lives in **`data/events.json`**.
   - Media lives under **per-event folders** in `data/<event_id>/`.
   - Each event folder typically contains:
     - `Media/` for original uploads
     - `Thumbnail/` for per-file thumbnails
     - `thumbnail.webp` for the event cover
     - `metadata.json` for cached dimensions
   - There is also a global `data/Thumbnail/` fallback area.

4. **Content hierarchy and addressing**
   - The application models content as **Organizations** containing **Events**.
   - Organizations use short **4-digit IDs**; events use **6-digit IDs**.
   - The homepage acts as an **ID resolver**, directing users to the correct org or event based on the numeric code entered.
   - This keeps URLs short and shareable, which is central to the app’s navigation model.

5. **Public request flow**
   - Visitors land on **`/`**, then resolve into either an organization page or an event gallery.
   - Organization pages show the set of events that belong to that org.
   - Event pages render the actual media gallery, with pagination and lazy loading for large collections.
   - The UI supports multiple display modes and column densities, but these are client-side presentation choices rather than separate backend subsystems.

6. **Access control architecture**
   - There are two distinct protection layers:
     - **Admin authentication**: session-based login for management actions.
     - **Content protection**: optional passwords for organizations and events.
   - Event passwords are passed via a **query parameter key** for unlock access.
   - The README indicates admin sessions are invalidated if the admin password changes, so auth is tied to current server configuration rather than persistent user accounts.

7. **Administration subsystem**
   - Admin routes support creating, editing, and deleting both organizations and events.
   - Admins can upload media, delete individual files, hide events, and manage passwords.
   - There is also support for uploading custom event thumbnails.
   - This subsystem is the only part that mutates the registry and filesystem in coordinated ways.

8. **Media processing pipeline**
   - Uploads are stored as original files first, then processed into thumbnails.
   - Images are orientation-corrected using **Pillow**.
   - Video thumbnails are extracted from the first second of the clip using **OpenCV**.
   - Generated thumbnails are stored as **WebP**, and the app caches media dimensions per event to reduce repeated filesystem reads.

9. **Frontend composition**
   - Server-rendered pages are defined in `templates/`.
   - Shared layout comes from `base.html`, while specialized pages cover the homepage, org listing, event gallery, auth prompts, edit forms, and upload UI.
   - Client-side behavior lives in `static/js/`, especially for dynamic view controls, settings persistence, infinite scroll, and theme toggling.
   - Styling is handled by `static/css/style.css`, with Bootstrap/Masonry/ImagesLoaded supporting layout behavior described in the README.

10. **Maintenance and filesystem reconciliation**
   - `sync.py` is the repo’s operational safety net when files are added or removed outside the web UI.
   - Its role is to bring `events.json` and the on-disk hierarchy back into agreement, including:
     - registering new event folders
     - removing missing folders from the registry
     - generating missing thumbnails
     - cleaning orphaned thumbnail files
   - This reinforces that the filesystem is the source of truth for media, while `events.json` is the registry layer.

11. **Deployment and environment**
   - The app is designed to run in Docker, with the data directory mounted as a volume so media survives container replacement.
   - Configuration is environment-driven, notably `PORT`, `ADMIN_PASSWORD`, and `SECRET_KEY`.
   - The architecture assumes a lightweight single-server deployment rather than a distributed service or database-backed stack.

12. **How to draw the architecture**
   - The main diagram should show:
     - browser traffic into **Flask (`app.py`)**
     - Flask reading/writing **`events.json`** and the **data filesystem**
     - media uploads flowing through **`utils.py`** into thumbnails and metadata caches
     - a separate **`sync.py`** maintenance path that reconciles disk and registry
     - static templates/assets served directly to the browser for gallery interaction and admin UI
   - The key architectural boundary is between **HTTP/application logic** and **filesystem-based persistence**, with no database in between.

Main entry points: [`app.py`](https://github.com/sh3ldr0id/ameryd/blob/main/app.py) (Flask app), [`sync.py`](https://github.com/sh3ldr0id/ameryd/blob/main/sync.py) (Sync CLI), [`Dockerfile`](https://github.com/sh3ldr0id/ameryd/tree/main/Dockerfile) (Docker deploy), [`docker-compose.yml`](https://github.com/sh3ldr0id/ameryd/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_py["Flask app<br/>web server<br/>[app.py]"]
  node_sync_py["Sync CLI<br/>maintenance tool<br/>[sync.py]"]
  node_utils_py["Media utils<br/>processing helpers<br/>[utils.py]"]
  node_public_flow{{"Public pages<br/>gallery flow"}}
  node_admin_flow{{"Admin flow<br/>management flow"}}
  node_auth_layers{{"Access control<br/>security boundary"}}
  node_thumbnail_pipe{{"Thumbnailing<br/>media pipeline"}}
end

subgraph group_persistence["Persistence"]
  node_events_json["events.json<br/>registry"]
  node_data_fs[("Data tree<br/>media store")]
  node_event_media[("Event media<br/>event assets")]
  node_orgs_events{{"Org/Event IDs<br/>content model"}}
end

subgraph group_frontend["Frontend"]
  node_templates_base["Base layout<br/>template shell<br/>[base.html]"]
  node_templates_pages["Page views<br/>templates<br/>[event.html]"]
  node_static_js["Client JS<br/>browser behavior<br/>[dynamic_view.js]"]
  node_static_css["Stylesheet<br/>ui styling<br/>[style.css]"]
end

subgraph group_ops["Ops"]
  node_docker["Docker deploy<br/>deployment"]
  node_compose["Compose<br/>runtime config<br/>[docker-compose.yml]"]
  node_env_cfg{{"Env config<br/>settings"}}
end

node_browser(("Browser<br/>client"))

node_browser -->|"HTTP requests"| node_app_py
node_app_py -->|"serves"| node_public_flow
node_app_py -->|"handles"| node_admin_flow
node_public_flow -->|"resolves"| node_orgs_events
node_public_flow -->|"reads"| node_events_json
node_public_flow -->|"reads media"| node_data_fs
node_admin_flow -->|"writes"| node_events_json
node_admin_flow -->|"mutates"| node_data_fs
node_admin_flow -->|"processes uploads"| node_thumbnail_pipe
node_thumbnail_pipe -->|"uses"| node_utils_py
node_thumbnail_pipe -->|"writes"| node_event_media
node_sync_py -->|"reconciles"| node_events_json
node_sync_py -->|"scans"| node_data_fs
node_sync_py -->|"repairs"| node_thumbnail_pipe
node_app_py -->|"enforces"| node_auth_layers
node_auth_layers -->|"checks"| node_events_json
node_app_py -->|"renders"| node_templates_base
node_app_py -->|"renders"| node_templates_pages
node_app_py -->|"serves"| node_static_js
node_app_py -->|"serves"| node_static_css
node_docker -->|"configures"| node_env_cfg
node_compose -->|"runs"| node_docker
node_docker -->|"mounts"| node_data_fs

click node_app_py "https://github.com/sh3ldr0id/ameryd/blob/main/app.py"
click node_sync_py "https://github.com/sh3ldr0id/ameryd/blob/main/sync.py"
click node_utils_py "https://github.com/sh3ldr0id/ameryd/blob/main/utils.py"
click node_templates_base "https://github.com/sh3ldr0id/ameryd/blob/main/templates/base.html"
click node_templates_pages "https://github.com/sh3ldr0id/ameryd/blob/main/templates/event.html"
click node_static_js "https://github.com/sh3ldr0id/ameryd/blob/main/static/js/dynamic_view.js"
click node_static_css "https://github.com/sh3ldr0id/ameryd/blob/main/static/css/style.css"
click node_docker "https://github.com/sh3ldr0id/ameryd/tree/main/Dockerfile"
click node_compose "https://github.com/sh3ldr0id/ameryd/blob/main/docker-compose.yml"

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_app_py,node_sync_py,node_utils_py,node_public_flow,node_admin_flow,node_auth_layers,node_thumbnail_pipe toneBlue
class node_events_json,node_data_fs,node_event_media,node_orgs_events toneAmber
class node_templates_base,node_templates_pages,node_static_js,node_static_css toneMint
class node_docker,node_compose,node_env_cfg toneRose
class node_browser toneNeutral
```

## Components

### Runtime

Flask web app and maintenance CLI.

- [Flask app](https://github.com/sh3ldr0id/ameryd/blob/main/app.py): web server · Main HTTP entrypoint, route controller, auth, and admin actions. · `app.py`
- [Sync CLI](https://github.com/sh3ldr0id/ameryd/blob/main/sync.py): maintenance tool · Reconciles on-disk media with the JSON registry and repairs missing artifacts. · `sync.py`
- [Media utils](https://github.com/sh3ldr0id/ameryd/blob/main/utils.py): processing helpers · Shared thumbnail generation, image handling, and metadata extraction helpers. · `utils.py`
- **Public pages**: gallery flow · Homepage resolves IDs into organization or event views, then renders galleries with pagination and lazy loading.
- **Admin flow**: management flow · Session-authenticated create/edit/delete, uploads, hiding, password management, and thumbnail updates.
- **Access control**: security boundary · Admin login sessions plus optional org/event passwords for protected content.
- **Thumbnailing**: media pipeline · Uploads are stored, orientation-corrected, and converted into WebP thumbnails with cached dimensions.

### Persistence

Filesystem-backed registry and media storage.

- **events.json**: registry · Structured metadata registry for organizations, events, passwords, and state.
- **Data tree**: media store · Filesystem-backed content hierarchy holding per-event media, thumbnails, and cached metadata.
- **Event media**: event assets · Per-event folders containing originals, thumbnails, cover art, and metadata cache.
- **Org/Event IDs**: content model · Short numeric addressing model that maps organizations to events and powers homepage resolution.

### Frontend

Server-rendered templates and client-side gallery behavior.

- [Base layout](https://github.com/sh3ldr0id/ameryd/blob/main/templates/base.html): template shell · Shared server-rendered layout for public and admin pages. · `templates/base.html`
- [Page views](https://github.com/sh3ldr0id/ameryd/blob/main/templates/event.html): templates · Homepage, organization pages, event galleries, auth prompts, forms, and upload UI. · `templates/event.html`
- [Client JS](https://github.com/sh3ldr0id/ameryd/blob/main/static/js/dynamic_view.js): browser behavior · Dynamic view controls, settings persistence, infinite scroll, and theme toggling. · `static/js/dynamic_view.js`
- [Stylesheet](https://github.com/sh3ldr0id/ameryd/blob/main/static/css/style.css): ui styling · Shared CSS styling for the gallery and admin interface. · `static/css/style.css`

### Ops

Containerized deployment and environment configuration.

- [Docker deploy](https://github.com/sh3ldr0id/ameryd/tree/main/Dockerfile): deployment · Containerized single-server runtime with mounted data volume and environment-driven configuration. · `Dockerfile`
- [Compose](https://github.com/sh3ldr0id/ameryd/blob/main/docker-compose.yml): runtime config · Local container orchestration and service setup. · `docker-compose.yml`
- **Env config**: settings · PORT, ADMIN_PASSWORD, and SECRET_KEY configuration for runtime behavior.

### Other components

- **Browser**: client · Users interact through public gallery pages and admin screens.

## Connections

- Browser → Flask app: HTTP requests · Users access galleries, org pages, and admin screens through Flask.
- Flask app → Public pages: serves · Routes homepage resolution and public gallery rendering.
- Flask app → Admin flow: handles · Processes management actions for organizations, events, and uploads.
- Public pages → Org/Event IDs: resolves · Maps short numeric codes to the correct organization or event.
- Public pages → events.json: reads · Loads registry data for org membership, visibility, and passwords.
- Public pages → Data tree: reads media · Loads gallery assets and event files from disk.
- Admin flow → events.json: writes · Creates, edits, hides, deletes, and re-keys registry entries.
- Admin flow → Data tree: mutates · Uploads media and manages event folders and files.
- Admin flow → Thumbnailing: processes uploads · Generates thumbnails and cached metadata during admin upload flows.
- Thumbnailing → Media utils: uses · Relies on shared media helper functions.
- Thumbnailing → Event media: writes · Stores per-file thumbnails and cached event metadata.
- Sync CLI → events.json: reconciles · Updates registry entries to match the filesystem.
- Sync CLI → Data tree: scans · Inspects event folders and orphaned thumbnail areas.
- Sync CLI → Thumbnailing: repairs · Generates missing thumbnails during maintenance runs.
- Flask app → Access control: enforces · Protects admin routes and gated org/event content.
- Access control → events.json: checks · Uses stored password and visibility flags.
- Flask app → Base layout: renders · Applies shared layout to server-rendered pages.
- Flask app → Page views: renders · Serves the specialized HTML views for browsing and admin tasks.
- Flask app → Client JS: serves · Delivers client-side behavior for gallery interaction.
- Flask app → Stylesheet: serves · Delivers shared visual styling to the browser.
- Docker deploy → Env config: configures · Container runtime is driven by environment variables.
- Compose → Docker deploy: runs · Defines the containerized application setup.
- Docker deploy → Data tree: mounts · Persists media and registry data across container replacement.
