create-restack-pattern 0.1.5 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/template/AGENTS.md +62 -0
package/package.json
CHANGED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
This file provides architecture, build, and styling guidance to Claude Code (claude.ai/code) and other AI assistants working in this repository.
|
|
4
|
+
|
|
5
|
+
## Project Stack
|
|
6
|
+
- **Frontend**: Next.js 16 (App Router)
|
|
7
|
+
- **Backend**: Hono
|
|
8
|
+
- **ORM**: Drizzle ORM
|
|
9
|
+
- **Database**: PostgreSQL (Postgres-js driver)
|
|
10
|
+
- **Validation**: Zod (shared schemas)
|
|
11
|
+
- **Package Manager**: pnpm workspaces
|
|
12
|
+
|
|
13
|
+
## Monorepo Layout
|
|
14
|
+
- `frontend/` — Next.js 16 App Router
|
|
15
|
+
- `backend/` — Hono API
|
|
16
|
+
- `packages/shared/` — Shared Zod schemas (the single source of truth)
|
|
17
|
+
|
|
18
|
+
## Build and Dev Commands
|
|
19
|
+
All commands should be run from the repository root:
|
|
20
|
+
- `pnpm install` — Install all dependencies
|
|
21
|
+
- `pnpm --filter @restack/shared build` — Build shared Zod schemas (run first!)
|
|
22
|
+
- `pnpm --filter backend dev` — Start Hono dev server on port 3001
|
|
23
|
+
- `pnpm --filter frontend dev` — Start Next.js dev server on port 3000
|
|
24
|
+
- `pnpm --filter backend db:push` — Push Drizzle schema to PostgreSQL database
|
|
25
|
+
- `pnpm --filter backend db:studio` — Open Drizzle Studio database viewer
|
|
26
|
+
- `pnpm --filter backend test` — Run Vitest tests
|
|
27
|
+
|
|
28
|
+
## Architecture Rules: Semi-DDD (Feature-Driven)
|
|
29
|
+
Code is organized by business domain/feature, not by file type.
|
|
30
|
+
|
|
31
|
+
### Backend Layout (`backend/src/domains/[feature]/`)
|
|
32
|
+
Each domain has 4 primary files:
|
|
33
|
+
- `[feature].routes.ts` — HTTP endpoints & input validation (imports Zod schema from `@restack/shared`)
|
|
34
|
+
- `[feature].service.ts` — Pure business logic only (no direct DB access)
|
|
35
|
+
- `[feature].repo.ts` — Drizzle queries only (no business logic)
|
|
36
|
+
- `[feature].model.ts` — Drizzle table definitions
|
|
37
|
+
|
|
38
|
+
**Cross-Domain Dependency Rule**: The `auth` domain may import from `user` (e.g. `usersTable` from `user.model.ts`). The reverse (user importing from auth) is STRICTLY FORBIDDEN.
|
|
39
|
+
|
|
40
|
+
### Frontend Layout (`frontend/domains/[feature]/`)
|
|
41
|
+
- `components/` — UI components (no direct data fetching)
|
|
42
|
+
- `hooks/` — Reactive state & data fetching logic
|
|
43
|
+
- `services/` — Thin HTTP wrappers around `apiClient`
|
|
44
|
+
- `types.ts` — Local TS type declarations
|
|
45
|
+
- `frontend/app/` is strictly for layout, routing config, metadata, or entry gates. Do not implement custom JSX layouts, forms, state, or complex components here. Always delegate rendering to domain feature components.
|
|
46
|
+
|
|
47
|
+
## Critical Gotcha: Shared Package Build Requirement
|
|
48
|
+
`@restack/shared`'s `package.json` resolves to `dist/`, which is gitignored. When editing Zod schemas in `packages/shared/src/schemas/`, you MUST compile them by running:
|
|
49
|
+
`pnpm --filter @restack/shared build`
|
|
50
|
+
(or keep `pnpm --filter @restack/shared dev` watch mode running in a terminal) or the frontend and backend will fail to resolve the updated types or throw compilation errors.
|
|
51
|
+
|
|
52
|
+
## Auth & Cookie Strategy
|
|
53
|
+
- Short-lived JWT `access_token` (15m) and opaque `refresh_token` (30d) are both set as `httpOnly` cookies at `Path=/`.
|
|
54
|
+
- Access tokens are automatically refreshed by the client-side `apiClient` on a 401 response.
|
|
55
|
+
- Cookie configuration: `SameSite=None` in production (requires `Secure=true`), and `SameSite=Lax` in development (`Secure=false` since local dev runs on HTTP).
|
|
56
|
+
- There is no server-side auth gate (`middleware.ts`/`proxy.ts`) because cookies cannot be read server-side when frontend and backend deploy to unrelated domains (Topology B). Authenticated routes are protected via backend `requireAuth` middleware, and frontend pages are protected via `<RequireAuth>` or client-side checks in hooks.
|
|
57
|
+
|
|
58
|
+
## Structured & Correlation Logging
|
|
59
|
+
- Every incoming HTTP request is tagged with a unique `requestId` via Hono's `requestId` middleware.
|
|
60
|
+
- A request-scoped child logger (`logger.child({ requestId })`) is bound to Hono's context.
|
|
61
|
+
- In route handlers, always extract the request-specific child logger from Hono's context (`c.get("logger") || logger`) to log events. This ensures all logs generated during a request carry the correct `requestId` and `userId` context (which is automatically enriched by the `requireAuth` middleware).
|
|
62
|
+
|