🚀 API Boilerplate with Advanced RBAC

A production-ready REST API boilerplate built with Hono and TypeScript, featuring a sophisticated Role-Based Access Control (RBAC) system, multi-tenant organizations, and modern authentication.

⚡ Why This Boilerplate?

• 🔐 Enterprise RBAC: Multi-level permissions (App + Organization roles) with granular access control
• 🏢 Multi-Tenant Ready: Complete organization management with teams, invitations, and member roles
• ⚡ High Performance: Built on Hono framework with Bun runtime for maximum speed
• 🔑 Modern Auth: Better-Auth integration with session-based security
• 📊 Production Database: MySQL 8.0 + Prisma ORM with type safety
• 🧪 Developer Experience: Hot reload, comprehensive logging, auto-generated docs
• 📝 Complete Documentation: Detailed API docs with OpenAPI specification

🛠️ Tech Stack

Component	Technology	Version
Runtime	Bun	Latest
Framework	Hono	^4.9.6
Authentication	Better-Auth	^1.3.7
Database	MySQL + Prisma	8.0 + ^6.15.0
Validation	Zod	^4.0
Logging	Pino	^9.9.1
Code Quality	BiomeJS	^2.2.2

🚀 Quick Start

Prerequisites

• Bun runtime installed (Install Guide)
• Docker for database (or local MySQL 8.0)
• Git for cloning

1. Setup Project

# Clone and install dependencies
git clone <repository-url>
cd api-boilerplate
bun install

2. Configure Environment

# Copy environment template
cp .env.example .env

Essential environment variables:

# Better Auth Configuration
BETTER_AUTH_SECRET=your-super-secret-key-here-min-32-chars
BETTER_AUTH_URL=http://localhost:3000

# Database Configuration  
DATABASE_URL=mysql://app_user:app_password@localhost:3306/api_boilerplate
SHADOW_DATABASE_URL=mysql://app_user:app_password@localhost:3306/api_boilerplate_shadow

# Application
NODE_ENV=development
APP_PORT=3000

3. Start Database

# Start MySQL with Docker (recommended)
docker-compose up -d mysql

# Verify database is ready
docker-compose ps

4. Initialize Database

# Generate Prisma client and run migrations
bun run db:generate
bun run db:migrate

5. Start Development

# Start with hot reload
bun run dev
# ✅ API running at http://localhost:3000/api/v1

🎯 Test Your Setup

# Test public endpoints
curl http://localhost:3000/api/v1/health/api
curl http://localhost:3000/api/v1/system/stats

# Test protected endpoint (expect 401)
curl http://localhost:3000/api/v1/me

🔐 Authentication & RBAC System

Authentication Flow

The API uses Better-Auth with session-based authentication:

1. Register/Login → Get session cookie
2. Session Management → Automatic cookie handling
3. Role Assignment → App-level roles (admin/user)
4. Organization Access → Join orgs with specific roles
5. Permission Validation → Middleware checks for each endpoint

RBAC Hierarchy

