A full-stack Next.js starter template with type-safe API routes (Hono + OpenAPI), multi-tenant auth with RBAC (Better Auth), and PostgreSQL (Drizzle ORM).
- Hono OpenAPI RPC - Type-safe API routes with automatic OpenAPI documentation at
/api/docs - Better Auth - Username/password auth with multi-tenant organizations
- Role-Based Access Control - 4-layer permission system (constants, schema, matrix, middleware)
- Drizzle ORM - Type-safe database with migration tooling
- TanStack Query - Server state management with type-safe hooks
- Shadcn UI - Component library with Radix primitives and Tailwind CSS
- Dashboard Shell - Sidebar, breadcrumbs, permission-gated navigation
- Code Quality - ESLint, Prettier, TypeScript strict mode, Husky git hooks
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router, Turbopack) |
| API | Hono + @hono/zod-openapi + Scalar docs |
| Auth | Better Auth (organization plugin) |
| Database | PostgreSQL + Drizzle ORM |
| State | TanStack Query + Zustand |
| UI | Tailwind CSS + Shadcn UI + Tabler Icons |
| Forms | React Hook Form + Zod |
| Logging | Pino (hono-pino) |
# Install dependencies
pnpm install
# Copy environment variables
cp .env.example .env
# Edit .env with your database URL and passwords
# Generate and push database schema
pnpm db:generate --name initial-schema
pnpm db:push
# Seed admin user and organization
pnpm db:seed
# Start dev server
pnpm devOpen http://localhost:3000 and log in with the admin credentials from your seed.
blur-stack/
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── api/[[...route]]/ # Hono API catch-all handler
│ │ │ └── route.ts # Mounts all API routes, exports AppType
│ │ ├── forbidden/ # 403 forbidden page
│ │ ├── page.tsx # Landing/home page
│ │ ├── layout.tsx # Root layout (providers, fonts)
│ │ └── globals.css # Global styles (Tailwind)
│ │
│ ├── components/ # React components
│ │ └── ui/ # Shadcn UI primitives only
│ │
│ ├── db/ # Database layer
│ │ ├── helpers/
│ │ │ └── columns.helper.ts # baseColumns helper (id, createdAt, updatedAt)
│ │ ├── schema/
│ │ │ ├── auth.ts # Better Auth tables
│ │ │ └── index.ts # Schema exports
│ │ └── index.ts # Drizzle client instance
│ │
│ ├── features/ # Feature-specific hooks
│ │ ├── auth/ # Authentication hooks
│ │ │ ├── useAuth.ts # signIn, signOut, etc.
│ │ │ └── usePermissions.ts # Permission checking
│ │ └── health/ # Health check hooks
│ │ └── useHealth.ts
│ │
│ ├── hooks/ # Shared custom hooks
│ │
│ ├── lib/ # Core libraries and configurations
│ │ ├── auth/ # Authentication & Authorization
│ │ │ ├── auth.ts # Better Auth server instance
│ │ │ ├── auth-client.ts # Better Auth client instance
│ │ │ ├── access-control.ts # ABAC role definitions
│ │ │ ├── permission-constants.ts # PERMISSION_ACTION enum
│ │ │ ├── permission-schema.ts # Resource groups & actions
│ │ │ ├── permissions-matrix.ts # Auto-generated permission matrix
│ │ │ ├── role-definitions.ts # Role-to-permission mappings
│ │ │ ├── role-mapper.ts # getRolePermissions()
│ │ │ └── route-permissions.ts # Route-to-permission mappings
│ │ │
│ │ ├── constants/ # Application constants
│ │ │ ├── date.constants.ts # Date format constants
│ │ │ ├── route-enums.ts # PageRoute, ApiRoute enums
│ │ │ └── routes.ts # Route path constants
│ │ │
│ │ ├── rpc/ # API (Hono + OpenAPI)
│ │ │ ├── client/ # Type-safe API clients
│ │ │ │ ├── hono-client.ts # Base Hono client
│ │ │ │ ├── health-client.ts # Health check client
│ │ │ │ ├── permissions-client.ts # Permission check client
│ │ │ │ └── index.ts # Client exports
│ │ │ │
│ │ │ ├── middleware/ # Hono middleware
│ │ │ │ ├── authMiddleware.ts # Session validation
│ │ │ │ ├── permissionMiddleware.ts # requirePermissions()
│ │ │ │ └── sessionMiddleware.ts # Session enrichment
│ │ │ │
│ │ │ ├── routes/ # API route definitions
│ │ │ │ ├── auth.ts # Auth routes (login, logout)
│ │ │ │ ├── health/ # Health check routes
│ │ │ │ │ ├── health.route.ts # Route definitions
│ │ │ │ │ ├── health.handler.ts # Route handlers
│ │ │ │ │ └── index.ts # Combined export
│ │ │ │ └── permissions/ # Permission check routes
│ │ │ │ ├── permissions.route.ts
│ │ │ │ ├── permissions.handler.ts
│ │ │ │ └── index.ts
│ │ │ │
│ │ │ ├── schemas/ # Zod validation schemas
│ │ │ │ ├── openapi-common.schema.ts # Shared OpenAPI schemas
│ │ │ │ └── pagination.schema.ts # Pagination schemas
│ │ │ │
│ │ │ ├── utils/ # RPC utilities
│ │ │ │ └── transformers.ts # Data transformers
│ │ │ │
│ │ │ └── index.ts # Route exports
│ │ │
│ │ ├── security/ # Security utilities
│ │ │ └── sanitization.ts # Input sanitization
│ │ │
│ │ ├── logger.ts # Pino logger configuration
│ │ └── utils.ts # General utilities (cn)
│ │
│ ├── providers/ # React context providers
│ │ └── query-provider.tsx # TanStack Query provider
│ │
│ ├── stores/ # Zustand state stores
│ │ ├── usePermissionsStore.ts # Permission state management
│ │ └── index.ts # Store exports
│ │
│ ├── types/ # TypeScript type definitions
│ │ ├── hono.ts # Hono AppBindings, context types
│ │ └── pagination.ts # Pagination types
│ │
│ ├── utils/ # Utility functions
│ │ └── handleApiError.ts # API error handling
│ │
│ ├── env.ts # Environment variable validation
│ ├── instrumentation.ts # Next.js instrumentation
│ └── proxy.ts # Route protection middleware
│
├── supabase/migrations/ # Database migrations
│
├── .husky/ # Git hooks
│ ├── pre-commit # Lint-staged
│ ├── pre-push # Typecheck
│ └── post-merge # pnpm install
│
├── .env.example # Environment variables template
├── CLAUDE.md # Detailed architecture docs
├── drizzle.config.ts # Drizzle ORM configuration
├── next.config.ts # Next.js configuration
├── package.json # Dependencies and scripts
└── tsconfig.json # TypeScript configuration
# Development
pnpm dev # Start dev server with Turbopack
pnpm build # Build for production
pnpm start # Production server
# Code Quality
pnpm lint # ESLint
pnpm typecheck # TypeScript strict check
pnpm format # Prettier
# Database
pnpm db:generate # Generate migrations (use --name flag)
pnpm db:push # Run migrations
pnpm db:studio # Drizzle Studio GUI
pnpm db:seed # Seed admin user + organizationSee CLAUDE.md for detailed architecture documentation and patterns for:
- Adding new API routes (OpenAPI + Hono)
- Adding new database tables
- Adding new permissions and roles
- Adding new pages with RBAC protection
- Form patterns, table patterns, and code style conventions
MIT