Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
feat(docs): add agent guide and repository structure documentation
Timothy Yinee87a1569226
diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 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.