Skip to content

How it works

This page is the map of Aperture’s internals: which processes run, how video gets from a camera to the recorder, the detectors and your browser, how an API request is authenticated and authorized, and which package does what. Each section names the files to open, and the pages linked from it go deeper.

An installed Aperture is three systemd services, plus the MQTT broker if you use Home Assistant. The unit files are in deploy/systemd/.

Unit Program Runs as Job
aperture.service /usr/bin/nvrd root The daemon: web app, API, recorder, detection, retention, integrations, extension supervisor, database
aperture-go2rtc.service /usr/lib/aperture/bin/go2rtc -config /var/lib/aperture/go2rtc.yaml aperture-go2rtc The stream broker: the only process that connects to cameras
aperture-discovery.service /usr/lib/aperture/bin/apdiscovery a dynamic user Announces the install over mDNS/DNS-SD, so aperture.local resolves. No state, no database
mosquitto.service the distribution’s broker its package’s user MQTT for Home Assistant. aperture.service lists it in Wants=, so Aperture starts without it

nvrd starts and supervises its own children. They live in the aperture service’s cgroup and share its memory and CPU limits (MemoryHigh, MemoryMax and CPUQuota in aperture.service):

Child How many Started by
ffmpeg recorder one per recording camera internal/record/recorder.go
ffmpeg motion decoder one per camera with motion detection internal/motion/detector.go
ffmpeg audio decoder one per camera with audio detection internal/audio/detector.go
ffprobe one per new segment, briefly the indexer in internal/record
ffmpeg on demand per export or scrub-preview frame internal/export, internal/api/recordings_handlers.go
apdetect one worker while object recognition is on internal/ai/worker.go
deno one per enabled backend extension internal/ext/supervisor.go

nvrd runs as root because it starts each extension backend under its own uid and gives it ownership of its folder. The unit takes most other privileges away: ProtectSystem=strict with /var/lib/aperture as the only writable path, NoNewPrivileges=yes, RestrictNamespaces=yes, and the kernel-protection switches. The comments in deploy/systemd/aperture.service explain each setting and the ones left out on purpose.

Four unit settings shape how the daemon behaves:

  • Restart=always with RestartSec=2, and StartLimitIntervalSec=0 in [Unit], so a crash loop never leaves the NVR permanently stopped. The in-app restart button exits the process and relies on this.
  • ExecStartPre=/usr/libexec/aperture/aperture-harden re-applies file modes and refuses to start when the recordings directory is inside the data directory, or when the database exists without secrets.json (see Data model).
  • KillMode=mixed with TimeoutStopSec=45: on stop, only nvrd gets SIGTERM and runs its ordered shutdown; the rest of the cgroup is killed only if that takes longer than 45 seconds (see Shutdown).
  • OOMPolicy=continue: when the kernel ends a child under memory pressure (extensions and the apdetect worker raise their oom_score_adj so they go first), the service keeps running.

The unit puts /usr/lib/aperture/bin first on PATH, so a vendored ffmpeg there wins over the distribution’s.

go2rtc holds the only connection to each camera stream: one for the main stream, and one for the sub stream when you set one and something reads it. Everything else reads from go2rtc. A camera sees the same one or two clients whether nobody is watching or ten people are.

Consumer What it reads from go2rtc Code
Recorder RTSP restream rtsp://127.0.0.1:8554/cam_<id> (cam_<id>_sub with low recording quality) stream.Manager.RTSPURL, internal/record/recorder.go
Motion detection cam_<id>_sub if the camera has a sub stream, otherwise cam_<id> internal/motion/detector.go
Audio detection cam_<id> internal/audio/detector.go
Object recognition nothing of its own: frames come from the motion decoder internal/detect/live.go
Browser live view go2rtc’s WebSocket /api/ws?src=cam_<id>, through nvrd’s authenticated proxy stream.Manager.ProxyWS
Snapshots and placeholders GET /api/frame.jpeg?src=cam_<id> on go2rtc’s API stream.Manager.Snapshot
Test connection a temporary stream test_<id>, deleted after one frame stream.Manager.TestStream
Watchdog probe an RTSP DESCRIBE to the restream, for cameras nothing else reads stream.Manager.Probe
Home Assistant, VLC, other recorders the RTSP restream on port 8554, directly see ONVIF and RTSP

Aperture talks to a camera directly only for control, never for video: ONVIF picture settings (internal/onvifclient) and the Reolink HTTP API for spotlight and infrared (internal/reolink).

