@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/architecture/api-design.md

@@ -0,0 +1,212 @@
+# API Design and Client Patterns
+
+## Core Rules
+
+- API types are generated or inferred — never duplicated by hand
+- Validate at the boundary on both sides (server validates incoming, client validates responses)
+- Use a consistent error response shape across all endpoints
+- Versioning is explicit when contracts change in breaking ways
+- Mock servers in development — do not block frontend work on backend availability
+
+## Choosing an API Layer
+
+| Approach | Use when |
+|---|---|
+| **tRPC** | Same team owns FE and BE, both in TypeScript — end-to-end type safety, no codegen step |
+| **OpenAPI + generated client** | Polyglot backend, public API, or external consumers |
+| **GraphQL** | Many client types with different field needs, or complex relational queries |
+| **Hand-written REST + Zod** | Small project, no FE/BE coordination needed, simple endpoints |
+
+Pick one per service. Mixing approaches creates two type pipelines to maintain.
+
+## tRPC Pattern
+
+```ts
+// server/router.ts
+import { initTRPC } from "@trpc/server";
+import { z } from "zod";
+
+const t = initTRPC.create();
+
+export const appRouter = t.router({
+  invoice: t.router({
+    list: t.procedure
+      .input(z.object({ status: z.enum(["all", "open", "paid"]).default("all") }))
+      .query(({ input }) => db.invoice.findMany({ where: { status: input.status } })),
+
+    create: t.procedure
+      .input(createInvoiceSchema)
+      .mutation(({ input, ctx }) =>
+        db.invoice.create({ data: { ...input, userId: ctx.userId } }),
+      ),
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+```ts
+// client — types flow from the server router definition
+const invoices = await trpc.invoice.list.query({ status: "open" });
+// invoices is fully typed; no manual DTO
+```
+
+## OpenAPI Pattern
+
+For polyglot or public APIs:
+
+```bash
+# Generate a typed client from an OpenAPI spec
+pnpm dlx openapi-typescript ./openapi.yaml -o ./src/lib/api-types.ts
+```
+
+Use a small fetch wrapper that validates with the generated types:
+
+```ts
+import type { paths } from "~/lib/api-types";
+import createClient from "openapi-fetch";
+
+export const api = createClient<paths>({ baseUrl: env.VITE_API_BASE_URL });
+
+const { data, error } = await api.GET("/invoices", { params: { query: { status: "open" } } });
+```
+
+## Hand-Written Fetch + Zod
+
+For small projects without a generated client:
+
+```ts
+import { z } from "zod";
+
+const invoiceSchema = z.object({ id: z.string(), title: z.string(), amount: z.number() });
+const invoicesResponseSchema = z.object({ items: invoiceSchema.array(), nextCursor: z.string().nullable() });
+
+export async function fetchInvoices(cursor?: string) {
+  const url = new URL("/api/invoices", env.VITE_API_BASE_URL);
+  if (cursor) url.searchParams.set("cursor", cursor);
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new ApiError(response.status, await response.text());
+  }
+  return invoicesResponseSchema.parse(await response.json());
+}
+```
+
+## Standard Error Response Shape
+
+Use one error shape across all endpoints:
+
+```ts
+// shared/schemas/api-error.schema.ts
+export const apiErrorSchema = z.object({
+  error: z.object({
+    code: z.string(),              // machine-readable: "NOT_FOUND", "VALIDATION_FAILED"
+    message: z.string(),           // human-readable, safe to show
+    details: z.record(z.unknown()).optional(),  // field errors, etc.
+    requestId: z.string().optional(),
+  }),
+});
+```
+
+Server example:
+
+```ts
+return res.status(422).json({
+  error: {
+    code: "VALIDATION_FAILED",
+    message: "Some fields are invalid",
+    details: result.error.flatten().fieldErrors,
+    requestId: req.id,
+  },
+});
+```
+
+## Pagination
+
+Prefer **cursor-based pagination** for performance and stability with mutable datasets:
+
+```ts
+// Request: GET /invoices?cursor=eyJpZCI6...&limit=20
+// Response:
+{
+  items: Invoice[],
+  nextCursor: string | null,  // null when at end
+}
+```
+
+Use **offset/page pagination** only for small, stable datasets where the user expects page numbers (admin tables, search results).
+
+## Versioning
+
+When making a breaking change:
+
+- **Additive change** (new optional field, new endpoint) — no version bump needed
+- **Breaking change** (removed field, changed type, removed endpoint) — bump the API version
+
+Common strategies:
+- URL prefix: `/v1/invoices`, `/v2/invoices`
+- Header: `Accept: application/vnd.acme.v2+json`
+
+Keep the old version working for one deprecation cycle (typically 1–2 releases). Document the migration path.
+
+## Mock Servers
+
+Frontend should never be blocked on backend availability.
+
+Options:
+- **MSW** (Mock Service Worker) — intercepts fetch at the browser/Node level; same handlers in tests and dev
+- **Prism** — runs an OpenAPI spec as a mock server
+- **tRPC** — type-safe mocks via `@trpc/react-query`'s `createTRPCMsw`
+
+```ts
+// MSW handler
+import { http, HttpResponse } from "msw";
+
+export const handlers = [
+  http.get("/api/invoices", () =>
+    HttpResponse.json({
+      items: [{ id: "1", title: "Q4 Report", amount: 500 }],
+      nextCursor: null,
+    }),
+  ),
+];
+```
+
+## Idempotency
+
+For mutations that might be retried (network errors, optimistic UI), accept an `Idempotency-Key` header so the same request can be safely sent twice:
+
+```ts
+// Client
+await api.POST("/invoices", {
+  body: invoice,
+  headers: { "Idempotency-Key": crypto.randomUUID() },
+});
+```
+
+The server deduplicates on this key for some window (e.g., 24 hours).
+
+## DO NOT
+
+- Hand-write FE types that mirror BE types — generate or infer instead
+- Return different error shapes from different endpoints
+- Mix snake_case and camelCase in the same API surface
+- Expose internal IDs / database errors / stack traces in error responses
+- Skip mocking in development — it slows everyone down
+
+## PRIORITY
+
+```
+Generated types > Hand-written DTOs
+Cursor pagination > Offset pagination
+Mock-first frontend > Blocked-on-backend frontend
+```
+
+## See Also
+
+- [`typescript/validation.md`](../typescript/validation.md) — schema-driven validation
+- [`security/api-security.md`](../security/api-security.md) — status codes, rate limiting, CORS
+- [`security/validation.md`](../security/validation.md) — input validation at boundaries
+- [`tooling/tanstack-query.md`](../tooling/tanstack-query.md) — TanStack Query patterns
+- [`tooling/tanstack-router.md`](../tooling/tanstack-router.md) — route loaders, typed search params

package/templates/standards/architecture/dependency-boundaries.md

@@ -0,0 +1,104 @@
+# Dependency Boundaries
+
+## Core Rule
+
+Features must not depend on each other. Features depend on `shared/`. `shared/` depends on nothing internal.
+
+## Allowed Dependencies
+
+```
+apps/web       → packages/ui, packages/schemas
+apps/api       → packages/schemas
+features/X     → shared/
+features/X     → lib/
+shared/        → lib/
+lib/           → external packages only
+packages/*     → external packages only (no internal app code)
+```
+
+## Forbidden Dependencies
+
+```
+features/invoices  → features/users      ✗ cross-feature import
+packages/ui        → apps/web            ✗ package depends on app
+shared/            → features/           ✗ shared depends on feature
+```
+
+## In Practice
+
+If feature A needs something from feature B:
+
+**Option 1: Move it to `shared/`**
+- Move the shared concept to `shared/`
+- Both features import from `shared/`
+
+**Option 2: Pass it as a prop or callback**
+- Feature A receives the data it needs via props
+- Feature B provides the data at the composition layer (page, layout)
+
+**Option 3: Use a shared store or context**
+- If it is runtime state (current user, theme), put it in context or Zustand
+- Both features read from the same source
+
+## Detecting Violations
+
+In a monorepo, use Nx's enforcement:
+
+```json
+// nx.json
+{
+  "targetDefaults": {
+    "lint": {
+      "configurations": {
+        "enforce-boundaries": true
+      }
+    }
+  }
+}
+```
+
+In a single app, use ESLint's `import/no-restricted-paths`:
+
+```js
+// eslint.config.js
+{
+  rules: {
+    "import/no-restricted-paths": ["error", {
+      zones: [
+        {
+          target: "./src/features",
+          from: "./src/features",
+          except: ["./src/features/invoices"], // each feature only allows itself
+        },
+      ],
+    }],
+  }
+}
+```
+
+## Circular Dependencies
+
+Circular dependencies are always forbidden. They indicate a design problem.
+
+Common causes:
+- `shared/` importing from a feature
+- Two features that should be combined into one
+- Missing abstraction that should be in `shared/`
+
+Use `madge` to detect cycles:
+
+```bash
+pnpm dlx madge --circular src/
+```
+
+## PRIORITY
+
+```
+Isolation > Convenience > DRY
+```
+
+## See Also
+
+- [`feature-driven.md`](feature-driven.md) — feature ownership
+- [`shared-code.md`](shared-code.md) — what belongs in `shared/`
+- [`monorepos.md`](monorepos.md) — package-level boundaries

package/templates/standards/architecture/feature-driven.md

@@ -0,0 +1,102 @@
+# Feature-Driven Architecture
+
+## Core Rule
+
+Organize code by feature, not by type. A feature owns everything it needs.
+
+## Structure
+
+```
+src/
+  features/
+    invoices/
+      InvoiceTable.tsx        ← component
+      InvoiceTable.test.tsx   ← test colocated
+      InvoiceFilters.tsx
+      InvoiceRow.tsx
+      useInvoiceSort.ts       ← hook used only in this feature
+      invoice.schema.ts       ← Zod schemas for this feature
+      invoice.api.ts          ← data fetching for this feature
+      invoice.types.ts        ← types not derivable from schema
+    users/
+      UserProfile.tsx
+      useCurrentUser.ts
+      user.schema.ts
+  shared/
+    components/               ← reused across 3+ features
+    hooks/
+    schemas/
+    utils/
+  app/                        ← routing, layout, providers
+```
+
+## What Goes in a Feature
+
+A feature folder contains everything the feature needs that is not shared with other features:
+
+- Components (primary + sub-components)
+- Hooks specific to this feature
+- API functions
+- Zod schemas and inferred types
+- Tests
+- Constants used only here
+
+## What Belongs in `shared/`
+
+Move to `shared/` only when:
+- Used by 3 or more distinct features
+- The shared nature is expected to be permanent, not incidental
+
+Never move something to `shared/` preemptively.
+
+## DO NOT
+
+- Organize by type at the root level (`components/`, `hooks/`, `types/`) for a large app
+- Import from another feature's internals directly
+- Create a `utils/` catch-all that accumulates unrelated helpers over time
+
+## Feature Communication
+
+Features must not import from each other's internals. If two features share a concept:
+
+1. Move the shared concept to `shared/`
+2. Both features import from `shared/`
+
+```
+features/
+  invoices/
+    invoice.schema.ts   ← imports User from shared/schemas/user.schema.ts
+  users/
+    user.schema.ts      ← defined here, re-exported from shared/
+shared/
+  schemas/
+    user.schema.ts      ← canonical location for shared User schema
+```
+
+## Scaling
+
+As the app grows, features can be grouped by domain:
+
+```
+features/
+  billing/
+    invoices/
+    payments/
+    subscriptions/
+  crm/
+    contacts/
+    companies/
+```
+
+## PRIORITY
+
+```
+Feature isolation > Shared reuse > Organizational elegance
+```
+
+## See Also
+
+- [`shared-code.md`](shared-code.md) — what belongs in `shared/`
+- [`folder-structure.md`](folder-structure.md) — canonical folder maps
+- [`dependency-boundaries.md`](dependency-boundaries.md) — feature isolation rules
+- [`../philosophy/maintainability.md`](../philosophy/maintainability.md) — colocation principle

package/templates/standards/architecture/folder-structure.md

@@ -0,0 +1,108 @@
+# Folder Structure
+
+## React App (Single Repo)
+
+```
+src/
+  app/                      ← routing, layout, root providers
+    layout.tsx
+    providers.tsx
+    router.tsx
+  features/                 ← feature-driven modules
+    invoices/
+      InvoiceTable.tsx
+      InvoiceTable.test.tsx
+      useInvoiceSort.ts
+      invoice.schema.ts
+      invoice.api.ts
+    users/
+      UserProfile.tsx
+      user.schema.ts
+  shared/                   ← reused across 3+ features
+    components/
+      Button.tsx
+      Modal.tsx
+    hooks/
+      useDebounce.ts
+    schemas/
+      pagination.schema.ts
+    utils/
+      format-currency.ts
+  lib/                      ← third-party adapter layer
+    db.ts
+    auth.ts
+    stripe.ts
+  styles/
+    globals.css
+  main.tsx
+```
+
+## Next.js App (App Router)
+
+```
+app/                        ← Next.js App Router
+  (auth)/
+    login/
+      page.tsx
+  (dashboard)/
+    invoices/
+      page.tsx
+      [id]/
+        page.tsx
+  layout.tsx
+  providers.tsx
+src/                        ← application code (same as above)
+  features/
+  shared/
+  lib/
+public/
+```
+
+## Monorepo
+
+```
+apps/
+  web/                      ← frontend app
+    src/
+      features/
+      shared/
+      lib/
+  api/                      ← backend app
+    src/
+      routes/
+      services/
+      lib/
+packages/
+  ui/                       ← shared component library
+  schemas/                  ← shared Zod schemas
+  tsconfig/
+  eslint-config/
+  biome-config/
+nx.json
+pnpm-workspace.yaml
+```
+
+## Rules
+
+- Feature folders are flat by default — add sub-folders only when a feature grows large
+- `shared/` files are named by purpose, not by type: `format-currency.ts` not `string-utils.ts`
+- `lib/` contains only external service adapters — no business logic
+- Tests live next to the code they test, not in a separate `__tests__/` directory
+- Use `index.ts` barrel exports sparingly — only at feature boundaries, not inside features
+
+## File Naming
+
+| Type | Convention | Example |
+|---|---|---|
+| React components | `PascalCase.tsx` | `InvoiceTable.tsx` |
+| Hooks | `camelCase.ts` | `useInvoiceSort.ts` |
+| Schemas | `kebab-case.schema.ts` | `invoice.schema.ts` |
+| API functions | `kebab-case.api.ts` | `invoice.api.ts` |
+| Utilities | `kebab-case.ts` | `format-currency.ts` |
+| Tests | same name + `.test.ts(x)` | `InvoiceTable.test.tsx` |
+
+## See Also
+
+- [`feature-driven.md`](feature-driven.md) — feature folder anatomy
+- [`shared-code.md`](shared-code.md) — `shared/` vs `lib/`
+- [`dependency-boundaries.md`](dependency-boundaries.md) — import rules between layers

package/templates/standards/architecture/monorepos.md

@@ -0,0 +1,107 @@
+# Monorepos
+
+## Preferred Tooling
+
+- **Nx** — build system, task orchestration, generators, affected commands
+- **pnpm** — package manager (workspaces, efficient storage, strict linking)
+
+## When to Use a Monorepo
+
+Use a monorepo when:
+- A frontend and backend share types or schemas
+- Multiple apps share a component library
+- A team maintains more than one deployable unit with significant shared code
+
+Do not add monorepo tooling to a single-app project speculatively.
+
+## Workspace Structure
+
+```
+apps/
+  web/              ← Next.js / Remix frontend
+  api/              ← Express / Hono / tRPC backend
+packages/
+  ui/               ← shared component library
+  schemas/          ← shared Zod schemas (FE + BE)
+  tsconfig/         ← shared tsconfig presets
+  eslint-config/    ← shared ESLint config
+  biome-config/     ← shared Biome config
+```
+
+Group packages by domain when scaling:
+
+```
+packages/
+  frontend/
+    ui/
+    design-tokens/
+  backend/
+    database/
+    email/
+  shared/
+    schemas/
+    utils/
+```
+
+## Nx Setup
+
+```bash
+pnpm dlx create-nx-workspace@latest acme --preset=ts
+```
+
+Key Nx commands:
+
+```bash
+nx build web                    # build a specific project
+nx test api                     # test a specific project
+nx affected --target=build      # build only changed projects
+nx graph                        # visualize dependency graph
+nx generate @nx/react:component # generate a component
+```
+
+## pnpm Workspaces
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - "apps/*"
+  - "packages/*"
+```
+
+Use workspace protocol for internal dependencies:
+
+```json
+{
+  "dependencies": {
+    "@acme/schemas": "workspace:*",
+    "@acme/ui": "workspace:*"
+  }
+}
+```
+
+## Dependency Rules
+
+- Apps may depend on packages
+- Packages must not depend on apps
+- Packages should not depend on other packages unless the dependency is stable and intentional
+- Use `nx graph` to audit the dependency graph
+- Circular dependencies are forbidden
+
+## DO NOT
+
+- Create publishable packages unless explicitly required for external consumption
+- Add unnecessary inter-package dependencies
+- Bypass the monorepo's package boundaries with relative imports across app/package boundaries
+- Use `npm` or `yarn` in a pnpm workspace
+
+## PRIORITY
+
+```
+Feature isolation > Build efficiency > Package granularity
+```
+
+## See Also
+
+- [`../tooling/nx.md`](../tooling/nx.md) — Nx commands and configuration
+- [`dependency-boundaries.md`](dependency-boundaries.md) — cross-package rules
+- [`../tooling/ci.md`](../tooling/ci.md) — `nx affected` in CI