55 lines
2.8 KiB
Markdown
55 lines
2.8 KiB
Markdown
# CLAUDE.md — project memory for AI assistants & developers
|
||
|
||
> **This file is the project-local source of truth.** It lives in the repo (not in any individual's
|
||
> `~/.claude`), so any developer — or any Claude/AI account that opens this package — can read the
|
||
> full context, decisions, and roadmap. Keep it updated as the project evolves.
|
||
|
||
## What this is
|
||
|
||
A **reusable macOS Photos–style photo gallery SDK** (`@photo-gallery/sdk`) for React / Next.js, plus a
|
||
Next.js demo (`apps/web`). Goal: a near carbon-copy of macOS Photos (light/dark/semi-dark, fully
|
||
responsive) where **every feature is optional via flags**, so each consuming project enables only what
|
||
it needs. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the complete, living feature checklist
|
||
(done / in-progress / planned) and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the design.
|
||
|
||
## Monorepo
|
||
|
||
- `packages/photo-sdk` — the SDK (React components, Zustand store, adapters, AI provider interface,
|
||
lib utils, self-contained CSS). **No heavy/ML deps in here** — they're injected by the host app.
|
||
- `apps/web` — Next.js demo: landing page (`/`) + gallery (`/gallery`), AI providers, server routes.
|
||
|
||
## Conventions
|
||
|
||
- SDK ships its own `styles.css` (no Tailwind required by consumers). Classes are prefixed `apg-`.
|
||
- State: a per-instance Zustand store (`createGalleryStore`) provided via React context.
|
||
- Storage is a pluggable `StorageAdapter` (default: localStorage/IndexedDB). AI is a pluggable
|
||
`AIProvider` (object detection / faces / OCR / caption / embeddings / generativeEdit) — all optional.
|
||
- Every capability is gated by a feature flag (`features={{ editor, camera, ai, map, import, export, ... }}`).
|
||
- Security: strict per-request **nonce CSP** (middleware), input validation, URL-scheme allow-list,
|
||
filename sanitization, server-only API keys (never `NEXT_PUBLIC_`). Don't regress this.
|
||
|
||
## Secrets
|
||
|
||
- API keys go in `apps/web/.env.local` (gitignored via `.env.*`). **Never commit keys.** Gemini is
|
||
read server-side only in `apps/web/src/app/api/ai/edit/route.ts`. See `.env.example`.
|
||
|
||
## Run
|
||
|
||
```bash
|
||
pnpm install && pnpm dev # http://localhost:3000 (landing → Open Gallery → /gallery)
|
||
pnpm build # SDK (tsup) + Next production build
|
||
pnpm typecheck
|
||
```
|
||
|
||
Full setup/troubleshooting: [`docs/SETUP.md`](docs/SETUP.md).
|
||
|
||
## Memory & status
|
||
|
||
**AI/working memory lives in [`.claude/memory/`](.claude/memory/)** (committed with the repo, not in any
|
||
machine's global `~/.claude`):
|
||
- [`.claude/memory/status.md`](.claude/memory/status.md) — current status + session log.
|
||
- [`.claude/memory/requirements.md`](.claude/memory/requirements.md) — the complete requirements backlog.
|
||
|
||
Human-facing feature checklist is [`docs/ROADMAP.md`](docs/ROADMAP.md). Read `.claude/memory/` + `docs/ROADMAP.md`
|
||
first — they are authoritative and travel with the code.
|