create-nextdevtpl 2.6.0

package/template/.env.example

@@ -0,0 +1,282 @@
+# ============================================
+# NextjsTpl 环境变量配置
+# ============================================
+# 复制此文件为 .env.local 并填写实际值
+# cp .env.example .env.local
+#
+# 快速开始 (开发环境):
+# 1. 数据库: 使用本地 PostgreSQL 或 Neon
+# 2. 认证:   配置 GitHub/Google OAuth (可选，可用邮箱登录)
+# 3. AI:     配置 OpenAI 或 DeepSeek API Key
+# 4. 启动:   pnpm dev
+#
+
+# ============================================
+# 应用配置
+# ============================================
+# 应用 URL (用于 OAuth 回调和 API 请求)
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# 应用名称 (显示在邮件、通知等)
+NEXT_PUBLIC_APP_NAME=NextDevTpl
+
+# 部署版本标签（可使用 Git commit 或发布版本）
+APP_VERSION=local
+
+# Docker Compose 可选覆盖项；生产环境必须修改数据库密码
+# PORT=3000
+# POSTGRES_DB=nextdevtpl
+# POSTGRES_USER=nextdevtpl
+# POSTGRES_PASSWORD=replace-with-a-long-random-password
+
+# 社交与联系链接 (显示在页脚和元数据)
+NEXT_PUBLIC_TWITTER_URL=https://twitter.com/example
+NEXT_PUBLIC_GITHUB_URL=https://github.com/evepupil/NextDevTpl
+NEXT_PUBLIC_DISCORD_URL=https://discord.gg/example
+NEXT_PUBLIC_SUPPORT_EMAIL=hello@example.com
+
+# 默认用户积分 (新用户注册时赠送)
+# DEFAULT_USER_CREDITS=100
+
+# ============================================
+# 数据库配置 (PostgreSQL)
+# ============================================
+# 本地 Docker PostgreSQL 示例:
+# DATABASE_URL=postgresql://postgres:password@localhost:5432/nextdevtpl
+
+# Neon Serverless PostgreSQL 示例 (注意: 使用非 pooler 端点以支持事务):
+# DATABASE_URL=postgresql://user:password@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require
+
+DATABASE_URL=postgresql://postgres:password@localhost:5432/nextdevtpl
+
+# ============================================
+# Better Auth 配置
+# ============================================
+# 认证密钥 (用于签名会话 Cookie)
+# 生成方法: openssl rand -base64 32
+BETTER_AUTH_SECRET=your-super-secret-key-change-in-production
+
+# 认证 URL (通常与 NEXT_PUBLIC_APP_URL 相同)
+BETTER_AUTH_URL=http://localhost:3000
+
+# ============================================
+# GitHub OAuth 配置
+# ============================================
+# 1. 访问 https://github.com/settings/developers
+# 2. 点击 "New OAuth App"
+# 3. 填写:
+#    - Application name: NextDevTpl (或你的应用名)
+#    - Homepage URL: http://localhost:3000
+#    - Authorization callback URL: http://localhost:3000/api/auth/callback/github
+# 4. 获取 Client ID 和 Client Secret
+
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# ============================================
+# Google OAuth 配置
+# ============================================
+# 1. 访问 https://console.cloud.google.com/apis/credentials
+# 2. 创建项目 (如果还没有)
+# 3. 点击 "Create Credentials" -> "OAuth client ID"
+# 4. 选择 "Web application"
+# 5. 添加:
+#    - Authorized JavaScript origins: http://localhost:3000
+#    - Authorized redirect URIs: http://localhost:3000/api/auth/callback/google
+# 6. 获取 Client ID 和 Client Secret
+
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# ============================================
+# Creem 支付配置
+# ============================================
+# 1. 访问 https://dashboard.creem.io 获取 API Key
+# 2. 创建 Webhook 并获取 Secret
+
+CREEM_API_KEY=creem_api_key_xxx
+CREEM_WEBHOOK_SECRET=creem_webhook_secret_xxx
+
+# Stripe 支付适配器（选择 Stripe 时启用）
+# STRIPE_SECRET_KEY=sk_test_xxx
+# STRIPE_WEBHOOK_SECRET=whsec_xxx
+
+# 支付供应商价格 ID
+# 可选: 如果不配置，对应的计划将不可用
+NEXT_PUBLIC_PRICE_STARTER_MONTHLY=price_xxx
+NEXT_PUBLIC_PRICE_STARTER_YEARLY=price_xxx
+NEXT_PUBLIC_PRICE_PRO_MONTHLY=price_xxx
+NEXT_PUBLIC_PRICE_PRO_YEARLY=price_xxx
+NEXT_PUBLIC_PRICE_ULTRA_MONTHLY=price_xxx
+NEXT_PUBLIC_PRICE_ULTRA_YEARLY=price_xxx
+
+# ============================================
+# 邮件服务配置 (Resend)
+# ============================================
+# 1. 访问 https://resend.com
+# 2. 创建 API Key
+# 3. 配置发件域名 (用于生产环境)
+
+RESEND_API_KEY=re_your-resend-api-key
+
+# 发件人地址 (格式: "Name <email@domain.com>")
+EMAIL_FROM="NextDevTpl <noreply@your-domain.com>"
+
+# SMTP 邮件适配器（选择 SMTP 时启用）
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_SECURE=false
+# SMTP_USER=your-smtp-user
+# SMTP_PASS=your-smtp-password
+
+# Cloudflare Email 使用 Worker 的 send_email Binding，无需 API Key。
+# 发件域名和 Binding 在 Cloudflare Workers 部署配置中完成。
+
+# ============================================
+# 存储配置 (S3 兼容: AWS S3 / Cloudflare R2 / MinIO)
+# ============================================
+# NextjsTpl 使用对象存储保存用户上传的文件 (PDF, Word, Markdown)
+#
+# 本地开发可选，不配置则文件上传功能不可用
+#
+# Cloudflare R2 示例:
+# STORAGE_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
+# STORAGE_REGION=auto
+
+# AWS S3 示例:
+# STORAGE_ENDPOINT=https://s3.us-east-1.amazonaws.com
+# STORAGE_REGION=us-east-1
+
+STORAGE_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
+STORAGE_REGION=auto
+STORAGE_ACCESS_KEY_ID=your-access-key-id
+STORAGE_SECRET_ACCESS_KEY=your-secret-access-key
+
+# 头像存储桶名称 (需要预先在存储服务中创建)
+NEXT_PUBLIC_AVATARS_BUCKET_NAME=avatars
+
+# ============================================
+# AI 配置 (OpenAI / DeepSeek / MiMo - 必需)
+# ============================================
+# Cloudflare AI Gateway (可选)
+# 只有同时配置 CF_AIG_BASE_URL 和 CF_AIG_TOKEN 才会走网关
+# baseURL 需要包含 /v1，并指向你在 CF 配置的 Provider Slug
+# 通常形如: https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/<provider>/v1
+# CF_AIG_TOKEN 会作为 cf-aig-authorization 头使用，仍需配置各提供商 API Key
+CF_AIG_BASE_URL=https://gateway.ai.cloudflare.com/v1/cb5d3307349a8fde7637f773906ad340/NextjsTpl/custom-xiaomi/v1
+CF_AIG_TOKEN=cf_aig_token_xxx
+
+# NextjsTpl 核心功能依赖 AI 生成闪卡
+# 支持 OpenAI、DeepSeek、MiMo 三种提供商
+#
+# 支持的 AI 提供商: openai | deepseek | mimo
+# 默认使用 OpenAI，设置为 deepseek 或 mimo 切换提供商
+AI_PROVIDER=openai
+
+# --- OpenAI 配置 ---
+# 1. 访问 https://platform.openai.com/api-keys
+# 2. 创建 API Key
+OPENAI_API_KEY=sk-your-openai-api-key
+
+# 可选: 指定 OpenAI 模型
+# - gpt-4o-mini (默认，推荐，成本低)
+# - gpt-4o
+# - gpt-3.5-turbo
+# OPENAI_MODEL=gpt-4o-mini
+
+# --- DeepSeek 配置 ---
+# 1. 访问 https://platform.deepseek.com/api_keys
+# 2. 创建 API Key
+DEEPSEEK_API_KEY=sk-your-deepseek-api-key
+
+# 可选: 指定 DeepSeek 模型
+# - deepseek-chat (默认，推荐)
+# - deepseek-reasoner
+# DEEPSEEK_MODEL=deepseek-chat
+
+# --- 小米 MiMo 配置 ---
+# 小米 MiMo 推理模型，使用 OpenAI 兼容 API
+# API 地址: https://api.xiaomimimo.com/v1
+MIMO_API_KEY=sk-your-mimo-api-key
+
+# 可选: 指定 MiMo 模型
+# - mimo-v2-flash (默认，推荐，快速推理)
+# MIMO_MODEL=mimo-v2-flash
+
+# --- Anthropic 配置（选择 Anthropic 时启用） ---
+# ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
+# ANTHROPIC_MODEL=claude-model-id
+
+# --- Cloudflare Workers AI（选择 Workers AI 时启用） ---
+# 推理服务使用 Worker 的 AI Binding；这里只选择模型。
+# WORKERS_AI_MODEL=@cf/meta/model-id
+
+# ============================================
+# Inngest 配置 (异步任务队列 - 必需)
+# ============================================
+# NextjsTpl 使用 Inngest 处理闪卡生成的后台任务
+#
+# 开发模式:
+# 1. 安装并启动 Dev Server:
+#    npx inngest-cli@latest dev
+# 2. 开发服务器会自动连接，无需额外配置
+#
+# 开发模式标志 (可选，用于明确启用开发模式)
+# INNGEST_DEV=1
+#
+# 本地 Dev Server URL (如果 Dev Server 不在默认端口)
+# INNGEST_BASE_URL=http://localhost:8288
+
+# 生产环境密钥 (通过 Vercel Integration 自动设置，通常无需手动配置)
+# INNGEST_EVENT_KEY=signkey-prod-xxx
+# INNGEST_SIGNING_KEY=signkey-prod-xxx
+
+# ============================================
+# 可选配置
+# ============================================
+
+# 定时任务密钥 (用于保护 cron 端点)
+# 生成方法: openssl rand -hex 32
+# CRON_SECRET=your-cron-secret
+
+# Google Analytics (可选)
+# NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
+
+# ============================================
+# Rate Limiting 配置 (Upstash Redis) - 可选
+# ============================================
+# 用于 API 限流保护，防止滥用
+# 未配置时将跳过限流检查
+#
+# 1. 访问 https://upstash.com
+# 2. 创建 Redis 数据库
+# 3. 获取 REST URL 和 Token
+
+# UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
+# UPSTASH_REDIS_REST_TOKEN=xxx
+
+# ============================================
+# 日志服务配置 (Axiom) - 可选
+# ============================================
+# 用于结构化日志收集和查询
+# 未配置时将使用 console 输出
+#
+# 1. 访问 https://axiom.co
+# 2. 创建数据集 (Dataset)
+# 3. 获取 API Token
+
+# AXIOM_TOKEN=xaat-xxx
+# AXIOM_DATASET=nextdevtpl
+
+# ============================================
+# 错误监控配置 (Sentry) - 可选
+# ============================================
+# 用于错误追踪和性能监控
+# 未配置时将使用 console 输出错误
+#
+# 1. 访问 https://sentry.io
+# 2. 创建项目 (选择 Next.js)
+# 3. 获取 DSN
+
+# NEXT_PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
+# SENTRY_AUTH_TOKEN=sntrys_xxx

