foldergram - Moses Yebei

The Problem

Self-hosting a photo gallery usually means either a heavy platform like Nextcloud or PhotoPrism, or a static file browser that ignores metadata and presentation. Foldergram targets the middle: a lightweight, local-first gallery that maps real folders to Instagram-style profiles and feeds, without sending media to a third party.

What This Does

Foldergram is a self-hosted web app with a Vue 3 client (client/src/) and a Node/TypeScript server (server/src/). It indexes media from a configured GALLERY_ROOT, stores metadata in SQLite (server/src/db/repositories.ts), and generates thumbnails/previews via server/src/services/derivative-service.ts. The UI mirrors Instagram: home feed, reels, explore, places, and folder "profiles."

The server exposes REST routes (server/src/routes/api.ts) and a lazy-derivative endpoint (server/src/routes/lazy-derivatives.ts). Client state lives in Pinia stores (client/src/stores/), and API calls are centralized in client/src/api/gallery.ts. The app is PWA-capable with a service worker (client/public/sw.js).

How It Is Wired

Execution starts at bootstrap in client/src/main.ts, which reaches 88 functions. The client calls fetchFeed, fetchReels, etc., through client/src/api/gallery.ts. On the server, start in server/src/db/repositories.ts (line 2412) reaches 48 functions and is the entry point for the database layer.

The call graph shows heavy hub modules: client/src/types/api.ts is imported by 46 modules, and server/src/utils/image-utils.ts by 28. Changing either ripples widely. The server's scanner-service.ts (77 functions) and gallery-service.ts (113 functions) are oversized and carry most business logic.

Database writes happen through prepare (called from 126 places), filesystem access via fsPromises.mkdir, and the shortest traced path from bootstrap to a DB write is bootstrap -> ensureDefaultCollection — two hops. The wiring is straightforward: HTTP request → route handler → service → repository → SQLite.

How To Use It

# Clone and install
git clone https://github.com/moses-y/foldergram
cd foldergram
pnpm install

# Configure
cp .env.example .env  # set GALLERY_ROOT, PORT, etc.

# Run server + client in dev
pnpm dev

# Or build and run with Docker
docker compose up -d

Setup is pnpm-based (pnpm-workspace.yaml). The Dockerfile and docker-compose.yml exist for container deployment. The server entry point is server/src/index.ts; the client dev server runs via Vite (client/vite.config.ts). No test command is wired into CI, despite 88 test files.

Real-World Use

A photographer with a NAS-mounted GALLERY_ROOT folder structure can run Foldergram in Docker, point it at the media directory, and get an Instagram-style feed for clients without uploading to a cloud service. The lazy-derivative mode (LAZY_DERIVATIVES=true) generates thumbnails on first request, which suits large libraries where eager processing would stall startup.

Code Health & Issues

Static analysis found 31 findings (8 high, 23 medium). Key issues:

High – Hub modules: client/src/types/api.ts (46 dependents) and server/src/utils/image-utils.ts (28 dependents) — high blast radius on change.
High – Oversized files: server/src/db/repositories.ts (2231 lines), scanner-service.ts, client/src/stores/collections.ts — hard to reason about.
High – Duplicated code: 707 repeated 6-line blocks across 114 files, including AdminUnlockDialog.vue and AuthGate.vue.
Medium – High branching density in exif-utils.ts, http.ts, csrf-protection.ts.

SDLC gaps: CI workflows (deploy-docs.yml, publish-ghcr.yml) never run the test suite, third-party actions aren't SHA-pinned, no Dependabot config, and the Docker base image (node:22-bookworm-slim) isn't digest-pinned.

The Bottom Line

Foldergram is a credible, self-contained gallery with a modern stack and real tests. The main risks are maintainability — oversized service files and hub modules — and CI that doesn't actually test. Worth using for small-to-medium local galleries; expect to refactor before extending heavily.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

274 files

TypeScript169
Vue43
Markdown14
JSON10
YAML6
CSS3

ReactVueDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["server<br/>97 modules"] g1["client<br/>71 modules"] g2["docs<br/>2 modules"] g0 -->|3| g1

Module dependencies

The 10 most depended-upon modules of 171, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_client_src_types_api["api"] n1_server_src_utils_image_utils["image-utils"] n2_client_src_api_gallery["gallery"] n3_server_src_utils_path_utils["path-utils"] n4_server_src_config_env["env"] n5_client_src_locales_index["index"] n6_client_src_stores_app["app"] n7_c_constants_app_setting_keys["app-setting-keys"] n8_server_src_types_models["models"] n9_client_src_stores_auth["auth"] n2_client_src_api_gallery --> n0_client_src_types_api n6_client_src_stores_app --> n2_client_src_api_gallery n6_client_src_stores_app --> n5_client_src_locales_index n6_client_src_stores_app --> n0_client_src_types_api n6_client_src_stores_app --> n9_client_src_stores_auth n9_client_src_stores_auth --> n2_client_src_api_gallery n9_client_src_stores_auth --> n0_client_src_types_api n0_client_src_types_api --> n5_client_src_locales_index n4_server_src_config_env --> n3_server_src_utils_path_utils n1_server_src_utils_image_utils --> n8_server_src_types_models n1_server_src_utils_image_utils --> n3_server_src_utils_path_utils

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh7 occurrences

.github/workflows

pnpm/action-setup@v4, peaceiris/actions-gh-pages@v4, docker/setup-qemu-action@v3, docker/setup-buildx-action@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Make CI invoke the test suite it hashigh88 occurrences

.github/workflows

88 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

node:22-bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/deploy-docs.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/deploy-docs.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.