nvrd registers streams through go2rtc’s HTTP API (PUT /api/streams). go2rtc’s config file, /var/lib/aperture/go2rtc.yaml, ends up holding the camera links with their passwords, which is why it is owned by aperture-go2rtc and mode 0600. nvrd does not rely on that file: stream.Manager.Sync runs at start and every 60 seconds (cmd/nvrd/main.go). It registers a stream only when its source changed, because re-registering an unchanged stream drops every viewer, and it deletes cam_* streams whose camera is gone. A go2rtc that restarted without its streams is repopulated within a minute.

cameras
| RTSP: one connection per camera stream
v
+--------------------- aperture-go2rtc.service ---------------------+
| go2rtc streams cam_<id>, cam_<id>_sub |
| HTTP API 127.0.0.1:1984 | RTSP :8554 | WebRTC :8555 |
+-------^----------------------^------------------+-----------------+
| | |
| register streams, | RTSP restream +--> WebRTC media to browsers
| frame.jpeg, /api/ws | +--> RTSP to Home Assistant, VLC,
| | other recorders
+-------+----------------------+------ aperture.service ------------+
| nvrd |
| HTTP :8971 chi router, /api/v1, embedded web app <-----------+---- browsers, PWA,
| recorder ------ ffmpeg per camera --> recordings/<id>/*.ts | nvrctl, scripts
| motion, audio - ffmpeg per camera --> events |
| object recognition ---------------> apdetect worker (ONNX) |
| indexer, uploader, mirrors, janitor, watchdog |
| Home Assistant publisher ---------> MQTT (mosquitto) |
| extension supervisor -------------> deno per extension |
| store ----------------------------> data/aperture.db (SQLite) |
+-------------------------------------------------------------------+

Port 8971 is the installed value of APERTURE_HTTP_ADDR; a development build listens on :8080. See Configuration for every variable.

Opening a camera tile is a good example: it uses an ordinary JSON route, a WebSocket and go2rtc.

  1. The web app calls GET /api/v1/cameras/{id}/stream-token. The browser sends the aperture_session cookie.
  2. The request passes the root middleware in Server.routes (internal/api/server.go), in this order: chi’s RequestID, then clientip.Resolver.Middleware (the client address, see below), chi’s Recoverer, then logRequests (logs every API write and every error response), then auth.Manager.Context, which turns the cookie into claims (see Principals).
  3. Under /api/v1, apiVersionHeaders sets X-Aperture-Api-Version: v1. Then three API-wide guards run: rateLimit, limitBody and csrfGuard.
  4. The route’s access spec runs last. This route is declared scopedCam(ScopeMediaLive), so enforce requires a signed-in principal, the media:live scope if the principal is an API token, and access to camera {id}.
  5. handleStreamToken (internal/api/stream_handlers.go) signs a stream token for that one camera, valid for 5 minutes (streamTokenTTL), and returns {token, wsUrl, hasSub}.
  6. The browser opens the WebSocket wsUrl, /api/v1/cameras/{id}/ws?token=…, adding &q=sub for the sub stream. A browser cannot set an Authorization header on a WebSocket, so this route is declared pub and handleStreamWS checks the token itself (authorizeStreamWS). {id} may be the camera id or its handle.
  7. stream.Manager.ProxyWS rewrites the request to go2rtc’s /api/ws?src=cam_<id>, removes the Origin header (go2rtc rejects cross-origin WebSockets, and nvrd is the trusted proxy in front of it) and reverse-proxies the socket.
  8. go2rtc and the browser negotiate WebRTC over that socket. The video then flows directly between the browser and go2rtc’s port 8555; if WebRTC fails, the player falls back to MSE and the video travels inside a WebSocket through nvrd.

Live streaming covers steps 5 to 8 in depth: the signalling messages, the fallback and the player’s reconnect logic.

Everything the web app does goes through the same API that scripts and extensions use. The router is chi, and every route is registered in one function, Server.routes in internal/api/server.go.

The route table is mounted twice, at /api/v1 and at the older unversioned /api. Both run the same handlers. The /api alias answers with Deprecation: true and Link: </api/v1>; rel="successor-version" and counts its callers for GET /api/v1/system/metrics. The web app’s client (v1Path in web/src/lib/api.ts) rewrites every /api/… path to /api/v1/….

A route cannot be registered without saying who may call it. Handlers are added through apiRouter (internal/api/access.go), whose Get, Post, Put and Delete methods all take an access value:

Field Meaning
public No authentication
admin The principal’s role must be admin
sessionOnly API tokens are refused, whatever their scopes
scopes Scopes an API token must hold; sessions and the CLI token pass
camera camScopeParam: the caller must be allowed to see the camera in the {id} path parameter

The shorthands used in server.go are pub, authed, authedSessionOnly, adminSessionOnly, extSelfOnly, and the functions scoped(…), scopedCam(…), adminScoped(…) and adminScopedCam(…). apiRouter.method records each route in declaredRoutes and routeSpecs and wraps the handler in Server.enforce, which answers in this order:

Check Response
No principal on a non-public route 401 unauthenticated
admin and the role is not admin 403 forbidden
sessionOnly and the principal is an API token 403 forbidden
extSelf (extSelfOnly) and the principal is neither a session nor the {id} extension’s own token 403 forbidden.extension
An API token without a required scope 403 forbidden.scope
Camera-scoped and the camera is not visible to the caller 403 forbidden.camera

Operations that could take over an account or the whole system are session-only rather than scoped, so no token can reach them: users, tokens, password, second factor, passkeys, backup, restore, restart, purge, reindex and the extension manager.

After the router is built, assertAllRoutesDeclared walks the whole chi tree. If any route under /api or /api/v1 was registered without going through apiRouter, it panics with fail-closed authorization guard: … registered without an Access descriptor, and nvrd does not start. An unguarded route cannot reach a running server. TestFailClosed_UndeclaredRouteRefusesBoot and TestRealRouterBootsClean in internal/api/fail_closed_test.go pin this.

  • Errors are JSON: {"error": "<English text>", "code": "<machine code>"} (writeErrorCode in internal/api/respond.go). Match on code; the text may change. An unknown path under the API prefix returns a JSON 404 not_found, and a wrong method a JSON 405 method_not_allowed, never the web app’s HTML.
  • Arrays are never null: writeJSON replaces nil slices with [] at any depth.
  • Config resources carry a strong ETag. An API token must send If-Match on config writes (428 without it, 412 when stale); for sessions it is optional (internal/api/etag.go).
  • POST /export and POST /shares accept an Idempotency-Key; a repeat within 24 hours replays the first response (internal/api/idempotency.go).
  • GET /events, GET /system/audit and GET /cameras/{id}/segments use cursor pagination.
  • GET /api/v1/openapi.json (any signed-in principal) is generated from routeSpecs at request time, so the required scopes it lists (x-required-scopes, x-requires-admin) are the ones enforce checks.
Guard What it does Values
rateLimit (limit.go) Token bucket per principal; anonymous callers per IP. 429 with Retry-After: 1 Sessions and CLI: burst 240, 120 per second. Tokens: burst 40, 20 per second, keyed by owning user. Anonymous: burst 30, 10 per second
limitBody (limit.go) Caps the body; 413 payload_too_large 1 MiB for JSON, 256 MiB for multipart, 2 GiB for a model upload. A non-multipart POST, PUT or PATCH body must arrive within 30 seconds
csrfGuard (ext_broker.go) Refuses a cookie-authenticated POST, PUT, PATCH or DELETE whose Origin (or Referer) host differs from the request’s Host 403 cross-origin request blocked

The HTTP server itself (Server.NewHTTPServer in internal/api/shutdown.go) sets ReadHeaderTimeout to 10 seconds and IdleTimeout to 120 seconds, and leaves ReadTimeout and WriteTimeout unset so event streams and long exports are not cut.

The client address comes from internal/clientip. Forwarding headers count only when the direct peer is in APERTURE_TRUSTED_PROXIES (default 127.0.0.0/8, ::1/128). From such a peer the middleware walks X-Forwarded-For from the right and takes the first entry that is not a trusted proxy (X-Real-IP when there is no X-Forwarded-For), rewrites RemoteAddr to it, and reads X-Forwarded-Proto. From any other peer it deletes X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Real-IP, True-Client-IP and Forwarded before any handler runs. The anonymous rate-limit key, the activity log, session and trusted-device records, the passkey origin (clientip.Scheme) and the passkey sign-in cookie’s Secure flag all read the result. See Client addresses.

/api/v1 changes only by adding: new routes, new optional fields. The capabilities document (GET /api/v1/capabilities) reports apiV1FrozenAt, set the first time extensions are enabled or one is installed (freezeV1 in internal/api/ext_handlers.go); from then on a breaking change needs a v2. The extension machinery under /api/v1/ext/ is exempt (frozenExempt), because only the web app and the SDK talk to it. The route reference is at API reference and the scopes at Scopes.

auth.Manager.Context (internal/auth/middleware.go) never rejects a request. It attaches claims if it can and leaves the decision to enforce. It tries, in order: the session cookie, then a Bearer header as the CLI token, then as an API token. The result carries a class:

Class Credential Authority
session The aperture_session cookie. A random 256-bit token; the sessions table keeps only its SHA-256 hash. Signed out after 90 days unused or 365 days after sign-in (internal/api/sessions.go) The user’s role and camera access, all scopes
cli Authorization: Bearer <cli_token>, the token in data/cli.token, compared in constant time A synthetic admin named nvrctl, all scopes. Used by nvrctl
token Authorization: Bearer apt_…, looked up by hash in api_tokens (Store.ResolveAPIToken) Acts as its owner, limited to its scopes and camera grants; never more than the owner. Refused if the owner is disabled or the token expired

A few routes accept narrower credentials of their own, outside these classes:

  • The live WebSocket accepts a stream token, an API token with media:live, or the server-managed live-view key, an integration setting an administrator can reveal and replace (Live streaming).
  • Share links (/s/{token}) carry a random token that the shares table keeps only as a hash (Export and share). Event-thumbnail links in notifications (/api/v1/public/event-thumb) are signed.
  • Extension UI assets (/ext/{id}/*) need no credential; the panel reaches data only through the broker (see Extensions).

Users, roles and per-camera access are on Users; sign-in methods on Sign-in and SSO.

cmd/nvrd/main.go wires everything together and starts these loops. The ones marked “waited” are tracked by the services type in cmd/nvrd/shutdown.go and given time to finish on shutdown.

Loop Interval Waited
go2rtc stream reconciliation (stream.Manager.Sync) at start, then 60 s no
Snapshot cache warm-up (WarmSnapshots) 15 s no
Scrub-frame cache prune (files older than 2 h) 30 min no
Recorder: reconcile ffmpeg set; index, upload, mirror 60 s; 8 s yes
Retention janitor 5 min, plus on allocation changes yes
Motion detector, audio detector continuous yes
Object recognition engine continuous yes
Home Assistant publisher continuous yes
Weather poller while a site location is set yes
Watchdog (recording health, camera online state) 15 s yes
Rate-limit bucket sweep 5 min no

The recorder runs one ffmpeg per camera that copies the video without re-encoding (unless you give that camera a lower recording quality) into 10-second MPEG-TS files named after their start second, <camera id>/<epoch>.ts. Audio is re-encoded to AAC at 32 kbit/s. Every 8 seconds the indexer probes finished files with ffprobe and inserts a segments row for each. For an SMB or SFTP destination, ffmpeg writes to a local spool and an uploader moves finished files to the share. Mirrors copy indexed segments to further destinations and record each copy in segment_copies. Every 5 minutes the janitor deletes by age, quota, allocation and free space; it deletes the file first and keeps the row until the file is really gone. Playback builds an HLS playlist from the rows on each request.

The details, with the exact ffmpeg command, are in Recording pipeline. The settings are on Storage and Recording.

Motion detection decodes a small grayscale copy of each camera’s stream with ffmpeg and compares cells of consecutive frames in Go. When enough of the picture changes, an event opens; it closes after a quiet period. The same ffmpeg also writes colour frames to a second pipe, which feed object recognition: the apdetect worker runs an ONNX model through ONNX Runtime on the CPU or an NVIDIA GPU and returns boxes, which become live overlays, labels on the event and Home Assistant presence. Instead of the local worker, events can be sent to an external DeepStack-style server. Audio detection is a separate ffmpeg per camera that measures loudness.

When an event opens, cmd/nvrd/main.go fans it out: object recognition tags it, then notifications, webhooks, automations and the HomeKit motion sensor get it. Detection pipeline follows every step; Motion and Object recognition cover the settings.

Extensions are off until an administrator types enable extensions to confirm (POST /api/v1/ext/gate, admin and session-only). An extension is a bundle with a manifest, optional UI panels and an optional Deno backend.

  • Panels are served from /ext/{id}/* (internal/api/ext_static.go) with a restrictive Content Security Policy into a sandboxed iframe that carries no cookie. A panel calls the API through POST /api/v1/ext/{id}/broker, which runs the call with the authority the signed-in user and the extension have in common.
  • Backends are started by internal/ext/supervisor.go. nvrd re-executes itself as nvrd __ext-spawn … under the extension’s own uid (allocated from 65600 upwards), applies resource limits and a raised oom_score_adj, then runs Deno with deny-by-default flags built in internal/ext/spec.go: --deny-run, --deny-ffi, --deny-sys, --deny-import, reads limited to the extension’s folder and the SDK, writes to its folder, and network access only to the hosts its manifest declares plus the Aperture API. The backend authenticates with its own API token.
  • Files live in data/ext/<id>/; per-extension key-value data in the ext_kv table.

On shutdown extensions are stopped first, with SIGTERM and SIGKILL 5 seconds later. See Extensions and Extension security.

GET /api/v1/feed (internal/api/feed_handlers.go) is a Server-Sent Events stream of envelopes {id, type, ts, camera, data}, published through notify.Engine.PublishFeed (internal/notify/feed.go). The web app uses it to update without polling.

There are two kinds of message:

  • Durable: event.created and event.closed, whose SSE id: is the event’s seq. On reconnect the browser sends Last-Event-ID and the server replays event.created for up to 1,000 events with a higher seq, straight from the database. If the cursor is older than the oldest kept event it sends {"type":"reset"} so the client refetches.
  • Ephemeral: live state such as camera.state, motion.state, objects.live, detection.created, storage.updated, config.updated, automation.updated, alarm.state and export.progress. They get an in-process id and are not replayed; instead the latest message per type and camera is sent as a snapshot right after connecting.

?types= and ?cameras= (comma-separated) filter server-side. Every message about a camera is checked against the connection’s camera access, a keep-alive comment goes out every 25 seconds, and an API token is re-checked every 60 seconds so a revoked token stops receiving within a minute. A slow subscriber’s frames are dropped rather than buffered. GET /api/v1/notify/stream is a second SSE stream that delivers in-app notifications.

On SIGTERM or SIGINT, nvrd stops in a fixed order (cmd/nvrd/main.go, budgets in cmd/nvrd/shutdown.go):

  1. Extension backends, while the API they call is still up: their stop window plus 2 seconds (extStopSlack).
  2. Background services: the recorder lets every ffmpeg close the segment it is writing, the detectors reap their ffmpeg, and Home Assistant is told the NVR is going offline. Up to 20 seconds (bgStopWait).
  3. HTTP: event streams end at once (CloseStreams), so browsers reconnect to the next instance; other requests get up to 10 seconds (httpStopWait).
  4. Storage backends and the database.

The worst case is about 37 seconds, inside the unit’s TimeoutStopSec=45. The last log line, shutdown complete, gives the time each phase took and names the slowest service. Recording pipeline explains what happens to the segment being written.

The web app uses i18next with react-i18next (web/src/lib/i18n.ts). A translatable string is written as t("key", "English text"), so English needs no catalog and is the fallback for any key a catalog lacks. The only other language is German. Its catalog covers the navigation, the sign-in screen, common buttons, parts of Settings and the personal preferences; the rest of the interface is English in every language setting.

The language is a per-user preference (language: auto, en or de) saved through PUT /api/v1/users/me/preferences and mirrored in the browser’s localStorage as aperture.lang. auto picks German when the browser’s language starts with de. The same setting drives date and number formatting (setLocale in web/src/lib/format.ts). The server does not translate: API error text is English, which is why clients should match on code.

The web app is React 18 with TypeScript, Vite, TanStack Query, React Router and Tailwind, in web/. It ships inside the nvrd binary:

  1. make build-web runs npm ci && npm run build in web/ (tsc then vite build) and copies web/dist to internal/webassets/dist.
  2. internal/webassets/embed.go embeds that folder with //go:embed all:dist.
  3. spaHandler (internal/api/static.go) serves it. Files under assets/ have content hashes in their names and are sent with Cache-Control: public, max-age=31536000, immutable. index.html, and every path that is not a file so that client-side routes work on reload, is sent with Cache-Control: no-cache, no-store, must-revalidate. A new build therefore reaches browsers on the next load.

The service worker (web/public/sw.js) caches nothing; it handles Web Push and notification clicks only.

The embedded folder is a build artifact and is not in git. go build embeds whatever is in it, however old, so make check-web-fresh exists to catch a stale bundle: it fails if internal/webassets/dist/index.html is missing or if any file in web/src or web/index.html is newer than it. The make build and make build-native targets always rebuild the bundle first. With APERTURE_WEB_DIR set, nvrd serves the web app from that folder instead of the embedded copy (see Development).

Path What is there
cmd/nvrd The daemon: wiring, interop services (HomeKit, ONVIF), ordered shutdown
cmd/nvrctl The admin console: full-screen TUI and scriptable subcommands (nvrctl)
cmd/apdetect The object-recognition worker; frames in on stdin, detections out on stdout
cmd/apdiscovery The mDNS/DNS-SD advertiser
web/ The React web app; web/src/screens, components, lib, ext (extension host), ext-sdk
deploy/ Installer, uninstaller, vendoring script, systemd units, sysusers and tmpfiles snippets, aperture-harden, the extension SDK module (aperture-sdk/mod.ts)
examples/ Example extensions, and their built bundles in examples/dist
tools/mkbundles Builds examples/dist/*.zip deterministically (make examples)
test/fixtures Test fixtures, such as an extension that probes its sandbox
docs/ Older Markdown guides (detection, Home Assistant, extensions)

The internal/ packages:

Package What it does
ai Object recognition: pinned downloads of ONNX Runtime and models, the worker protocol, pre- and post-processing, label mapping
ai/ort A minimal ONNX Runtime binding loaded at run time with purego, so no cgo; used only by apdetect
api The HTTP API, access specs, the change feed, the web app handler, playback and export routes
astro Sunrise, sunset, twilight and moon phase, computed locally
audio Loud-sound detection, one ffmpeg per camera
audit The hash-chained activity log
auth Password hashing, session and stream tokens, the request-claims middleware
automate The local automation engine: event conditions to actions
config Environment variables, defaults, directory creation, secrets.json
detect Live object recognition, event tagging, tracks, presence, the package watch, the external detector bridge
eufy The Eufy bridge account and session
export MP4 export: stream-copy concatenation, optional burn-in, multi-camera, timelapse
ext Extension manifests, permissions, Deno launch specs, the backend supervisor
format Human-readable units shared by the API, the audit log and nvrctl
ha Home Assistant over MQTT: discovery, state, presence, inbound control
homekit The HomeKit bridge
hwinfo What the host can do: CPU, cgroup limits, GPU; feeds the capacity estimate
logbuf An in-memory ring of recent log lines for the diagnostics bundle
motion Motion detection and the frame source for object recognition
notify Notification rules and channels (Web Push, ntfy, Telegram, Discord, webhook, email) and the change-feed hub
oidc OpenID Connect sign-in
onvif The ONVIF Profile S provider that lets other recorders use Aperture’s cameras
onvifclient The client that adjusts a camera’s own picture settings over ONVIF
record The recorder, indexer, uploader and mirrors
reolink Reolink spotlight and infrared control over the camera’s HTTP API
reserve The hard-reservation balloon file
retention The janitor: age limits, quotas, allocations, free-space floor
secret AES-256-GCM encryption of stored credentials
site The site profile: location, timezone, units
storage Storage backends: local folder, SMB, SFTP
store SQLite access and the embedded migrations
stream go2rtc orchestration: stream registration, snapshots, the WebSocket proxy
urlcred Keeps the secret part of a camera link on the server
version Build version, injected with -ldflags
watchdog Recording health and camera online state, with recovery
weather The weather time series behind the playback ribbon
webassets The embedded web bundle
webhook Signed outbound webhooks with retry and a delivery log

A reading order that builds the picture fastest:

  1. cmd/nvrd/main.go: every subsystem is constructed and connected here, and the shutdown order is at the end.
  2. internal/api/server.go and internal/api/access.go: the complete route table with each route’s access spec, and how it is enforced.
  3. internal/stream/manager.go: how cameras become go2rtc streams.
  4. internal/record/recorder.go: the recorder, the indexer and the uploader.
  5. internal/store/migrations: the schema, one change per file.
  6. internal/motion/detector.go and internal/detect/live.go: from frames to events and boxes.
  7. web/src/App.tsx and web/src/lib/api.ts: the web app’s routes and its API client.

Many files open with a comment that explains why the code is shaped the way it is; read those first.

Related: Recording pipeline, Live streaming, Detection pipeline, Data model, Development.