Analysis · Geskus reference

Analysis: Geskus reference repos analysis

Two public Geskus repos solve a related but smaller problem space. Neither implements subjects, duplicates, exports, or layouts — so we're learning shapes (RBAC, file trees, task-driven uploads), not borrowing features.

Repos surveyed

• geskus-dev/geskus-client-portal — generic studio-client portal.
• geskus-dev/pics-client-portal — variant that integrates with an external Pics-like API.

Stack

Frontend

SvelteKit 2.47 + Svelte 5, Tailwind 4 + DaisyUI, Vite, @sveltejs/adapter-node for Cloud Run.

Auth

@auth/sveltekit + Auth0. Backend validates JWTs against Auth0 JWKS; supports an API-key + impersonate-user fallback for automation.

Backend

FastAPI (Python) on Uvicorn, deployed to Google Cloud Run.

Data

Firestore for metadata (users, roles, clients, events, file metadata, tasks). Google Cloud Storage for file binaries.

Email

ZeptoMail, gated by a RECEIVE_NOTIFICATIONS permission opt-in.

Our stack (Next.js + Supabase + Pics) doesn't align directly, but the conceptual model translates cleanly.

Domain model

• Studio — single deployment owner, identified by STUDIO_ID at the Firestore root.
• Client — school/organization, with optional parent_client_id for hierarchy.
• User — email + name; many-to-many with roles per client.
• Role — predefined set with permission lists (see below).
• Event — a photo shoot. In geskus-client-portal stored in Firestore; in pics-client-portal fetched from the external Pics API.
• File — flat Firestore metadata (id, name, parent_id, bucket_path, created_at) with binary in GCS. Folders are rows with bucket_path === null. Tree reconstructed at read time.
• Task — file or text request, assigned to a user/client with a due date, status (pending / in_progress / completed), and either text_response or a list of file_response entries. Tasks emit email notifications.

RBAC

Roles live in a Firestore sub-collection: studios/{STUDIO_ID}/users/{user_id}/roles. Each role doc carries a name (one of the predefined role types) and the materialized permission list derived from PREDEFINED_ROLES. Roles can be globally scoped (client_id == null, studio-level) or per-client.

Role	Posture
STUDIO_ADMIN	Implicit superuser — special-cased in code.
STUDIO_USER	Broad CRUD across events, files, tasks; can invite + modify roles.
CLIENT_ADMIN	Manages a single client, can invite users and modify client-scoped roles.
CLIENT_USER	View access + upload data via tasks. The "everyday school user".
DATA_ACCESS	Narrow grant: upload data files, view files and tasks. No event management.
EVENT_ACCESS	View events only.
RECEIVE_NOTIFICATIONS	Opt-in for emails; not a privilege grant.

Permission checks iterate the user's roles, match the requested client_id scope, and look for the named permission. Granular permissions exist for VIEW / CREATE / UPDATE / DELETE of events, files, tasks, plus INVITE_USERS and MODIFY_ROLES.

File handling pattern

• Flat documents indexed by parent_id; tree rebuilt with build_branches() at read time. Avoids deep Firestore nesting.
• Binary in GCS at studios/{STUDIO_ID}/clients/{client_id}/files/{season}/.
• Downloads are signed-URL based with a TTL.
• Upload paths: either a free-form upload from a "FileViewCard" UI (with a hidden <input type=file>) or a structured task-bound upload that mutates the task's file_response.

Task pattern (file-request workflow)

Worth highlighting because it's the cleanest piece of these repos for our Phase 4 (customer portal + files):

1. Studio admin creates a task with input_type='file', allowed types (csv/xlsx/xls/txt/zip), assignee, and due date.
2. Notifications fire to anyone with VIEW_TASKS + RECEIVE_NOTIFICATIONS.
3. Client user sees the task in the portal, uploads the file via a POST endpoint that pushes to GCS and updates the task document.
4. Status transitions from pending → in_progress → completed.

What to borrow

• RBAC shape: Studio / Client / User / Role with permission-scoped grants and an optional client_id scope. Our Phase 4 ADR should adopt this taxonomy.
• Predefined-role pattern: ship a fixed set of role templates rather than letting permissions be edited à la carte. Easier to reason about and easier to display in UI.
• Task-driven file requests: decouples the upload action from when a customer happens to be in the portal, gives an audit trail, and powers notifications.
• Flat-with-parent_id file tree: trivial to render, trivial to mutate, no Firestore-/SQL-specific deep nesting concerns.
• Notifications tied to permission opt-in: avoids the "who gets email" config nightmare.

What to avoid (or not assume exists)

• Don't expect duplicates, exports, or layouts. They're not in either repo — we design from scratch.
• Don't trust the simulated email helpers as a production pattern; we need real SMTP/SES wiring.
• Don't use querySelector to drive file input clicks the way FileViewCard does. Fragile under multiple instances; we'll prefer refs and React-shaped patterns.
• Don't rely on no-pagination file trees. Their assumption is "small school" — at our scale we need cursor pagination on large client trees.
• Don't import the SvelteKit form-action ergonomics wholesale; Next.js server actions are different. The mental model translates, the code doesn't.

Net

Geskus gives us a validated RBAC vocabulary and a clean task-and-file-request pattern. Everything that makes this product different from Geskus — subjects, dedupe, exports with format authoring, print layouts with template authoring, render pipeline — has to come from us.