package/template/.gitattributes

@@ -0,0 +1,17 @@
+* text=auto eol=lf
+
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+*.gif binary
+*.ico binary
+*.jpeg binary
+*.jpg binary
+*.pdf binary
+*.png binary
+*.wasm binary
+*.webp binary
+*.woff binary
+*.woff2 binary
+*.zip binary

package/template/.node-version

@@ -0,0 +1 @@
+24.18.0

package/template/Dockerfile

@@ -0,0 +1,45 @@
+# syntax=docker/dockerfile:1
+
+FROM node:24.18.0-alpine AS base
+ENV PNPM_HOME=/pnpm
+ENV PATH=$PNPM_HOME:$PATH
+RUN corepack enable
+WORKDIR /app
+
+FROM base AS dependencies
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --ignore-scripts
+
+FROM dependencies AS builder
+COPY . .
+ARG NEXT_PUBLIC_APP_URL=http://localhost:3000
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV DATABASE_URL=postgresql://build:build@127.0.0.1:5432/build
+ENV BETTER_AUTH_SECRET=build-only-secret
+ENV BETTER_AUTH_URL=http://localhost:3000
+ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
+RUN pnpm run --if-present postinstall
+RUN pnpm build
+
+FROM dependencies AS migrator
+COPY . .
+ENV NODE_ENV=production
+CMD ["pnpm", "db:migrate"]
+
+FROM node:24.18.0-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV HOSTNAME=0.0.0.0
+ENV PORT=3000
+
+RUN addgroup --system --gid 1001 nodejs \
+  && adduser --system --uid 1001 nextjs
+
+COPY --from=builder --chown=nextjs:nodejs /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+EXPOSE 3000
+CMD ["node", "server.js"]

