README.md

OpenClapper docs

Reference documentation for the whole app. Start with architecture, then read the feature page for whatever you are changing.

Project

Page	What it covers
architecture.md	Repo layout, stack per app, how data flows from the phone to the Studio, auth
data-model.md	D1 tables, the shot/photo split, JSON columns, migrations
api.md	Every Worker endpoint, with request and response shapes
development.md	Local dev loops, checks, deploy, migrations, APK builds
testing.md	What runs where (unit, Worker and admin route tests), the route-test helpers, the tenancy map rule
infrastructure.md	Cloudflare resources, auth, secrets
releasing.md	One product version (SemVer 0.x), cutting a release, what a deployment does after
self-hosting.md	Running your own instance: API token, settings, the deploy workflow, the admin plane's Access app, updates, the phone
known-issues.md	Risks and untested cases we know about, with where they live
design.md	Design system: Sun/Set themes, contrast rules, tokens, icons, where the styles live

Features

Page	What it covers
features/accounts.md	Sign-in, sessions, workspaces and their members and roles, the Account settings
features/admin.md	The admin plane: its own Worker and board behind its own Access app, accounts and workspaces across the instance
features/monitoring.md	Storage monitoring in the admin plane: the daily snapshot, the operator's marks, the optional Cloudflare overlay
features/projects.md	Projects as a hard scope, the active project on both clients
features/capture.md	Phone Shoot tab: rigs, lenses, overlay, controls, HUD chips, Tag after capture, sequences, direct upload, upload queue
features/viewfinder-layouts.md	Viewfinder layouts: the model, the Studio editor, how the phone renders them
features/review-and-tagging.md	Tags (light model, INT/EXT, weather, location, spot), the shot view, Metadata board, History on the phone, view modes (mask/frame/fit/raw)
features/extra-fields.md	User-defined fields as JSON, AI import, per-project selection
features/positions.md	GPS modes (High · Low · Off), photos without a position, manual pin correction, location pins and shots synced to them
features/rig-explorer.md	Framing: re-frame a photo (other rig + lens, moved), saved framings, the root frame, Compare A / B
features/new-shot.md	New shot in the Studio from uploaded images or a drawn sketch
features/compose.md	Shot descriptions, the drawing model, sketches (floor plans, diagrams); Studio editor, phone viewer, renders
features/schedule.md	Shooting days, daylight phases, forecast, shootable windows
features/timeline.md	Timelines: rough cuts of steps and clip layers with hold times, playback (Studio only)
features/composition.md	A shot as a composition: steps, layers (drawing and adjustment, with order, range and space), bakes for the phone, the Compose stage, merge and extract, the migration from overlays
features/day-mode-offline.md	Phone "Day" tab, offline days, offline project, offline mode, edits kept on the phone
features/phone-app.md	Phone shell: 5 tabs, gates, pushed screens, header and sync state, Setup hub, shared components
features/files.md	Files on the desktop: folders, the Desktop folder, the Files app, desktop icons and selection, the recycle bin
features/desktop.md	The Studio desktop: startup and projects, windows and the side-by-side split, workspaces and task view, taskbar and pins, launcher, the apps, URL and keys, the Gallery (grid/list/map, filters, views)
shortcuts.md	Every Studio keyboard shortcut, generated from apps/studio/src/shortcuts.ts
features/lights.md	Lights: pairing NEEWER and Aputure fixtures and the NEEWER battery over Bluetooth, the connection manager, the synced list (epic #206)
features/debug-log.md	The phone's background debug log

History

• Before 2026-09-27: prototype with one shot = one photo, districts and a hard-coded U-Bahn list.
• 2026-09-27: rework from GitHub issue #1. Schema reset to 0001_baseline.sql (prototype data dropped), then all features above. The implementation plan is in the git history of branch rework/phase-1-projects-photos.
• 2026-09-28: redesign on a design system from Claude Design (design.md), then a ground-up rework of the Studio and the phone screens from Claude Design (Studio, phone app); features unchanged.
• 2026-10-16: the Studio became a desktop scoped to one project (epic #72): apps in windows, a taskbar, folders and desktop shortcuts on the server (desktop, files).
• 2026-10-16: desktop v2 (epic #90): a recycle bin for every delete (30 days), the Desktop folder with real icons on a grid and rubber-band selection, workspaces with a task view, a split grip for side-by-side windows, taskbar position, alignment and server-side pins.