🎯 App-Level Roles
├── admin → System administrator (global access to /admin/*)
└── user  → Authenticated user (access to /me/* + organization features)

🏢 Organization-Level Roles  
├── owner  → Full control (delete org, manage all)
├── admin  → Manage members, teams, settings
└── member → Basic access to organization resources

Permission Model

Permissions are structured around resources and actions:

• Resources: user, organization, team, invitation, member
• Actions: create, read, update, delete, manage, invite, ban

Example Permission Checks:

// Organization admin can invite members
user.hasPermission('invitation.create', organizationId)

// Only owners can delete organizations  
user.hasRole('owner', organizationId)

// System admins bypass organization permissions
user.hasSystemRole('admin')

📚 API Overview

Endpoint Categories

Category	Base Path	Authentication	Description
System	/api/v1/health/*	Public	Health checks and system status
Documentation	/api/v1/docs/*	Public	Interactive API documentation with Scalar UI
Auth	/api/v1/auth/*	Public	Better-Auth endpoints (auto-generated)
User	/api/v1/me/*	Session Required	User profile, organizations, invitations
Organizations	/api/v1/organizations/*	Session + Membership	Multi-tenant org management
Admin	/api/v1/admin/*	Admin Role Required	System administration

Essential API Examples

User Registration & Login

# Register new user
curl -X POST http://localhost:3000/api/v1/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"password123","name":"Developer"}'

# Login (get session cookie)
curl -X POST http://localhost:3000/api/v1/auth/sign-in \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"dev@example.com","password":"password123"}'

User Profile & Organizations

# Get my profile (with session)
curl http://localhost:3000/api/v1/me \
  -b cookies.txt

# Get my organizations
curl http://localhost:3000/api/v1/me/organizations \
  -b cookies.txt

Organization Management

# Create organization
curl -X POST http://localhost:3000/api/v1/organizations \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"My Company","slug":"my-company"}'

# Invite member to organization  
curl -X POST http://localhost:3000/api/v1/organizations/{id}/invite \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"email":"member@example.com","role":"admin"}'

Admin Operations (Admin Role Required)

# List all users with pagination
curl http://localhost:3000/api/v1/admin/users?page=1&limit=10 \
  -b cookies.txt

# Ban a user
curl -X POST http://localhost:3000/api/v1/admin/users/{id}/ban \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"reason":"Policy violation","expiresAt":"2024-12-31T23:59:59Z"}'

🛠️ Development Commands

Core Development

bun run dev              # Start with hot reload
bun run build            # Build for production  
bun run start            # Start production server

Database Management

bun run db:generate      # Generate Prisma client
bun run db:migrate       # Create and run migrations
bun run db:studio        # Open Prisma Studio (DB GUI)
bun run db:push          # Push schema changes
bun run db:reset         # Reset database (⚠️ destroys data)

Code Quality & Documentation

bun run lint             # Run BiomeJS linter
bun run lint:fix         # Auto-fix linting issues
bun run typecheck        # Run TypeScript type checking
bun run gen:sdk          # Generate SDK client from OpenAPI spec

Docker Operations

# Database only
docker-compose up -d mysql

# Database + Monitoring Stack
docker-compose up -d mysql loki promtail grafana

# View logs
docker-compose logs mysql
docker-compose logs grafana

# Stop services
docker-compose down

# Full stack (uncomment api service in docker-compose.yml)
docker-compose up -d

📊 Monitoring & Observability

The project includes a complete Grafana monitoring stack with:

• Grafana: Web interface at http://localhost:3001 (admin/admin123)
• Loki: Log aggregation and storage (30-day retention)
• Promtail: Automatic log collection from /logs/ directory

Start Monitoring

# Start monitoring stack
docker-compose up -d loki promtail grafana

# Verify services
docker-compose ps

Pre-built Dashboards

Dashboard	URL	Purpose
API Performance	http://localhost:3001/d/api-performance	Response times, request rates, status codes
Auth & Security	http://localhost:3001/d/auth-security	Login events, admin actions, security alerts
System Health	http://localhost:3001/d/system-health	API status, errors, database connectivity
RBAC Activity	http://localhost:3001/d/rbac-activity	Organization operations, permissions

Quick Monitoring Setup

1. Ensure log generation: Set NODE_ENV=production in .env
2. Start monitoring: docker-compose up -d loki promtail grafana
3. Access Grafana: http://localhost:3001 (admin/admin123)
4. View dashboards: Pre-configured dashboards appear automatically

See Monitoring Documentation for detailed setup and customization.

🧪 Testing & Debugging

Development Logging

The API includes comprehensive logging with Pino:

• Console: Pretty-formatted logs in development
• Files: Structured JSON logs in production
• Categories: Access, errors, auth events, admin actions, system events

# View recent errors
tail -f logs/error.log

# Monitor API access
tail -f logs/access.log

# Watch auth events
tail -f logs/auth.log

Common Debugging

# Check API health
curl http://localhost:3000/api/v1/health/api

# Verify database connection
curl http://localhost:3000/api/v1/health/db

# Test authentication (should return 401 without session)
curl http://localhost:3000/api/v1/me

# Check your permissions
curl http://localhost:3000/api/v1/system/permissions -b cookies.txt

📖 Complete Documentation

Document	Description	Use Case
📋 Quick Reference	Concise endpoint tables by role	Fast API lookup during development
📚 Complete API Docs	Detailed endpoint docs with schemas	Integration development
📝 Logging Guide	Logging system & monitoring setup	Production debugging & monitoring
🗺️ Documentation Index	Navigation & architecture overview	Understanding system design

Interactive API Documentation

The API includes comprehensive interactive documentation powered by Scalar UI:

# Access interactive documentation
open http://localhost:3000/api/v1/docs

# View OpenAPI specification
open http://localhost:3000/api/v1/docs/openapi.json

# Better-Auth specific docs
open http://localhost:3000/api/v1/docs/auth-openapi.json

# Generate SDK client
bun run gen:sdk

The documentation includes:

• Interactive API explorer with request/response examples
• Authentication guide with Better-Auth integration
• RBAC documentation explaining permissions and roles
• Schema validation showing Zod validation rules

🗂️ Project Structure

src/
├── index.ts                    # Application entry point + main router
├── config.ts                   # Environment configuration
├── api/                        # API route handlers organized by feature
│   ├── index.ts               # Main router combining all sub-routers
│   ├── auth/                  # Authentication routes
│   │   ├── auth.ts            # Better-Auth integration handler
│   │   └── me.ts              # User profile routes
│   ├── admin/                 # Administration routes
│   │   ├── admin.ts           # Global admin routes (user mgmt, stats)
│   │   └── organizations.ts   # Admin organization oversight
│   ├── system/                # System routes
│   │   └── index.ts           # Health checks and system info
│   └── docs/                  # Documentation routes
│       ├── index.ts           # Interactive API docs with Scalar UI
│       └── openapi.json       # OpenAPI 3.0 specification
├── lib/                       # Core libraries
│   ├── auth.ts                # Bette