Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

feat(docs): add agent guide and repository structure documentation

Timothy Yinee87a1569226
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..c8331fd4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,155 @@
+# Agent guide
+
+ChronoFrame is a photo management and gallery pnpm monorepo built with Nuxt 4,
+Vue 3, TypeScript, Nitro and Tailwind CSS. Read the affected application's or
+package's README before editing; this guide describes shared repository rules.
+
+## Repository map
+
+### Application entries
+
+- `apps/self-hosted`: complete Node/Docker application, composing Console and
+ Gallery with onboarding, authentication, API, SQLite, storage and embedded-job
+ adapters. Root development and build commands target this entry.
+- `apps/cloud`: Cloudflare Workers marketing, authentication and platform portal.
+- `apps/site`: independent Cloudflare Workers public gallery entry; extends
+ Gallery, not Console or SaaS UI.
+- `apps/worker`: standalone native photo processing node that claims tasks from
+ Cloud, sends heartbeats and submits results. This is not an edge Worker.
+- `apps/shared`: shared application adapters and platform wiring.
+- `apps/admin`: separate Git submodule, excluded from the root pnpm workspace.
+ Do not assume it is initialized or add workspace dependencies without checking
+ its independent repository setup.
+
+### Shared packages
+
+- `packages/gallery`: public gallery Nuxt layer, viewer, composables, state and
+ translations. Its `shared` directory includes compatibility presentation types.
+- `packages/console`: reusable photo management dashboard Nuxt layer.
+- `packages/saas-ui`: opt-in Cloud/Admin UI primitives, semantic tokens and shell;
+ do not introduce its styling into Self-hosted or Site.
+- `packages/contracts`: browser-compatible schemas, DTOs and named contract
+ exports; no database models, Nuxt globals, Node globals or runtime services.
+- `packages/core`: framework-independent business use cases. Applications inject
+ repositories, trusted access context and infrastructure capabilities.
+- `packages/database`: canonical Self-hosted SQLite schema, migrations, DTO
+ projections and repositories.
+- `packages/platform`: edge platform D1 persistence for identity, sessions and
+ Workspace/Site directory data; separate from Self-hosted SQLite.
+- `packages/jobs`: durable embedded job execution, claims, leases and retries.
+- `packages/processing`: framework-independent photo processing orchestration.
+- `packages/storage`, `packages/media`, `packages/geocoding`: storage providers,
+ media capabilities and reverse geocoding.
+- `packages/webgl-image`: standalone hardware-accelerated image viewer.
+
+`tests` contains repository and integration tests; `scripts` contains launchers,
+maintenance and architecture checks; `docs` contains English and Chinese
+VitePress documentation. Root `.nuxt`, `.output`, `node_modules` and local `data`
+are not canonical source locations.
+
+## Development commands
+
+Use Node.js 22 and the pnpm version pinned in `package.json`. Install with pnpm;
+do not introduce another package manager or lockfile.
+
+Run these commands from the repository root:
+
+| Command | Purpose |
+| -------------------------------------- | ------------------------------------------------------------------ |
+| `pnpm install --frozen-lockfile` | Install workspace dependencies |
+| `pnpm dev` | Prepare Nuxt and run WebGL development build alongside Self-hosted |
+| `pnpm dev:only` | Run Self-hosted alone after dependencies are built |
+| `pnpm build:deps` | Build Storage and WebGL dependencies |
+| `pnpm build` | Build Self-hosted |
+| `pnpm preview` | Preview the Self-hosted build |
+| `pnpm dev:cloud` / `pnpm dev:site` | Develop the corresponding edge entry |
+| `pnpm build:cloud` / `pnpm build:site` | Build the corresponding edge entry |
+| `pnpm lint` / `pnpm fmt:check` | Oxlint and Oxfmt checks |
+| `pnpm test` | Repository tests and Gallery utility tests |
+| `pnpm check:packages` | UI/package boundary checks and package type checks |
+| `pnpm check:ui` | Shared UI boundary checks |
+| `pnpm check:entries` | Application entry boundary checks |
+| `pnpm smoke:cloud` / `pnpm smoke:site` | Run built edge entries locally |
+| `pnpm db:generate` | Generate migrations after schema changes |
+| `pnpm db:migrate` | Apply Self-hosted migrations manually |
+| `pnpm docs:dev` / `pnpm docs:build` | Develop/build documentation |
+
+For local UI verification, check whether port 3000 is already serving the app
+before starting another development server. Use local development by default;
+Docker verification and remote deployment are not routine requirements.
+
+Self-hosted can start directly without creating or configuring a `.env` file.
+Use the setup wizard to create an administrator and configure storage. Runtime
+data paths remain repository-relative.
+Cloud and Site have independent launchers and generated output; do not load the
+Self-hosted environment or start its runtime services from an edge entry.
+
+## Architecture and implementation rules
+
+- Keep HTTP validation, authentication, cookies and runtime effects in application
+ adapters. Shared UI layers must not acquire server implementations.
+- Put shared domain contracts in `packages/contracts`, not database types or
+ application-local aliases. Prefer named package exports and existing helpers.
+- Keep Core independent of Nuxt, filesystem access and database connections.
+ Supply infrastructure through its existing interfaces.
+- Keep native SQLite, Sharp, EXIF tooling and native processing out of edge
+ entries. Native work belongs in Self-hosted adapters or the processing node.
+- Follow Vue Composition API, existing Nuxt auto-import conventions, strict
+ TypeScript and the repository's formatting. Avoid `any`, unsafe casts and
+ unnecessary abstractions.
+- Preserve existing authorization, localization and edition-specific UX. Check
+ every affected entry when changing shared packages; do not implement a feature
+ in one entry by accidentally exposing it in another.
+- Treat trusted Site/access context as an explicit boundary. Never infer tenant
+ authorization from client input or a Self-hosted administrator session.
+- Public DTOs must not expose passwords, password hashes, credentials or internal
+ storage configuration. Preserve protected-media URL handling and redaction.
+- Surface failures through established error/logging/notification patterns.
+ Do not replace failures with silent defaults or success-shaped responses.
+
+## Persistence and processing
+
+- In Self-hosted server adapters, use the existing `useDB()` utility in
+ `apps/self-hosted/server/utils/db.ts` and its exported tables/query helpers.
+ Reuse package repositories for domain operations rather than introducing
+ parallel database access paths.
+- Schema and migrations are owned by `packages/database`. Historical server
+ migration paths are compatibility paths, not a second source of truth.
+- Generate and review SQL for schema changes; never edit released migrations.
+ Check both a fresh database and an upgrade from existing data.
+- Keep SQLite transactions synchronous and short. Never hold transactions across
+ storage I/O, EXIF tooling or other asynchronous processing.
+- Preserve explicit Site scope, source generations, immutable storage connection
+ revisions and transactional resource/job publication.
+- Preserve job leases and attempt identity on claims, heartbeats, stages and
+ completion. Do not reset live workers or let stale attempts publish results.
+- Reuse the shared photo processor for HEIC conversion, metadata, WebP/ThumbHash,
+ EXIF, geocoding and Live/Motion Photo handling. Keep long-running native work
+ outside HTTP request execution.
+- Access storage through existing provider abstractions; do not hard-code a
+ provider or bypass protected-media access controls.
+- Keep platform D1 migrations separate from Self-hosted SQLite migrations.
+
+## Verification and change hygiene
+
+- Make focused changes and preserve unrelated working-tree edits. Do not commit,
+ push, deploy or perform destructive Git operations without explicit direction.
+- Start with the smallest existing test or check covering the change, then run
+ affected package/type/boundary checks. Add regression coverage for changed
+ behavior where practical.
+- For application changes, build dependencies and the affected application, and
+ verify the affected behavior. Edge changes also require entry checks and the
+ corresponding built-entry smoke checks.
+- For documentation changes, update both language versions when applicable.
+ Build VitePress when changing documentation pages; standalone agent guidance
+ does not require an application build.
+- Do not change dependencies merely to run unrelated checks. Keep formatting
+ changes scoped to files you intentionally modify.
+- Never commit `.env` secrets, local databases, photos, logs or generated output.
+ Do not copy production data into source directories or Docker build contexts.
+- Preserve license notices. The repository default is AGPL-3.0-only, with MIT
+ exceptions for Contracts and WebGL; consult `LICENSING.md`.
+
+Use `CONTRIBUTING.md`, package READMEs and the development documentation for
+details. Verify current code when documentation describes an earlier extraction
+phase; do not assume a documented future capability is implemented.