package/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yeton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/README.md

@@ -0,0 +1,267 @@
+<p align="center">
+  <br>
+  <img src="public/logo.svg" alt="NextDevTpl" width="120">
+  <br>
+  <h1 align="center">NextDevTpl</h1>
+  <p align="center">
+    The production-ready Next.js SaaS starter — launch your SaaS in hours, not weeks.
+  </p>
+  <p align="center">
+    <a href="https://github.com/evepupil/NextDevTpl/blob/master/LICENSE">
+      <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+    </a>
+    <a href="https://nextjs.org/">
+      <img src="https://img.shields.io/badge/Next.js-16-black?logo=nextdotjs" alt="Next.js 16">
+    </a>
+    <a href="https://www.typescriptlang.org/">
+      <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript 5">
+    </a>
+    <a href="https://tailwindcss.com/">
+      <img src="https://img.shields.io/badge/Tailwind%20CSS-4-38bdf8?logo=tailwindcss" alt="Tailwind CSS 4">
+    </a>
+    <a href="https://pnpm.io/">
+      <img src="https://img.shields.io/badge/pnpm-9-orange?logo=pnpm" alt="pnpm">
+    </a>
+  </p>
+  <p align="center">
+    <a href="#-features">Features</a> •
+    <a href="#-why-nextdevtpl">Why NextDevTpl?</a> •
+    <a href="#-quick-start">Quick Start</a> •
+    <a href="#-project-structure">Structure</a> •
+    <a href="#-deployment">Deployment</a>
+  </p>
+</p>
+
+---
+
+## 🚀 Features
+
+| Category | Highlights |
+|----------|-----------|
+| **Framework** | Next.js 16 (App Router, Turbopack), React 19, TypeScript |
+| **Styling** | Tailwind CSS 4, Shadcn/UI, Radix UI, dark mode |
+| **Database** | PostgreSQL, Drizzle ORM, Neon serverless |
+| **Auth** | Better Auth — email/password, GitHub/Google OAuth, role-based access |
+| **Payments** | Creem subscription billing, webhooks, multi-tier pricing |
+| **Credits** | Double-entry FIFO system with batch expiration tracking |
+| **Email** | Resend delivery, React Email templates, dev preview |
+| **Storage** | S3 / Cloudflare R2 compatible, presigned uploads |
+| **Support** | Ticket system with threaded conversations |
+| **Admin** | Dashboard, user CRUD, credit top-ups, ticket management |
+| **i18n** | ~~next-intl~~ full en/zh bilingual routing |
+| **AI** | ~~Remove~~ multi-provider chat (OpenAI, DeepSeek, MiMo) |
+| **Rate Limiting** | Upstash Redis sliding window — automatically falls back to no-op when unconfigured |
+| **Logging** | Pino structured logging → Axiom cloud — gracefully degrades to console |
+| **Monitoring** | Sentry error tracking — auto-capture, user context, console fallback |
+| **Async Jobs** | Inngest background queue with graceful degradation |
+| **Tooling** | Biome (lint + format), pnpm, strict TypeScript |
+
+> **Graceful degradation** — every optional service (rate limiting, logging, monitoring, async jobs) falls back to a safe local mode when its environment variable is missing. Start with 3 env vars and add services incrementally.
+
+## ✨ Why NextDevTpl?
+
+| | NextDevTpl | Other SaaS Templates |
+|---|---|---|
+| **AI integration** | Multi-provider, built-in | None or bolted on |
+| **Double-entry credits** | FIFO + batch expiry | Shallow balance field |
+| **i18n** | Full en/zh routing | Partial or add-on |
+| **Async jobs** | Inngest, no blocking calls | Requests block on I/O |
+| **Graceful degradation** | Every optional service self-silences | Hard dependency on Redis / Sentry / etc. |
+| **Feature-based code** | `features/auth/`, `features/credits/` | Flat or role-based folders |
+| **Real payment integration** | Creem (not Stripe mock) | Placeholder events |
+| **PSEO demo** | ~~AnkiGenix~~ Phoenix-style programmatic SEO | None |
+
+## 📦 Tech Stack
+
+```mermaid
+graph TD
+    Client[Browser / Client] --> Next["Next.js 16<br/>App Router + Server Actions"]
+    Next --> Auth[Better Auth]
+    Next --> DB[("PostgreSQL<br/>Drizzle ORM")]
+    Next --> Mail[Resend + React Email]
+    Next --> Storage[(S3 / R2)]
+    Next --> Payment[Creem]
+    Next --> RateLimit["Rate Limit<br/>Upstash Redis"]
+    Next --> Jobs[Inngest Queue]
+    Next --> Log[Pino → Axiom]
+    Next --> Monitor[Sentry]
+    Next --> AI["AI<br/>OpenAI / DeepSeek / MiMo"]
+```
+
+## 🏁 Quick Start
+
+Three env vars are enough to launch:
+
+```bash
+git clone git@github.com:evepupil/NextDevTpl.git
+cd NextDevTpl
+pnpm install
+cp .env.example .env.local
+```
+
+Edit `.env.local`:
+
+```bash
+DATABASE_URL=postgresql://...
+BETTER_AUTH_SECRET="your-secret"
+BETTER_AUTH_URL="http://localhost:3000"
+```
+
+```bash
+pnpm db:push    # push Drizzle schema to your DB
+pnpm dev        # http://localhost:3000
+```
+
+### Optional Services
+
+| Service | Env Var | What You Get |
+|---------|---------|-------------|
+| Inngest | `INNGEST_EVENT_KEY` | Background queue (credits delivery, email batching) |
+| Upstash | `UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN` | API rate limiting |
+| Axiom | `AXIOM_TOKEN` + `AXIOM_DATASET` | Structured cloud logging |
+| Sentry | `SENTRY_DSN` | Error monitoring |
+| OpenAI | `OPENAI_API_KEY` | AI chat |
+| Creem | `CREEM_API_KEY` + webhook secret | Subscription payments |
+
+Every service that isn't configured simply skips its logic — no crash, no error, no blocked startup.
+
+## 📁 Project Structure
+
+```
+src/
+├── app/                        # Next.js App Router
+│   └── [locale]/               # i18n routing (en / zh)
+│       ├── (marketing)/        # Public pages (landing, pricing, blog, docs)
+│       ├── (dashboard)/        # Authenticated user area
+│       └── (admin)/            # Admin-only area
+├── components/ui/              # Shadcn/UI primitives
+├── features/                   # Feature-based modules
+│   ├── marketing/              # header, footer, hero, pricing
+│   ├── dashboard/              # sidebar, topbar, stat cards
+│   ├── admin/                  # admin sidebar, user table
+│   ├── auth/                   # sign-in, sign-up, auth client
+│   ├── blog/                   # blog list, post detail
+│   ├── settings/               # profile, billing, account
+│   ├── support/                # ticket CRUD
+│   ├── analytics/              # admin dashboard charts
+│   ├── shared/                 # mode-toggle, language-switcher, icons
+│   └── pseo/                   # programmatic SEO demo
+├── db/                         # Drizzle schema definitions
+├── lib/                        # Shared utilities
+│   ├── auth/                   # Better Auth config + middleware
+│   ├── rate-limit/             # Upstash sliding window
+│   ├── logger/                 # Pino logger wrapper
+│   └── monitoring/             # Sentry instrumentation
+├── credits/                    # Double-entry FIFO credit engine
+├── mail/                       # React Email templates + Resend sender
+├── storage/                    # S3 / R2 abstraction
+├── config/                     # Site, nav, payment, subscription configs
+└── test/                       # Integration tests
+```
+
+## 🧩 Feature Modules
+
+### Auth
+Email/password + GitHub/Google OAuth. Session management, `user` / `admin` roles, middleware protection.
+
+### Payments
+Creem subscription flow. Multi-tier pricing, webhook handling, subscription lifecycle, admin override.
+
+### Credits
+FIFO batch expiry + double-entry ledger. Every credit transaction is a balanced debit/credit pair with audit trail.
+
+### Email
+React Email templates with `<Html>`, `<Button>`, etc. Resend delivery. In dev mode, preview at `/api/emails/preview`.
+
+### Storage
+S3-compatible abstraction. Presigned upload URLs. Works with AWS S3, Cloudflare R2, MinIO, etc.
+
+### Support Tickets
+Threaded conversations, status workflow (open → in-progress → resolved), admin reply, email notifications.
+
+### Admin Panel
+Overview dashboard, user management (search, role toggle, ban), credit top-ups, ticket queue.
+
+### i18n
+`next-intl`-based routing. Current locales: `en`, `zh`. Add a locale by dropping a JSON file.
+
+### Rate Limiting
+Globally applied middleware. Route-level rate windows. Zero-config — unset `UPSTASH_*` env vars and it becomes a pass-through.
+
+### Logging
+Pino structured logger wrapped in `@/lib/logger`. Ships to Axiom when configured, otherwise writes to console.
+
+### Error Monitoring
+Sentry auto-instruments Server Actions & route handlers. Attaches authenticated user context. Falls back to `console.error` without a DSN.
+
+## 🚢 Deployment
+
+### Self-hosted (recommended)
+
+The repo includes `deploy-build.bat` (Windows build machine) + `start-prod.sh` (Linux server). Edit the SSH host / key paths at the top of `deploy-build.bat`, then:
+
+```bat
+:: Windows local machine
+deploy-build.bat
+```
+
+The script: builds → tars `.next` + config → SCPs → remote server unpacks → PM2 restarts.
+
+### Vercel
+
+Zero-config — push to `master`, Vercel auto-detects Next.js.
+
+### Docker
+
+Write a `Dockerfile`:
+
+```dockerfile
+FROM node:20-alpine AS base
+# ... pnpm install, build, start
+```
+
+## 📋 Scripts
+
+```bash
+pnpm dev            # Next.js dev (Turbopack)
+pnpm build          # Production build
+pnpm start          # Production server
+pnpm lint           # Biome lint
+pnpm format         # Biome format
+pnpm check          # lint + format in fix mode
+pnpm typecheck      # tsc --noEmit
+pnpm db:generate    # Drizzle kit generate
+pnpm db:push        # Drizzle kit push (dev)
+pnpm db:studio      # Drizzle Studio UI
+pnpm test           # Run integration tests
+```
+
+## 🗺️ Routes
+
+| Route | Description | Access |
+|-------|-------------|--------|
+| `/` | Landing page | Public |
+| `/pricing` | Subscription plans | Public |
+| `/blog` | Blog index | Public |
+| `/blog/[slug]` | Blog post | Public |
+| `/docs` | Documentation | Public |
+| `/sign-in` | Sign in | Public |
+| `/sign-up` | Sign up | Public |
+| `/dashboard` | User dashboard | Auth required |
+| `/dashboard/support` | My tickets | Auth required |
+| `/settings` | Account settings | Auth required |
+| `/admin` | Admin dashboard | Admin only |
+| `/admin/users` | User management | Admin only |
+| `/admin/tickets` | Ticket queue | Admin only |
+
+## 🤝 Contributing
+
+- **Feature-based code**: place new modules under `src/features/<name>/`.
+- **Server Components first**: only add `'use client'` when you need interactivity.
+- **Server Actions**: all data mutations go through `next-safe-action`.
+- **Type safety**: every prop, API response, and action schema must be typed.
+- **Tests**: add integration tests in `src/test/`.
+
+## 📄 License
+
+MIT