create-restack-pattern 0.1.0 → 0.1.4

package/README.md

@@ -1,8 +1,12 @@
 # create-restack-pattern
 
-Scaffold a new Next.js + Hono + Drizzle ORM monorepo using the Restack Pattern
-(Semi-DDD / Feature-Driven) architecture — the same template built out in
-[the main repo](../../README.md), bundled as a copy-and-go generator.
+[![npm version](https://img.shields.io/npm/v/create-restack-pattern.svg)](https://www.npmjs.com/package/create-restack-pattern)
+[![npm license](https://img.shields.io/npm/l/create-restack-pattern.svg)](https://www.npmjs.com/package/create-restack-pattern)
+[![node version](https://img.shields.io/node/v/create-restack-pattern.svg)](https://nodejs.org)
+
+Skip the boilerplate — scaffold a full-stack Next.js + Hono + PostgreSQL monorepo with secure auth cookies, structured logging, and a type-safe Hono RPC client end-to-end, all wired up and ready to deploy.
+
+This is the official initializer for the [Restack Pattern](https://github.com/NicholasChandraa/restack-pattern).
 
 ## Usage
 
@@ -10,63 +14,86 @@ Scaffold a new Next.js + Hono + Drizzle ORM monorepo using the Restack Pattern
 npx create-restack-pattern my-app
 ```
 
-Or without an argument, it'll prompt for a project name:
-
+Or run it without arguments to be prompted for a project name:
 ```bash
 npx create-restack-pattern
 ```
 
-This will:
+### Prerequisites
+- **Node.js**: version 20 or higher
+- **pnpm**: package manager installed (run `npm install -g pnpm` if needed)
+- **PostgreSQL**: a running database (either a local instance or a free hosted instance on [Neon](https://neon.tech))
 
-1. Copy the template into `./my-app`
-2. Set `my-app` as the generated project's root `package.json` name
-3. Run `pnpm install`
-4. Build `@restack/shared` (required once before `pnpm dev` works — see the
-   generated project's gotcha notes)
-5. Run `git init`
+---
 
-## Prerequisites
+## Quick Start (Next Steps)
 
-- Node.js 20+
-- [pnpm](https://pnpm.io) — the generated project is a pnpm workspace monorepo
-
-## After scaffolding
+Once the CLI finishes scaffolding your project, follow these three simple steps to get started:
 
+### 1. Configure Environment Variables
 ```bash
 cd my-app
-cp backend/.env.example backend/.env   # fill in DATABASE_URL and JWT_SECRET
-pnpm --filter backend dev              # http://localhost:3001
-pnpm --filter frontend dev             # http://localhost:3000
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
 ```
+- Open `backend/.env` and set:
+  - `DATABASE_URL` (format: `postgresql://user:password@localhost:5432/dbname`; you can use a local Postgres database or a free hosted instance on [Neon](https://neon.tech))
+  - `JWT_SECRET` (generate a secure 32-character key by running: `openssl rand -base64 32`)
+- *(Optional)* Open `frontend/.env` to override `NEXT_PUBLIC_API_URL` (defaults to `http://localhost:3001` for local Hono API).
 
-## What you get
-
-- `frontend/` — Next.js 16 (App Router)
-- `backend/` — Hono + Drizzle ORM, with a working JWT + refresh-token auth
-  flow, rate limiting, and an example `user` domain already wired up
-- `packages/shared/` — Zod schemas shared between frontend and backend
-
-## Current scope (MVP)
-
-This is the first, deliberately minimal version of the CLI. It does not yet
-ask about package manager, database, or auth-provider choices — it always
-scaffolds the exact pnpm + Postgres + Drizzle stack from the template as-is.
-Those choices are tracked as follow-up work in the main repo's
-`docs/concerns.md`.
-
-## For maintainers: keeping the template in sync
-
-The `template/` directory in this package is a **copy** of `frontend/`,
-`backend/`, and `packages/shared/` from the repo root, not a live reference —
-and it's gitignored, same as `dist/`. It's regenerated automatically before
-publish (`prepublishOnly` runs `sync-template` then `build`), so it never
-needs to be committed. For local testing, run it manually first:
-
+### 2. Push Database Tables
+This creates the required `users` and `auth_sessions` tables in your database:
 ```bash
-pnpm --filter create-restack-pattern sync-template
+pnpm --filter backend db:push
 ```
 
-This overwrites `template/` from the current state of the root template
-(excluding `node_modules`, build output, `.env*` except `.env.example`, and
-this repo's own internal planning docs like `docs/` and root `CLAUDE.md`,
-which aren't relevant to a generated project).
+### 3. Start Development Servers
+```bash
+pnpm dev
+```
+- **Backend API**: runs at [http://localhost:3001](http://localhost:3001)
+- **Frontend App**: runs at [http://localhost:3000](http://localhost:3000)
+
+---
+
+## What You Get
+
+- **`frontend/`** — Next.js 16 (App Router)
+- **`backend/`** — Hono + Drizzle ORM, with a working JWT + refresh-token auth flow, production-ready structured correlation logging (Pino + Hono request tracing), and an example `user` domain already wired up.
+- **`packages/shared/`** — Zod schemas shared between frontend and backend.
+
+For a full breakdown of the folder structure, architecture rules (Semi-DDD), dual-cookie auth implementation, and deployment verification checklists, please visit the [GitHub repository](https://github.com/NicholasChandraa/restack-pattern).
+
+---
+
+## For Maintainers (Local Dev & Publishing)
+
+The `template/` directory in this package is a **copy** of `frontend/`, `backend/`, and `packages/shared/` from the repo root, not a live reference — and it's gitignored.
+
+Before testing your CLI changes locally or publishing, follow the standard workflow:
+
+1. **Sync template**:
+   ```bash
+   pnpm --filter create-restack-pattern sync-template
+   ```
+2. **Compile the CLI script**:
+   ```bash
+   pnpm --filter create-restack-pattern build
+   ```
+3. **Verify the published files**:
+   ```bash
+   npm pack --dry-run
+   ```
+4. **Scaffold locally to test**:
+   ```bash
+   node dist/index.js test-app
+   ```
+5. **Publish to npm**:
+   Bump the `"version"` in `package.json`, then:
+   ```bash
+   npm publish
+   ```
+
+For detailed guides, workflow explanations, and lessons learned:
+- Check out the [Development Guide](../../docs/en/development-guide.md) (Indonesian: [Panduan Kontribusi](../../docs/id/development-guide.md))
+- Check out the [Building a Scaffolding CLI Tutorial](../../docs/tutorial.md)

package/dist/index.js

@@ -26,7 +26,24 @@ function renameGitignoreFilesBack(dir) {
             renameSync(full, path.join(dir, ".gitignore"));
     }
 }
+function isPnpmInstalled() {
+    try {
+        execSync("pnpm --version", { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function main() {
+    if (!isPnpmInstalled()) {
+        console.error("\n\x1b[31mError: pnpm is not installed.\x1b[0m");
+        console.error("This template is configured as a pnpm workspace monorepo and requires pnpm to run.");
+        console.error("Please install pnpm before continuing:");
+        console.error("  npm install -g pnpm");
+        console.error("Or visit https://pnpm.io for more installation options.\n");
+        process.exit(1);
+    }
     const argName = process.argv[2];
     const projectName = argName ?? (await promptProjectName());
     if (!projectName || !isValidProjectName(projectName)) {
@@ -59,12 +76,32 @@ async function main() {
         // git not available — non-fatal, scaffolding still succeeded
     }
     console.log(`
-Done! Next steps:
+\x1b[32m✔ Scaffolded project successfully!\x1b[0m
+
+Next steps to get started:
+
+  1. Go to your project directory:
+     \x1b[36mcd ${projectName}\x1b[0m
+
+  2. Configure environment variables:
+     • For Backend:
+       \x1b[36mcp backend/.env.example backend/.env\x1b[0m
+       (Open backend/.env and set \x1b[33mDATABASE_URL\x1b[0m and a min-32-chars \x1b[33mJWT_SECRET\x1b[0m)
+
+     • For Frontend:
+       \x1b[36mcp frontend/.env.example frontend/.env\x1b[0m
+
+  3. Push database tables (creates users & auth_sessions tables):
+     \x1b[36mpnpm --filter backend db:push\x1b[0m
+
+  4. Start development servers:
+     • Backend (running at http://localhost:3001):
+       \x1b[36mpnpm --filter backend dev\x1b[0m
+
+     • Frontend (running at http://localhost:3000):
+       \x1b[36mpnpm --filter frontend dev\x1b[0m
 
-  cd ${projectName}
-  cp backend/.env.example backend/.env   # fill in DATABASE_URL and JWT_SECRET
-  pnpm --filter backend dev
-  pnpm --filter frontend dev
+Enjoy building your app with the Restack Pattern!
 `);
 }
 main().catch((err) => {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "create-restack-pattern",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Scaffold a new Next.js + Hono + Drizzle monorepo using the Restack Pattern (Semi-DDD) template.",
   "license": "MIT",
   "type": "module",
   "private": false,
   "bin": {
-    "create-restack-pattern": "./dist/index.js"
+    "create-restack-pattern": "dist/index.js"
   },
   "files": [
     "dist",
@@ -22,5 +22,8 @@
     "@types/node": "^20.11.17",
     "tsx": "^4.7.1",
     "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/template/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides architecture, build, and styling guidance to Claude Code (claude.ai/code) and other AI assistants working in this repository.
+
+## Project Stack
+- **Frontend**: Next.js 16 (App Router)
+- **Backend**: Hono
+- **ORM**: Drizzle ORM
+- **Database**: PostgreSQL (Postgres-js driver)
+- **Validation**: Zod (shared schemas)
+- **Package Manager**: pnpm workspaces
+
+## Monorepo Layout
+- `frontend/` — Next.js 16 App Router
+- `backend/` — Hono API
+- `packages/shared/` — Shared Zod schemas (the single source of truth)
+
+## Build and Dev Commands
+All commands should be run from the repository root:
+- `pnpm install` — Install all dependencies
+- `pnpm --filter @restack/shared build` — Build shared Zod schemas (run first!)
+- `pnpm --filter backend dev` — Start Hono dev server on port 3001
+- `pnpm --filter frontend dev` — Start Next.js dev server on port 3000
+- `pnpm --filter backend db:push` — Push Drizzle schema to PostgreSQL database
+- `pnpm --filter backend db:studio` — Open Drizzle Studio database viewer
+- `pnpm --filter backend test` — Run Vitest tests
+
+## Architecture Rules: Semi-DDD (Feature-Driven)
+Code is organized by business domain/feature, not by file type.
+
+### Backend Layout (`backend/src/domains/[feature]/`)
+Each domain has 4 primary files:
+- `[feature].routes.ts` — HTTP endpoints & input validation (imports Zod schema from `@restack/shared`)
+- `[feature].service.ts` — Pure business logic only (no direct DB access)
+- `[feature].repo.ts` — Drizzle queries only (no business logic)
+- `[feature].model.ts` — Drizzle table definitions
+
+**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.
+
+### Frontend Layout (`frontend/domains/[feature]/`)
+- `components/` — UI components (no direct data fetching)
+- `hooks/` — Reactive state & data fetching logic
+- `services/` — Thin HTTP wrappers around `apiClient`
+- `types.ts` — Local TS type declarations
+- `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.
+
+## Critical Gotcha: Shared Package Build Requirement
+`@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:
+`pnpm --filter @restack/shared build`
+(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.
+
+## Auth & Cookie Strategy
+- Short-lived JWT `access_token` (15m) and opaque `refresh_token` (30d) are both set as `httpOnly` cookies at `Path=/`.
+- Access tokens are automatically refreshed by the client-side `apiClient` on a 401 response.
+- Cookie configuration: `SameSite=None` in production (requires `Secure=true`), and `SameSite=Lax` in development (`Secure=false` since local dev runs on HTTP).
+- 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.
+
+## Structured & Correlation Logging
+- Every incoming HTTP request is tagged with a unique `requestId` via Hono's `requestId` middleware.
+- A request-scoped child logger (`logger.child({ requestId })`) is bound to Hono's context.
+- 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).
+

package/template/backend/.env.example

@@ -5,4 +5,5 @@ PORT=3001
 FRONTEND_URL=http://localhost:3000,https://myapp.vercel.app
 # COOKIE_SAME_SITE=Lax   # override default (None in production, Lax in development)
 # COOKIE_DOMAIN=.example.com   # only set if FE/BE share a domain, e.g. app.example.com + api.example.com
-#                               # see docs/deployment-verification.md before deploying cross-domain
+#                              # see docs/deployment-verification.md before deploying cross-domain
+# LOG_FILE_PATH=logs/app.log   # Optional log file path (outputs to stdout and writes to this file)

package/template/backend/README.md

@@ -1,8 +1,49 @@
+# RestackPattern - Backend API (Hono)
+
+This is the Hono backend API for the RestackPattern monorepo. It features structured, context-scoped correlation logging (Pino), database interaction via Drizzle ORM, and a secure dual-cookie JWT refresh token authentication flow.
+
+## Directory Structure (Semi-DDD)
+
+Code is structured by business domain/feature:
+
 ```
-npm install
-npm run dev
+src/
+├── config/                  # Environment variables validation (env.ts)
+├── shared/                  # Reusable utilities across domains
+│   ├── db/                  # Drizzle connection client
+│   ├── logger/              # Pino logger instance and type definitions
+│   └── middlewares/         # requireAuth, etc.
+└── domains/
+    ├── auth/                # Auth routes, service, repo, and model
+    └── user/                # User routes, service, repo, and model
 ```
 
+### Domain Architecture Layer Rules:
+- `*.routes.ts` - Handles HTTP requests, validates input schemas (from `@restack/shared`), calls service logic, and returns JSON.
+- `*.service.ts` - Houses core business workflows, password hashing, and token issuance. Does not write SQL or run DB queries directly.
+- `*.repo.ts` - Houses Drizzle DB query executions. No business logic.
+- `*.model.ts` - Defines Drizzle database tables.
+
+---
+
+## Development
+
+Prerequisites: A running PostgreSQL database (e.g. [Neon](https://neon.tech) or a local instance).
+
+```bash
+# 1. Create env file and configure DATABASE_URL and JWT_SECRET
+cp .env.example .env
+
+# 2. Push schema to database
+pnpm db:push
+
+# 3. Start development watcher
+pnpm dev
 ```
-open http://localhost:3000
-```
+
+### Core Commands (Run from backend folder)
+- `pnpm dev` - Starts development server at `http://localhost:3001` (uses tsx watch)
+- `pnpm db:push` - Pushes Drizzle schemas to PostgreSQL database
+- `pnpm db:generate` - Generates Drizzle SQL migrations
+- `pnpm db:studio` - Starts Drizzle Studio GUI database viewer
+- `pnpm test` - Runs unit and integration test suites using Vitest

package/template/backend/gitignore

@@ -26,6 +26,7 @@ lerna-debug.log*
 
 # misc
 .DS_Store
-
-.vercel
-.env*
+
+.vercel
+.env*
+!.env.example

package/template/backend/package.json

@@ -30,5 +30,8 @@
     "tsx": "^4.7.1",
     "typescript": "^5.8.3",
     "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/template/backend/src/config/env.ts

@@ -17,6 +17,7 @@ const envSchema = z.object({
   // the frontend's own middleware read the session cookies too.
   COOKIE_DOMAIN: z.string().optional(),
   FRONTEND_URL: z.string().default("http://localhost:3000"),
+  LOG_FILE_PATH: z.string().optional(),
 })
 
 export const env = envSchema.parse(process.env)

package/template/backend/src/domains/auth/auth.routes.ts

@@ -5,8 +5,7 @@ import { zValidator } from "@hono/zod-validator"
 import { LoginSchema, RegisterSchema } from "@restack/shared"
 import { authService, ACCESS_TOKEN_TTL_SECONDS, REFRESH_TOKEN_TTL_SECONDS } from "./auth.service.js"
 import { env } from "../../config/env.js"
-import { logger } from "../../shared/logger/logger.js"
-import { rateLimit } from "../../shared/middlewares/rate-limit.js"
+import { logger, type AppVariables } from "../../shared/logger/logger.js"
 
 /**
  * Routing layer for the Auth domain.
@@ -37,57 +36,59 @@ const clearAuthCookies = (c: Context) => {
   deleteCookie(c, "refresh_token", deleteCookieOpts("/"))
 }
 
-export const authRoutes = new Hono()
+export const authRoutes = new Hono<{ Variables: AppVariables }>()
+  .post("/register", zValidator("json", RegisterSchema), async (c) => {
+    const reqLogger = c.get("logger") || logger
+    try {
+      reqLogger.info("Starting user registration")
+      const body = c.req.valid("json")
+      const user = await authService.register(body)
+      const tokens = await authService.issueTokenPair(user)
+
+      setAuthCookies(c, tokens)
+
+      return c.json({ user }, 201)
+    } catch (e: any) {
+      reqLogger.error({ err: e.message }, "Register failed")
+      return c.json({ error: e.message }, 400)
+    }
+  })
+  .post("/login", zValidator("json", LoginSchema), async (c) => {
+    const reqLogger = c.get("logger") || logger
+    try {
+      reqLogger.info("Attempting user login")
+      const body = c.req.valid("json")
+      const user = await authService.login(body)
+      const tokens = await authService.issueTokenPair(user)
+
+      setAuthCookies(c, tokens)
+
+      return c.json({ user })
+    } catch (e: any) {
+      reqLogger.error({ err: e.message }, "Login failed")
+      return c.json({ error: e.message }, 401)
+    }
+  })
+  .post("/refresh", async (c) => {
+    const reqLogger = c.get("logger") || logger
+    const refreshToken = getCookie(c, "refresh_token")
+    if (!refreshToken) return c.json({ error: "Missing refresh token" }, 401)
+
+    try {
+      reqLogger.info("Attempting token rotation")
+      const tokens = await authService.refresh(refreshToken)
+      setAuthCookies(c, tokens)
+      return c.json({ user: tokens.user })
+    } catch (e: any) {
+      clearAuthCookies(c)
+      reqLogger.error({ err: e.message }, "Refresh failed")
+      return c.json({ error: "Invalid refresh token" }, 401)
+    }
+  })
+  .post("/logout", async (c) => {
+    const refreshToken = getCookie(c, "refresh_token")
+    if (refreshToken) await authService.revokeSession(refreshToken)
 
-authRoutes.post("/register", rateLimit, zValidator("json", RegisterSchema), async (c) => {
-  try {
-    const body = c.req.valid("json")
-    const user = await authService.register(body)
-    const tokens = await authService.issueTokenPair(user)
-
-    setAuthCookies(c, tokens)
-
-    return c.json({ user }, 201)
-  } catch (e: any) {
-    logger.error({ err: e.message }, "Register failed")
-    return c.json({ error: e.message }, 400)
-  }
-})
-
-authRoutes.post("/login", rateLimit, zValidator("json", LoginSchema), async (c) => {
-  try {
-    const body = c.req.valid("json")
-    const user = await authService.login(body)
-    const tokens = await authService.issueTokenPair(user)
-
-    setAuthCookies(c, tokens)
-
-    return c.json({ user })
-  } catch (e: any) {
-    logger.error({ err: e.message }, "Login failed")
-    return c.json({ error: e.message }, 401)
-  }
-})
-
-authRoutes.post("/refresh", rateLimit, async (c) => {
-  const refreshToken = getCookie(c, "refresh_token")
-  if (!refreshToken) return c.json({ error: "Missing refresh token" }, 401)
-
-  try {
-    const tokens = await authService.refresh(refreshToken)
-    setAuthCookies(c, tokens)
-    return c.json({ user: tokens.user })
-  } catch (e: any) {
     clearAuthCookies(c)
-    logger.error({ err: e.message }, "Refresh failed")
-    return c.json({ error: "Invalid refresh token" }, 401)
-  }
-})
-
-authRoutes.post("/logout", async (c) => {
-  const refreshToken = getCookie(c, "refresh_token")
-  if (refreshToken) await authService.revokeSession(refreshToken)
-
-  clearAuthCookies(c)
-  return c.json({ success: true })
-})
+    return c.json({ success: true })
+  })

package/template/backend/src/domains/user/user.routes.ts

@@ -2,11 +2,9 @@ import { Hono } from "hono"
 import type { Context } from "hono"
 import { zValidator } from "@hono/zod-validator"
 import { UpdateProfileSchema } from "@restack/shared"
-import type { AuthVariables } from "../../shared/middlewares/require-auth.js"
 import { requireAuth } from "../../shared/middlewares/require-auth.js"
 import { userService, UserNotFoundError } from "./user.service.js"
-import { rateLimit } from "../../shared/middlewares/rate-limit.js"
-import { logger } from "../../shared/logger/logger.js"
+import { logger, type AppVariables } from "../../shared/logger/logger.js"
 
 /**
  * Routing layer for the User domain.
@@ -14,35 +12,39 @@ import { logger } from "../../shared/logger/logger.js"
  * 
  * Semi-DDD rules:
  * - `.routes.ts` files define HTTP endpoints, parse inputs using schema validators (zValidator),
- *   apply guards (requireAuth, rateLimit), and serialize JSON responses.
+ *   apply guards (requireAuth), and serialize JSON responses.
  * - Routing code should never implement business logic directly; it must delegate to the service layer.
  */
-export const userRoutes = new Hono<{ Variables: AuthVariables }>()
-
-// Only UserNotFoundError is an expected, safe-to-expose outcome. Anything else (DB/driver
-// errors, etc.) gets logged with detail but returned to the caller as a generic 500 —
-// leaking raw error messages/mislabeling unexpected failures as 404 would be misleading.
-const handleProfileError = (c: Context, e: unknown, action: string) => {
+const handleProfileError = (c: Context<{ Variables: AppVariables }>, e: unknown, action: string) => {
   if (e instanceof UserNotFoundError) return c.json({ error: e.message }, 404)
-  logger.error({ err: e instanceof Error ? e.message : String(e) }, action)
+  const reqLogger = c.get("logger") || logger
+  reqLogger.error({ err: e instanceof Error ? e.message : String(e) }, action)
   return c.json({ error: "Internal server error" }, 500)
 }
 
-userRoutes.get("/me", requireAuth, async (c) => {
-  try {
-    const profile = await userService.getProfile(Number(c.get("user").sub))
-    return c.json({ user: profile })
-  } catch (e) {
-    return handleProfileError(c, e, "Get profile failed")
-  }
-})
-
-userRoutes.put("/profile", requireAuth, rateLimit, zValidator("json", UpdateProfileSchema), async (c) => {
-  try {
-    const body = c.req.valid("json")
-    const profile = await userService.updateProfile(Number(c.get("user").sub), body)
-    return c.json({ user: profile })
-  } catch (e) {
-    return handleProfileError(c, e, "Update profile failed")
-  }
-})
+export const userRoutes = new Hono<{ Variables: AppVariables }>()
+  .get("/me", requireAuth, async (c) => {
+    const reqLogger = c.get("logger") || logger
+    try {
+      reqLogger.info("Retrieving authenticated user profile")
+      const user = c.get("user")
+      if (!user) return c.json({ error: "Unauthorized" }, 401)
+      const profile = await userService.getProfile(Number(user.sub))
+      return c.json({ user: profile })
+    } catch (e) {
+      return handleProfileError(c, e, "Get profile failed")
+    }
+  })
+  .put("/profile", requireAuth, zValidator("json", UpdateProfileSchema), async (c) => {
+    const reqLogger = c.get("logger") || logger
+    try {
+      const body = c.req.valid("json")
+      reqLogger.info("Updating user profile")
+      const user = c.get("user")
+      if (!user) return c.json({ error: "Unauthorized" }, 401)
+      const profile = await userService.updateProfile(Number(user.sub), body)
+      return c.json({ user: profile })
+    } catch (e) {
+      return handleProfileError(c, e, "Update profile failed")
+    }
+  })

package/template/backend/src/hono-app.ts

@@ -2,8 +2,9 @@ import { Hono } from "hono"
 import { cors } from "hono/cors"
 import { csrf } from "hono/csrf"
 import { logger as honoLogger } from "hono/logger"
+import { requestId } from "hono/request-id"
 import { env } from "./config/env.js"
-import { logger } from "./shared/logger/logger.js"
+import { logger, type AppVariables } from "./shared/logger/logger.js"
 import { authRoutes } from "./domains/auth/auth.routes.js"
 import { userRoutes } from "./domains/user/user.routes.js"
 
@@ -13,13 +14,37 @@ import { userRoutes } from "./domains/user/user.routes.js"
  * server (local dev, Railway/Render/VPS) or as a Vercel serverless function
  * (backend/api/index.ts), which cannot call @hono/node-server's serve().
  */
-export const app = new Hono()
+export const app = new Hono<{ Variables: AppVariables }>()
 
 const allowedOrigins = env.FRONTEND_URL
   .split(",")
   .map((url) => url.trim())
 
-app.use(honoLogger((...args) => logger.info(args.join(" "))))
+// 1. Generate unique request IDs for all API calls
+app.use("/api/*", requestId())
+
+// 2. Set up Pino child logger with correlation metadata per request
+app.use("/api/*", async (c, next) => {
+  const reqId = c.get("requestId") || ""
+  const { method, url } = c.req
+
+  const reqLogger = logger.child({
+    requestId: reqId,
+    method,
+    url: new URL(url).pathname,
+  })
+
+  c.set("logger", reqLogger)
+  await next()
+})
+
+// 3. Request Logging (bridge Hono's output into our Pino logger)
+app.use(
+  "/api/*",
+  honoLogger((...args) => {
+    logger.info(args.join(" "))
+  })
+)
 
 app.use(
   "/api/*",
@@ -36,7 +61,11 @@ app.use(
   })
 )
 
-app.route("/api/auth", authRoutes)
-app.route("/api/user", userRoutes)
+const routes = app
+  .route("/api/auth", authRoutes)
+  .route("/api/user", userRoutes)
 
 app.get("/", (c) => c.json({ status: "ok" }))
+
+export type AppType = typeof routes
+

package/template/backend/src/shared/db/index.ts

@@ -7,5 +7,5 @@ import { env } from "../../config/env.js"
  * Starts the `postgres-js` connection pool using the validated DATABASE_URL environment setting
  * and wraps it with the Drizzle ORM client wrapper.
  */
-const client = postgres(env.DATABASE_URL)
+const client = postgres(env.DATABASE_URL, { max: 1 })
 export const db = drizzle(client)

package/template/backend/src/shared/logger/logger.ts

@@ -6,10 +6,37 @@ import { env } from "../../config/env.js"
  * Configured using `pino`. Automatically toggles logging verbosity (info vs debug)
  * and formats stdout output using `pino-pretty` during local development.
  */
-export const logger = pino({
-  level: env.NODE_ENV === "production" ? "info" : "debug",
-  transport:
-    env.NODE_ENV === "production"
-      ? undefined
-      : { target: "pino-pretty", options: { colorize: true } },
-})
+const level = env.NODE_ENV === "production" ? "info" : "debug"
+
+let loggerInstance: pino.Logger
+
+if (env.LOG_FILE_PATH) {
+  // If a log file path is provided, stream to both stdout (console) and the file
+  const streams = [
+    { stream: process.stdout },
+    { stream: pino.destination({ dest: env.LOG_FILE_PATH, sync: false }) }
+  ]
+  loggerInstance = pino({ level }, pino.multistream(streams))
+} else {
+  // Otherwise default to standard stdout (with pretty formatting in local development)
+  loggerInstance = pino({
+    level,
+    transport:
+      env.NODE_ENV === "production"
+        ? undefined
+        : { target: "pino-pretty", options: { colorize: true } },
+  })
+}
+
+export const logger = loggerInstance
+
+
+import type { Logger } from "pino"
+import type { AuthTokenPayload } from "../../domains/auth/auth.types.js"
+
+export type AppVariables = {
+  requestId: string
+  logger: Logger
+  user?: AuthTokenPayload
+}
+

package/template/backend/src/shared/middlewares/require-auth.ts

@@ -1,19 +1,18 @@
 import type { MiddlewareHandler } from "hono"
 import { getCookie } from "hono/cookie"
 import { authService } from "../../domains/auth/auth.service.js"
-import type { AuthTokenPayload } from "../../domains/auth/auth.types.js"
-
-export type AuthVariables = { user: AuthTokenPayload }
+import type { AppVariables } from "../logger/logger.js"
 
 /**
  * Authentication guard middleware.
  * Enforces the presence and validity of the short-lived JWT access token in request cookies.
- * Resolves the payload and binds it to Hono context variables (`c.get("user")`).
+ * Resolves the payload, binds it to Hono context variables (`c.get("user")`),
+ * and attaches the authenticated userId to the request logger context.
  * 
  * Usage:
  * Apply to any endpoint requiring authentication (e.g. `userRoutes.get("/me", requireAuth, ...)`).
  */
-export const requireAuth: MiddlewareHandler<{ Variables: AuthVariables }> = async (c, next) => {
+export const requireAuth: MiddlewareHandler<{ Variables: AppVariables }> = async (c, next) => {
   // Extract token from cookie (JWT)
   const token = getCookie(c, "access_token")
   if (!token) return c.json({ error: "Unauthorized" }, 401)
@@ -22,6 +21,12 @@ export const requireAuth: MiddlewareHandler<{ Variables: AuthVariables }> = asyn
     // Decode and verify signature & expiration
     const payload = await authService.verifyAccessToken(token)
     c.set("user", payload)
+
+    // Enrich the child logger with the user's ID for all downstream actions
+    const reqLogger = c.get("logger")
+    if (reqLogger) {
+      c.set("logger", reqLogger.child({ userId: Number(payload.sub) }))
+    }
   } catch {
     // Return standard 401 response on invalid / expired signature
     return c.json({ error: "Unauthorized" }, 401)

package/template/frontend/.env.example

@@ -0,0 +1 @@
+NEXT_PUBLIC_API_URL=http://localhost:3001

package/template/frontend/README.md

@@ -1,36 +1,41 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# RestackPattern - Frontend App (Next.js)
 
-## Getting Started
+This is the Next.js 16 (App Router) frontend app for the RestackPattern monorepo. It uses a Semi-DDD folder structure, vanilla CSS, and connects to Hono through its official RPC client (`hc<AppType>`), giving end-to-end type inference on every request/response without manually declaring types.
 
-First, run the development server:
+## Directory Structure (Semi-DDD)
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+Code is structured by business domain/feature:
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+```
+src/
+├── app/                     # Routing configs, layouts, pages (no complex JSX/state here!)
+├── shared/                  # Reusable components, client wrappers, hooks
+│   ├── components/ui/       # Component primitives (e.g. Shadcn atoms)
+│   └── lib/api-client.ts    # Hono RPC client (hc<AppType>) + auto session refresh
+└── domains/
+    ├── auth/                # Login/Register components, auth services, hooks
+    └── user/                # User profile UI components, hooks
+```
 
-## Learn More
+### Folder Rules:
+- `app/` is strictly for routing and page wrappers. Do not implement complex forms, state, or layouts directly here. Always delegate rendering to domain feature components.
+- `domains/[feature]/components` - UI components specific to the business feature.
+- `domains/[feature]/hooks` - Handles fetching, mutations, and local state.
+- `domains/[feature]/services` - Small wrappers making API requests.
 
-To learn more about Next.js, take a look at the following resources:
+---
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Development
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+Ensure the backend API is running at `http://localhost:3001`.
 
-## Deploy on Vercel
+```bash
+# 1. Optional - configure environment variables (defaults to localhost:3001)
+cp .env.example .env
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+# 2. Start Next.js development server
+pnpm dev
+```
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+- Dev server will run at [http://localhost:3000](http://localhost:3000).
+- Runs with Turbopack enabled for lightning-fast hot reloading.

package/template/frontend/domains/auth/services/auth.api.ts

@@ -1,5 +1,5 @@
 import type { AuthUser, LoginInput, RegisterInput } from "@restack/shared"
-import { apiClient } from "@/shared/lib/api-client"
+import { client, unwrap } from "@/shared/lib/api-client"
 
 /**
  * Service API layer for the Auth domain.
@@ -11,17 +11,11 @@ import { apiClient } from "@/shared/lib/api-client"
  */
 export const authApi = {
   register: (data: RegisterInput) =>
-    apiClient<{ user: AuthUser }>("/api/auth/register", {
-      method: "POST",
-      body: JSON.stringify(data),
-    }),
+    unwrap<{ user: AuthUser }>(client.api.auth.register.$post({ json: data })),
 
   login: (data: LoginInput) =>
-    apiClient<{ user: AuthUser }>("/api/auth/login", {
-      method: "POST",
-      body: JSON.stringify(data),
-    }),
+    unwrap<{ user: AuthUser }>(client.api.auth.login.$post({ json: data })),
 
   logout: () =>
-    apiClient<{ success: boolean }>("/api/auth/logout", { method: "POST" }),
+    unwrap<{ success: boolean }>(client.api.auth.logout.$post()),
 }

package/template/frontend/domains/user/services/user.api.ts

@@ -1,5 +1,5 @@
 import type { AuthUser, UpdateProfileInput } from "@restack/shared"
-import { apiClient } from "@/shared/lib/api-client"
+import { client, unwrap } from "@/shared/lib/api-client"
 
 /**
  * Service API layer for the User domain.
@@ -11,11 +11,9 @@ import { apiClient } from "@/shared/lib/api-client"
  * - Request and response structures are mapped using schemas shared from `@restack/shared`.
  */
 export const userApi = {
-  me: () => apiClient<{ user: AuthUser }>("/api/user/me"),
+  me: () =>
+    unwrap<{ user: AuthUser }>(client.api.user.me.$get()),
 
   updateProfile: (data: UpdateProfileInput) =>
-    apiClient<{ user: AuthUser }>("/api/user/profile", {
-      method: "PUT",
-      body: JSON.stringify(data),
-    }),
+    unwrap<{ user: AuthUser }>(client.api.user.profile.$put({ json: data })),
 }

package/template/frontend/gitignore

@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel
@@ -39,5 +40,5 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
-
-.vercel
+
+.vercel

package/template/frontend/package.json

@@ -12,6 +12,7 @@
     "@restack/shared": "workspace:*",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "hono": "^4.12.27",
     "next": "16.2.9",
     "radix-ui": "^1.6.1",
     "react": "19.2.4",
@@ -31,5 +32,8 @@
     "eslint-config-next": "16.2.9",
     "tailwindcss": "^4",
     "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/template/frontend/shared/components/require-auth.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect, useState } from "react"
 import { useRouter } from "next/navigation"
-import { apiClient } from "../lib/api-client"
+import { client, unwrap } from "../lib/api-client"
 
 /**
  * Client-side auth gate for pages with no data fetch of their own to piggyback
@@ -15,11 +15,17 @@ export function RequireAuth({ children }: { children: React.ReactNode }) {
   const [checked, setChecked] = useState(false)
 
   useEffect(() => {
-    apiClient("/api/user/me")
+    unwrap(client.api.user.me.$get())
       .then(() => setChecked(true))
       .catch(() => router.replace("/login"))
   }, [router])
 
-  if (!checked) return null
+  if (!checked) {
+    return (
+      <div className="flex min-h-screen items-center justify-center bg-background">
+        <div className="h-6 w-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+      </div>
+    )
+  }
   return <>{children}</>
 }

package/template/frontend/shared/lib/api-client.ts

@@ -1,73 +1,77 @@
-/**
- * Global HTTP client helper for frontend domains.
- * Wraps global fetch and configures default options such as content types,
- * credentials handling (sending HTTP cookies), and base API URL resolution.
- */
+import { hc } from "hono/client"
+import type { AppType } from "../../../backend/src/hono-app"
+
 const BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001"
 
-/**
- * Custom API Error wrapping utility.
- * Captures both the backend error message payload and the raw HTTP response status code.
- */
-class ApiError extends Error {
+export class ApiError extends Error {
   constructor(message: string, public status: number) {
     super(message)
   }
 }
 
-interface ApiErrorBody {
-  error?: string
-}
-
-async function request<T>(path: string, options?: RequestInit): Promise<T> {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    ...options,
-    headers: {
-      "Content-Type": "application/json",
-      ...options?.headers,
-    },
-    credentials: "include",
-  })
-
-  const contentType = res.headers.get("content-type")
-  const data: unknown =
-    contentType && contentType.includes("application/json")
-      ? await res.json()
-      : { error: (await res.text()) || "Request failed" }
-
-  if (!res.ok) throw new ApiError((data as ApiErrorBody).error ?? "Request failed", res.status)
-  return data as T
-}
-
-// The refresh token is single-use (backend rotates it atomically), so if several
-// requests 401 at once they must share one refresh call, not each fire their own —
-// only the first would succeed and the rest would wrongly fail as "logged out".
-let refreshPromise: Promise<unknown> | null = null
+// Share a single refresh request promise to prevent TOCTOU race conditions
+let refreshPromise: Promise<Response> | null = null
 
 function refreshSession() {
   if (!refreshPromise) {
-    refreshPromise = request("/api/auth/refresh", { method: "POST" }).finally(() => {
+    refreshPromise = fetch(`${BASE_URL}/api/auth/refresh`, {
+      method: "POST",
+      credentials: "include",
+    }).finally(() => {
       refreshPromise = null
     })
   }
   return refreshPromise
 }
 
-export async function apiClient<T>(
-  path: string,
-  options?: RequestInit
-): Promise<T> {
-  try {
-    return await request<T>(path, options)
-  } catch (e) {
-    // The access_token cookie is short-lived by design (15m). On a 401, silently
-    // exchange the refresh_token for a new pair once, then retry the original call.
-    // Auth routes are excluded so a failed refresh can't loop back into itself.
-    const isAuthRoute = path.startsWith("/api/auth/")
-    if (e instanceof ApiError && e.status === 401 && !isAuthRoute) {
-      await refreshSession()
-      return request<T>(path, options)
+const customFetch: typeof fetch = async (input, init) => {
+  const newInit = {
+    ...init,
+    credentials: "include" as const,
+  }
+
+  const res = await fetch(input, newInit)
+
+  // Silently rotate access token on 401, unless it's the auth endpoints themselves
+  const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url
+  const isAuthRoute = url.includes("/api/auth/")
+
+  if (res.status === 401 && !isAuthRoute) {
+    const refreshRes = await refreshSession()
+    if (refreshRes.ok) {
+      // Retry the original request
+      return fetch(input, newInit)
+    }
+  }
+
+  return res
+}
+
+// Expose the Hono RPC client
+export const client = hc<AppType>(BASE_URL, { fetch: customFetch })
+
+interface ApiErrorBody {
+  error?: string
+}
+
+interface RpcResult {
+  ok: boolean
+  status: number
+  json(): Promise<unknown>
+}
+
+// Unwrap Hono RPC response helper to parse JSON or throw formatted ApiError
+export async function unwrap<T>(promise: Promise<RpcResult>): Promise<T> {
+  const res = await promise
+  if (!res.ok) {
+    let errorMsg = "Request failed"
+    try {
+      const data = (await res.json()) as ApiErrorBody
+      errorMsg = data.error ?? errorMsg
+    } catch {
+      // fallback
     }
-    throw e
+    throw new ApiError(errorMsg, res.status)
   }
+  return res.json() as Promise<T>
 }

package/template/gitignore

@@ -32,4 +32,12 @@ Thumbs.db
 .idea/
 
 # Claude Code local overrides (personal, not shared with the team)
-.claude/settings.local.json
+.claude/settings.local.json
+test-project/
+test-app/
+
+# Exclude concerns and root CLAUDE.md from git
+docs/concerns.md
+CLAUDE.md
+
+docs/tutorial.md

package/template/package.json

@@ -1,6 +1,7 @@
 {
   "name": "restack-pattern",
   "private": true,
+  "license": "MIT",
   "scripts": {
     "dev": "pnpm --parallel dev",
     "build": "pnpm --parallel build"
@@ -9,5 +10,8 @@
     "frontend",
     "backend",
     "packages/*"
-  ]
+  ],
+  "engines": {
+    "node": ">=20"
+  }
 }

package/template/backend/src/shared/middlewares/rate-limit.ts

@@ -1,43 +0,0 @@
-import type { Context, MiddlewareHandler } from "hono"
-import { getConnInfo } from "@hono/node-server/conninfo"
-
-/**
- * In-Memory Fixed-Window Rate Limiting Middleware.
- * 
- * Performance/Topology Note:
- * - This implementation stores counts in a local `Map` memory segment.
- * - This works perfectly for single-process deployments (like a standalone Railway node).
- * - If horizontal scaling (multiple instances) is introduced, this must be swapped
- *   for a shared datastore (e.g. Redis) to ensure limits are synchronized globally.
- */
-const WINDOW_MS = 60_000
-const MAX_REQUESTS = 10
-
-const hits = new Map<string, { count: number; resetAt: number }>()
-
-// getConnInfo reaches into the raw Node socket, which only exists when served via a real
-// @hono/node-server connection — it throws in in-memory test harnesses (Hono's `.request()`)
-// and some serverless runtimes. Fall back to a shared bucket rather than crashing the request.
-const clientIp = (c: Context) => {
-  try {
-    return getConnInfo(c).remote.address ?? "unknown"
-  } catch {
-    return "unknown"
-  }
-}
-
-export const rateLimit: MiddlewareHandler = async (c, next) => {
-  const key = `${c.req.path}:${clientIp(c)}`
-  const now = Date.now()
-  const entry = hits.get(key)
-
-  if (!entry || entry.resetAt < now) {
-    hits.set(key, { count: 1, resetAt: now + WINDOW_MS })
-  } else if (entry.count >= MAX_REQUESTS) {
-    return c.json({ error: "Too many requests, try again later" }, 429)
-  } else {
-    entry.count++
-  }
-
-  await next()
-}