@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-architecture/SKILL.md

@@ -0,0 +1,552 @@
+---
+name: maestro-architecture
+description: "Layered TypeScript architecture pattern for maestro-js backends. Covers Zod schemas (base model, extended views, request inputs), database providers (data access with SQL + Zod parsing), and use cases (z.function business logic with permissions). Use when scaffolding new domains, writing providers or use cases, or understanding the schema/provider/use-case layer conventions."
+---
+
+# Layered TypeScript Architecture: Schemas, Providers, and Use Cases
+
+A portable pattern for building type-safe, layered Node.js backends. This architecture uses Zod as the backbone for runtime validation and type inference,  providers as a strict data access layer, and use cases as the business logic orchestration layer.
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview](#1-architecture-overview)
+2. [Layer 1: Zod Schemas (Type System)](#2-layer-1-zod-schemas)
+3. [Layer 2: Database Providers (Data Access)](#3-layer-2-database-providers)
+4. [Layer 3: Use Cases (Business Logic)](#4-layer-3-use-cases)
+5. [Supporting Utilities](#5-supporting-utilities)
+6. [How It All Connects](#6-how-it-all-connects)
+7. [Adapting to Your Project](#7-adapting-to-your-project)
+
+---
+
+## 1. Architecture Overview
+
+```
+Route Handler (Remix action / Express route)
+  │
+  ▼
+Use Case (z.function, permissions, orchestration)
+  │
+  ▼
+Provider (SQL queries or Api Calls, Zod parsing, data mapping)
+  │
+  ▼
+Database / API (depending on the type of the provider)
+```
+
+**Principles:**
+- Schemas are the single source of truth for types AND runtime validation
+- Providers own ALL database / external api access — no raw SQL anywhere else
+- Use cases own ALL business logic — routes are thin wrappers
+- Types flow from schemas through every layer via `z.infer<>`
+- Hard dependencies everywhere — no DI containers, no mocks in production code
+
+---
+
+## 2. Layer 1: Zod Schemas
+
+Schemas define every data shape in the system. They serve triple duty: TypeScript types, runtime validation, and documentation.
+
+
+### 2a. Single-File Schema Pattern
+
+Each domain entity lives in a single `index.ts` file. All three schema layers — base model, extended views, and request/response inputs — are defined together, then exported as a single namespace object with a companion `declare namespace` block for types.
+
+```typescript
+// packages/schemas/src/widget-tags/index.ts
+import { z } from 'zod'
+import { isoZ } from '@maestro-js/iso-zod'
+
+// ─── Enums ───────────────────────────────────────────────
+const removedReasonOptions = ['expired', 'resolved', 'other'] as const
+const removedReasonLabels = {
+  expired: 'Expired',
+  resolved: 'Resolved',
+  other: 'Other'
+} satisfies { [key in (typeof removedReasonOptions)[number]]: string }
+const removedReasonEnum = z.enum(removedReasonOptions).meta({ enumLabels: removedReasonLabels })
+
+// ─── Layer A: Base Model (matches DB columns exactly) ────
+const widgetTagModel = z.object({
+  id: z.uuid(),
+  widgetId: z.string(),
+  notes: z.string().max(2000).nullable(),
+  expirationDate: isoZ.date().nullable(),
+  createdDate: isoZ.instant(),
+  createdByProfileId: z.number(),
+  removedDate: isoZ.instant().nullable(),
+  removedByProfileId: z.number().nullable(),
+  removedReason: removedReasonEnum.nullable(),
+  removedNotes: z.string().max(2000).nullable(),
+  lastModifiedDate: isoZ.instant()
+})
+
+// ─── Layer B: Extended Views (joined/computed fields) ────
+const widgetTagAdminView = widgetTagModel.extend({
+  serialNumber: z.string().min(1).nullable(),
+  createdByUserName: z.string().nullable(),
+  removedByUserName: z.string().nullable()
+})
+
+// ─── Layer C: Request/Input Schemas ──────────────────────
+const createWidgetTagInput = z.object({
+  widgetId: z.string().uuid(),
+  notes: z.string().max(2000).nullable(),
+  expirationDate: isoZ.date().nullable()
+})
+
+// ─── Domain Helpers ──────────────────────────────────────
+// Helpers reference the namespace type — works because declare namespace is hoisted.
+function isTagActive(
+  tag: Pick<WidgetTagSchemas.widgetTagModel, 'removedDate'>
+): boolean {
+  return tag.removedDate === null
+}
+
+// ─── Namespace Export ────────────────────────────────────
+export const WidgetTagSchemas = {
+  removedReasonOptions,
+  removedReasonLabels,
+  removedReasonEnum,
+  widgetTagModel,
+  widgetTagAdminView,
+  createWidgetTagInput,
+  isTagActive
+}
+
+// ─── Type Declarations ───────────────────────────────────
+// declare namespace merges with the exported const — consumers get
+// both runtime schemas and inferred types from a single import.
+export declare namespace WidgetTagSchemas {
+  export type widgetTagModel = z.infer<typeof widgetTagModel>
+  export type widgetTagAdminView = z.infer<typeof widgetTagAdminView>
+  export type createWidgetTagInput = z.infer<typeof createWidgetTagInput>
+  export type RemovedReason = (typeof removedReasonOptions)[number]
+}
+```
+
+**Key points:**
+- **`const` + `declare namespace` merge** — `WidgetTagSchemas.widgetTagModel` is a Zod schema at runtime and a type at compile time.
+- **Only the final object is exported** — individual schemas are plain `const` declarations, keeping the public API surface explicit.
+- **Domain helpers reference the namespace type** — `declare namespace` is hoisted, so helpers can use `Pick<WidgetTagSchemas.widgetTagModel, ...>` even though the declaration appears below.
+
+```typescript
+import { WidgetTagSchemas } from 'my-schemas-package'
+
+const parsed = WidgetTagSchemas.createWidgetTagInput.parse(formData)
+function renderTag(t: WidgetTagSchemas.widgetTagAdminView) { ... }
+if (WidgetTagSchemas.isTagActive(tag)) { ... }
+```
+
+index.ts re-export each entity's namespace — one line per entity:
+
+```typescript
+// packages/schemas/src/index.ts
+export { WidgetTagSchemas } from './widget-tags'
+export { WidgetSchemas } from './widget'
+export { WidgetMetricSchemas } from './widget-metric'
+```
+
+### 2b. Enum Pattern
+
+Every enum uses a three-part structure. The options array is always the source of truth — never define values inside `z.enum()` directly.
+
+```typescript
+const priceUnitOptions = ['Hourly', 'Daily', 'Total'] as const          // 1. options array (source of truth)
+const priceUnits = enumOptionsToObject(priceUnitOptions)                 // 2. object for runtime lookups
+type PriceUnit = (typeof priceUnitOptions)[number]                       // 3. TypeScript type
+
+// Labels layered on as needed
+const priceUnitLabels = { Hourly: 'Per Hour', Daily: 'Per Day', Total: 'Fixed Price' } satisfies Record<PriceUnit, string>
+```
+---
+
+## 3. Layer 2: Database Providers
+
+Providers encapsulate ALL database access. They translate between SQL and typed domain objects using Zod schemas.
+
+**Providers are a private interface.** They must never be exported from the services package. External consumers (routes, other packages) access data exclusively through use cases. Only use cases may import and call providers directly.
+
+### 3a. Structure
+
+```typescript
+// packages/services/src/categories/category-db-data-provider.ts
+import { instantFns } from 'iso-fns2'
+import { CategorySchemas } from 'my-schemas-package'
+import { NotFoundError } from '@maestro-js/custom-errors'
+import { nonNullAsync } from '../../internals'
+import { Db } from 'maestro'
+
+// --- Mapping function: DB row → typed domain object ---
+function mapToCategory(raw: any) {
+  return CategorySchemas.categorySystemView.parse({
+    ...raw,
+    isDeleted: !!raw.isDeleted
+  })
+}
+
+// --- Query functions ---
+async function listByOrganizationId(organizationId: number) {
+  const results = await Db.select(
+    `SELECT * FROM categories WHERE organizationId = ?`,
+    [organizationId]
+  )
+  return results.map(mapToCategory)
+}
+
+async function getById(id: number) {
+  const results = await Db.select(
+    `SELECT * FROM categories WHERE id = ?`,
+    [id]
+  )
+  return results.length ? mapToCategory(results[0]) : null
+}
+
+// Strict variant — throws NotFoundError instead of returning null
+const getByIdStrict = nonNullAsync(getById)
+
+async function create(category: CategorySchemas.categoryUpdate) {
+  return await Db.transaction(async () => {
+    const insert = await Db.insert(
+      `INSERT INTO categories SET ?`,
+      [{ ...category, createdDate: instantFns.formatISO9075(instantFns.now()) }]
+    )
+    return getByIdStrict(insert.insertId)
+  })
+}
+
+async function deleteById(id: number) {
+  await Db.update(
+    `UPDATE categories SET deletedDate = ? WHERE id = ?`,
+    [instantFns.formatISO9075(instantFns.now()), id]
+  )
+}
+
+async function hardDeleteById(id: number) {
+  await Db.delete(`DELETE FROM categories WHERE id = ?`, [id])
+}
+
+// --- Export as plain object literal ---
+export const CategoryDbDataProvider = {
+  listByOrganizationId,
+  getById,
+  getByIdStrict,
+  create,
+  deleteById,
+  hardDeleteById
+}
+```
+
+### 3b. Naming Conventions (Strict)
+
+| Prefix         | Returns     | Behavior                              |
+| -------------- | ----------- | ------------------------------------- |
+| `get[X]`       | `T \| null` | Single item or null                   |
+| `get[X]Strict` | `T`         | Single item or throws `NotFoundError` |
+| `list[X]`      | `T[]`       | Array (empty array if none)           |
+| `create`       | `T`         | INSERT                                |
+| `update`       | `T`         | UPDATE                                |
+| `delete`       | `void`      | Soft delete (sets `deletedDate`)      |
+| `hardDelete`   | `void`      | Permanent DELETE                      |
+
+### 3c. Query Builder for Dynamic Filters
+
+```typescript
+import { Sql } from '@maestro-js/sql'
+
+async function listByFilter(filter: EntityFilter) {
+  const where = Sql.where()
+
+  if (filter.organizationId) {
+    where.and('organizationId = ?', [filter.organizationId])
+  }
+  if (filter.isArchived !== undefined) {
+    where.and('isArchived = ?', [filter.isArchived])
+  }
+  if (!filter.includeDeleted) {
+    where.and('deletedDate IS NULL')
+  }
+
+  const limit = filter.limit ?? 50
+  const results = await Db.select(
+    `SELECT * FROM widgets WHERE ${where.query} ORDER BY createdDate DESC LIMIT ?`,
+    [...where.parameters, limit]
+  )
+  return results.map(mapToWidget)
+}
+```
+
+`Sql.where()` creates a `WhereClauseBuilder` for constructing parameterized WHERE clauses incrementally. It provides:
+- `and(condition, params?)` — appends an AND clause (or a parenthesized group when given a callback)
+- `or(condition, params?)` — appends an OR clause (or a parenthesized group when given a callback)
+- `.query` — getter for the assembled WHERE clause string (returns `'TRUE'` if no conditions added)
+- `.parameters` — getter for the parameter array matching `?` placeholders
+
+### 3d. Rules
+
+1. **All SQL lives in providers** — use cases and routes never write SQL
+2. **Always parse results through Zod** — `Schema.parse(dbRow)` ensures runtime type safety
+3. **Use `nonNullAsync` for strict variants** — avoids null-check boilerplate in callers
+4. **Use transactions for multi-step writes** — `Db.transaction(async () => { ... })`
+5. **Soft delete by default** — set `deletedDate`, filter it in queries. Use `hardDelete` only when truly needed
+6. **Check array length before IN queries** — `if (!ids.length) return []` to avoid SQL syntax errors
+7. **Never export providers from the services package** — providers are internal to the services layer. Routes and other external consumers must go through use cases. Only use cases may import providers
+
+---
+
+## 4. Layer 3: Use Cases
+
+Use cases are the business logic layer. Each use case represents one complete user action and orchestrates providers, permissions, and side effects.
+
+### 4a. The Pattern: `z.function().implementAsync()`
+
+```typescript
+// packages/services/src/categories/category-use-case.ts
+import { z } from 'zod'
+import { CategorySchemas, UserSchemas } from 'my-schemas-package'
+import { ForbiddenError, ConflictError } from '@maestro-js/custom-errors'
+import { CategoryDbDataProvider } from './category-db-data-provider'
+
+export const ListCategoriesByOrganizationId = z
+  .function({ input: [z.number(), UserSchemas.Profile] })
+  .implementAsync(async (organizationId, profile) => {
+    // 1. Permission check
+    if (profile.clientType === 'ORG_USER' && !profile.organizationIds.includes(organizationId)) {
+      throw new ForbiddenError('Cannot list categories which are not yours')
+    }
+    // 2. Delegate to provider
+    return CategoryDbDataProvider.listByOrganizationId(organizationId)
+  })
+
+export const CreateCategory = z
+  .function({ input: [CategorySchemas.categoryUpdate, UserSchemas.Profile] })
+  .implementAsync(async (category, profile) => {
+    if (profile.clientType === 'ORG_USER' && !profile.organizationIds.includes(category.organizationId)) {
+      throw new ForbiddenError('Cannot create categories which are not yours')
+    }
+    return CategoryDbDataProvider.create(category)
+  })
+
+export const DeleteCategory = z
+  .function({ input: [z.number(), UserSchemas.Profile] })
+  .implementAsync(async (id, profile) => {
+    const category = await CategoryDbDataProvider.getByIdStrict(id)
+
+    if (profile.clientType === 'ORG_USER' && !profile.organizationIds.includes(category.organizationId)) {
+      throw new ForbiddenError('Cannot delete categories which are not yours')
+    }
+
+    // Business rule: can't delete if still referenced
+    const [products, accessories] = await Promise.all([
+      ProductDbDataProvider.listByCategoryId(category.id),
+      AccessoryDbProvider.listPublishedByCategoryId(category.id)
+    ])
+
+    if (products.length || accessories.length) {
+      throw new ConflictError('Cannot delete a category still associated with a product')
+    }
+
+    await CategoryDbDataProvider.deleteById(id)
+  })
+```
+
+### 4b. Permission Checks with Permissions.gate()
+
+For RBAC-style permission checks, use `Permissions.gate()` at the top of each use case:
+
+```typescript
+import { Permissions } from '@maestro-js/permissions'
+import { ForbiddenError } from '@maestro-js/custom-errors'
+
+export const UpdateWidget = z
+  .function({ input: [z.string(), WidgetSchemas.updateWidgetRequest, UserSchemas.Profile] })
+  .implementAsync(async (id, data, profile) => {
+    // Throws ForbiddenError if user can't update widgets
+    Permissions.gate(profile, 'widgets', 'update')
+
+    // Additional resource-level check
+    const existing = await widgetDbProvider.getByIdStrict(id)
+    if (profile.clientType === 'ORG_USER' && !profile.organizationIds.includes(existing.organizationId)) {
+      throw new ForbiddenError('Cannot update widgets which are not yours')
+    }
+
+    return widgetDbProvider.update(id, data)
+  })
+```
+
+The `Permissions` package follows the maestro service registry pattern. Set it up once at application boot:
+
+```typescript
+// app/boot.ts (or equivalent startup file)
+import { Permissions } from '@maestro-js/permissions'
+
+const driver = Permissions.drivers.static<UserSchemas.Profile>((profile, allow, forbid) => {
+  if (profile.role === 'admin') {
+    allow('widgets', ['create', 'read', 'update', 'delete'])
+    allow('categories', ['create', 'read', 'update', 'delete'])
+  }
+  if (profile.role === 'member') {
+    allow('widgets', ['create', 'read', 'update'])
+    allow('categories', 'read')
+  }
+})
+
+const service = Permissions.Provider.create({ driver })
+Permissions.Provider.register('default', service)
+```
+
+### 4c. Exporting Use Cases as Services
+
+Group related use cases into a service export:
+
+```typescript
+// packages/services/src/categories/index.ts
+export * as CategoryService from './category-use-case'
+```
+
+Routes call individual use cases through the service namespace:
+
+```typescript
+// Express
+routes.get('/:id', async (req, res) => {
+  const category = await CategoryService.GetCategoryById(Number(req.params.id), res.locals.profile)
+  res.json(category)
+})
+
+// Remix
+export const action = async ({ request }: ActionFunctionArgs) => {
+  const profile = await getProfileStrict(request)
+  const formData = await request.formData()
+  const data = CategorySchemas.categoryUpdate.parse(Object.fromEntries(formData))
+  await CategoryService.CreateCategory(data, profile)
+  return redirect('/categories')
+}
+```
+
+### 4d. Rules
+
+1. **Always use `z.function().implementAsync()`** — provides input validation and type inference
+2. **Exactly two parameters** — use cases always accept exactly two inputs: the domain data as the first parameter and `UserSchemas.Profile` as the second parameter. Never add a third parameter; combine related domain inputs into a single object if needed
+3. **Profile is always the second parameter** — every use case receives the actor's profile as its second argument, keeping business input cleanly separated from auth context
+4. **Always check permissions first** — via `Permissions.gate()` or inline checks
+5. **Never write raw SQL** — delegate to providers
+6. **One use case = one complete user action** — the front-end calls ONE use case, not many
+7. **Large use cases are fine** — prefer one comprehensive use case over fragmenting a workflow across multiple
+8. **Hard dependencies only** — import providers directly, no dependency injection or mocking
+
+---
+
+## 5. Supporting Utilities
+
+### 5a. `nonNullAsync`
+
+Wraps an async function so it throws instead of returning null:
+
+```typescript
+import { NotFoundError } from '@maestro-js/custom-errors'
+
+export function nonNullAsync<T extends (...args: any) => any>(
+  func: T
+): (...args: Parameters<T>) => Promise<Exclude<Awaited<ReturnType<T>>, null>> {
+  return async function (...args: any) {
+    const res = await func(...args)
+    if (res === null) throw new NotFoundError()
+    return res
+  }
+}
+
+// Usage in a provider:
+async function getById(id: number) { ... } // returns T | null
+const getByIdStrict = nonNullAsync(getById) // returns T or throws
+```
+
+### 5b. `@maestro-js/custom-errors`
+
+Provides pre-built error classes with HTTP status codes for common failure modes. Each error carries an `httpStatusCode` property that the route layer uses to map to the correct HTTP response.
+
+**Pre-built errors used in this architecture:**
+
+| Error             | HTTP Status | Used For                                                      |
+| ----------------- | ----------- | ------------------------------------------------------------- |
+| `NotFoundError`   | 404         | Entity not found (thrown by `nonNullAsync`, strict providers) |
+| `ForbiddenError`  | 403         | Unauthorized resource access (inline ownership checks)        |
+| `ConflictError`   | 409         | Business rule violations (e.g., deleting referenced entities) |
+| `BadRequestError` | 400         | Invalid input that passes Zod but fails a business rule       |
+
+**Route-layer error handling:**
+
+```typescript
+import { CustomErrors } from '@maestro-js/custom-errors'
+
+app.use((err, req, res, next) => {
+  const status = CustomErrors.getHttpStatusCode(err) ?? 500
+  res.status(status).json({ error: err.message })
+})
+```
+
+**Creating domain-specific errors with `CustomErrors.create()`:**
+
+For errors that need structured input or domain-specific names, use the factory:
+
+```typescript
+import { CustomErrors } from '@maestro-js/custom-errors'
+
+const InsufficientInventoryError = CustomErrors.create({
+  name: 'InsufficientInventoryError',
+  message: (input: { requested: number; available: number }) =>
+    `Requested ${input.requested} but only ${input.available} available`,
+  httpStatusCode: 'conflict' as const
+})
+
+// Usage
+throw new InsufficientInventoryError({ requested: 10, available: 3 })
+```
+
+This is how `@maestro-js/permissions` defines its `PermissionsError` — a domain-specific forbidden error with structured `action` and `subject` attributes.
+
+---
+
+## 6. How It All Connects
+
+### Directory Structure
+
+```
+packages/
+├── schemas/                       # All domain types and validation
+│   └── src/
+│       ├── widget/
+│       │   ├── widget-model.ts                # Layer A: DB columns
+│       │   ├── widget-system-view.ts          # Layer B: extended for API
+│       │   ├── create-widget-request.ts       # Layer C: mutation input
+│       │   ├── update-widget-request.ts
+│       │   ├── widget-admin-view.ts
+│       │   └── index.ts                       # Barrel export
+│       ├── user/
+│       │   └── profile.ts                         # UserSchemas.Profile
+│       └── index.ts                               # Top-level barrel
+└── services/                      # Providers + Use Cases
+    └── src/
+        └── widget/
+            ├── widget-db-provider.ts           # Data access (internal — never exported)
+            ├── widget-use-case.ts              # Business logic (public via index.ts)
+            ├── widget-use-case.test.ts         # Tests (no mocks)
+            └── index.ts                        # export * as WidgetService (use cases only)
+        └── utils/
+            └── make-non-null.ts                    # nonNullAsync
+```
+
+### Request Lifecycle
+
+```
+1. Route receives HTTP request
+2. Route extracts user profile from auth middleware
+3. Route calls: CategoryService.CreateCategory(parsedBody, profile)
+4. Use case validates inputs via z.function() args
+5. Use case calls Permissions.gate(profile, 'categories', 'create')
+6. Use case calls CategoryDbDataProvider.create(category)
+7. Provider runs SQL INSERT inside a transaction
+8. Provider calls Schema.parse(dbRow) on the result
+9. Typed result flows back up through use case → route → HTTP response
+```

package/skills/maestro-examples/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: maestro-examples
+description: "Three complete reference applications built with @maestro-js. Use when building a new app, scaffolding features, writing routes/components, setting up infrastructure, or needing a working example of any maestro pattern. Covers authentication (password and magic link), permissions, multi-tenancy, file uploads, queues, recurring jobs, email templates, drag-and-drop, and full-stack React Router + maestro integration."
+---
+
+# Maestro Example Applications
+
+Three production-style reference apps demonstrating how to build full-stack applications with @maestro-js and React Router. Each app is a complete monorepo with schemas, services, web frontend, configuration, infrastructure, and tests.
+
+## When to read these references
+
+- Scaffolding a new app or feature — read the closest app's full structure
+- Writing a specific layer (schema, provider, use case, route) — read that file in any app
+- Setting up maestro services — read any app's `packages/services/src/maestro.ts`
+- Writing migrations — read any app's `infrastructure/db-migrations/sqls/`
+- Writing e2e tests — read any app's `*-web/tests/`
+- Setting up a queue processor — read setlist's `queue-processor/`
+- Writing email templates — read chorus or setlist's `packages/email-templates/`
+
+## App Overview
+
+### Cadence — Multi-tenant CRM
+`references/cadence/`
+
+A contact management system with organizations, users, contacts, interactions, and tags.
+
+**Unique patterns:**
+- Multi-tenant data isolation (org-scoped queries)
+- Password authentication with remember-me tokens
+- Role-based permissions via `@maestro-js/permissions` (admin/member/viewer)
+- Rich text editor for interaction notes
+- Server-side table with filtering, sorting, and pagination
+- Tag autocomplete system
+
+**Key files:**
+- `packages/schemas/src/` — 4 domain schemas (contact, interaction, organization, user)
+- `packages/services/src/maestro.ts` — Full boot with Password, Auth, Permissions, Mail (SES)
+- `packages/services/src/permissions.ts` — RBAC permission rules
+- `packages/services/src/contact/` — Canonical provider + use case example
+- `cadence-web/app/routes/contacts.tsx` — Server table with filters
+- `cadence-web/app/routes/contacts.new.tsx` — Form action pattern
+- `cadence-web/app/components/table/` — Reusable table system
+- `cadence-web/app/features/` — Middleware (CSRF, rate limiting, security headers)
+- `config/` — Per-service configuration files
+
+---
+
+### Chorus — Community Discussion Platform
+`references/chorus/`
+
+A Reddit/forum-style app with channels, posts, replies, likes, and image uploads.
+
+**Unique patterns:**
+- File uploads to S3 (`@maestro-js/file-storage`)
+- Image grid display (Twitter-style 1-4 image layouts)
+- Like/unlike toggle
+- Content moderation (hiding posts, moderator roles)
+- Channel ownership and transfer
+- Email templates with React (password reset)
+- Nested route layouts (`c.$slug/` with `_layout.tsx`)
+
+**Key files:**
+- `packages/schemas/src/` — 4 domain schemas (channel, post, like, profile)
+- `packages/services/src/maestro.ts` — Boot with file storage (S3) in addition to standard services
+- `packages/services/src/post/redact-hidden-post.ts` — Content filtering pattern
+- `packages/services/src/channel/channel-use-cases.ts` — Ownership/moderator permission checks
+- `chorus-web/app/routes/c.$slug/` — Nested route layout pattern
+- `chorus-web/app/routes/api/like.$postId.tsx` — Fetcher action (no navigation)
+- `chorus-web/app/components/post-composer.tsx` — File upload component
+- `chorus-web/app/components/image-grid.tsx` — Responsive image layout
+- `packages/email-templates/` — React email template system
+
+---
+
+### Setlist — Personal Task Manager
+`references/setlist/`
+
+A Things-style task manager with areas, projects, tasks, drag-and-drop reordering, and a background queue processor.
+
+**Unique patterns:**
+- Magic link authentication (no passwords)
+- Background queue processor (separate Node.js service)
+- Recurring jobs (cron-scheduled cleanup)
+- Drag-and-drop reordering with fractional position tracking
+- Inline task creation
+- Single-user model (no multi-tenancy or roles)
+- API-only routes (fetcher actions, no loaders)
+
+**Key files:**
+- `packages/schemas/src/` — 5 domain schemas (area, project, task, user, magic-link) + `position.ts` utility
+- `packages/services/src/maestro.ts` — Boot with magic link auth (no Password provider)
+- `packages/services/src/auth/verify-magic-link-credentials.ts` — Custom credential verifier
+- `packages/services/src/task/task-db-provider.ts` — Position-based reordering queries
+- `queue-processor/src/index.ts` — Queue worker with graceful shutdown
+- `queue-processor/src/recurring-jobs.ts` — Cron job definitions
+- `setlist-web/app/routes/api/` — API-only action routes (tasks, projects, areas CRUD + reorder)
+- `setlist-web/app/components/task-list/` — DnD task list with keyboard support
+- `setlist-web/app/components/sidebar/` — DnD sidebar with sortable areas/projects
+- `setlist-web/app/hooks/` — Action hooks (use-task-actions, use-area-actions, use-project-actions)
+- `packages/email-templates/` — Magic link email template
+
+---
+
+## Common Structure
+
+All three apps share this monorepo layout:
+
+```
+app-name/
+├── package.json + tsconfig.json
+├── config/                          # Per-service env config
+├── infrastructure/
+│   ├── cdk/                         # AWS CDK stack
+│   └── db-migrations/
+│       ├── *.ts                     # Migration runner files
+│       └── sqls/*.sql               # Up/down SQL scripts
+├── packages/
+│   ├── schemas/src/                 # Zod schemas (model, views, inputs)
+│   ├── services/src/
+│   │   ├── maestro.ts               # Service boot/registration
+│   │   ├── permissions.ts           # Permission rules (if applicable)
+│   │   └── [domain]/
+│   │       ├── [domain]-db-provider.ts
+│   │       ├── [domain]-use-cases.ts
+│   │       └── index.ts
+│   └── email-templates/src/         # React email templates (chorus, setlist)
+├── [app]-web/
+│   ├── app/
+│   │   ├── root.tsx
+│   │   ├── routes.ts
+│   │   ├── services.server.ts       # Re-exports services for route imports
+│   │   ├── routes/                  # React Router routes (loaders + actions)
+│   │   ├── components/              # UI components
+│   │   ├── features/                # Server middleware
+│   │   └── utils/                   # Client utilities and hooks
+│   └── tests/                       # Playwright e2e tests
+├── queue-processor/                 # Background worker (setlist only)
+├── specs/                           # App requirements and data model docs
+└── scripts/                         # One-off utilities
+```