How sh3ldr0id/ameryd works
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 Flask app · sync.py Sync CLI · Dockerfile Docker deploy · docker-compose.yml Compose
Components 19
Runtime
Flask web app and maintenance CLI.
- Flask app · Main HTTP entrypoint, route controller, auth, and admin actions.
app.py - Sync CLI · Reconciles on-disk media with the JSON registry and repairs missing artifacts.
sync.py - Media utils · Shared thumbnail generation, image handling, and metadata extraction helpers.
utils.py - Public pages · Homepage resolves IDs into organization or event views, then renders galleries with pagination and lazy loading.
- Admin flow · Session-authenticated create/edit/delete, uploads, hiding, password management, and thumbnail updates.
- Access control · Admin login sessions plus optional org/event passwords for protected content.
- Thumbnailing · Uploads are stored, orientation-corrected, and converted into WebP thumbnails with cached dimensions.
Persistence
Filesystem-backed registry and media storage.
- events.json · Structured metadata registry for organizations, events, passwords, and state.
- Data tree · Filesystem-backed content hierarchy holding per-event media, thumbnails, and cached metadata.
- Event media · Per-event folders containing originals, thumbnails, cover art, and metadata cache.
- Org/Event IDs · Short numeric addressing model that maps organizations to events and powers homepage resolution.
Frontend
Server-rendered templates and client-side gallery behavior.
- Base layout · Shared server-rendered layout for public and admin pages.
templates/base.html - Page views · Homepage, organization pages, event galleries, auth prompts, forms, and upload UI.
templates/event.html - Client JS · Dynamic view controls, settings persistence, infinite scroll, and theme toggling.
static/js/dynamic_view.js - Stylesheet · Shared CSS styling for the gallery and admin interface.
static/css/style.css
Ops
Containerized deployment and environment configuration.
- Docker deploy · Containerized single-server runtime with mounted data volume and environment-driven configuration.
Dockerfile - Compose · Local container orchestration and service setup.
docker-compose.yml - Env config · PORT, ADMIN_PASSWORD, and SECRET_KEY configuration for runtime behavior.
Other components
- Browser · Users interact through public gallery pages and admin screens.
Connections 23
- 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.