Cobalt Stack

Modern full-stack application template with Rust backend (Axum + SeaORM) and Next.js 16 frontend (Bun + React Query + shadcn/ui).

Repository: https://github.com/Ameyanagi/cobalt-stack

• Modern Rust Backend: Axum 0.7+ with SeaORM for type-safe database access
• Next.js 16 Frontend: App Router with TypeScript and shadcn/ui components
• Type Safety: OpenAPI schema generation with automatic TypeScript type generation
• Authentication: JWT-based auth with email verification and role-based access control
• Admin System: Complete admin dashboard with user management
• Testing: TDD workflow with cargo-tarpaulin coverage reporting
• Docker Ready: Optimized multi-stage builds with BuildKit cache mounts
• Development Tools: Hot reload, code generation, linting, and formatting

• Rust 1.75+ (install)
• Bun 1.2+ (install)
• Docker & Docker Compose (install)
• Make (usually pre-installed on macOS/Linux)

# Clone the repository
git clone https://github.com/Ameyanagi/cobalt-stack
cd cobalt-stack

# Setup environment and install dependencies
make setup

# Start all services with Docker Compose
make dev

Access the application:

• Frontend: http://localhost:3001
• Backend API: http://localhost:3002/health
• Swagger UI: http://localhost:3002/swagger-ui

# Run database migrations
make migrate

# Create initial admin user (development only)
make seed-admin
# Email: admin@example.com | Password: admin123

Comprehensive guides and references for all aspects of the project:

• Getting Started - Installation, setup, and first steps
• Backend Documentation - Rust backend architecture and API development
• Frontend Documentation - Next.js frontend development and components
• API Reference - Complete API endpoint documentation
• Deployment Guide - Production deployment and configuration
• Contributing Guide - Development workflow and contribution guidelines

# Full stack with Docker Compose
make dev

# Backend only (hot reload)
make dev-backend

# Frontend only (dev server)
make dev-frontend

# Run all tests
make test

# Watch mode (auto-rerun)
make test-watch

# Coverage report
make test-coverage

# Lint, format, and test
make ci

# Individual commands
make lint      # Run clippy
make fmt       # Format code
make fmt-check # Check formatting

# Generate OpenAPI schema from backend
make generate-openapi

# Generate TypeScript types from schema
make generate-types

• Framework: Axum 0.7+ (async web framework)
• ORM: SeaORM 1.1+ with PostgreSQL
• Runtime: Tokio async runtime
• API Docs: utoipa for OpenAPI 3.0 generation
• Testing: cargo-test with 100% coverage requirement for domain logic

• Framework: Next.js 16 App Router
• Runtime: Bun 1.2+
• UI Components: shadcn/ui + Radix UI + TailwindCSS 4.1
• State Management: React Query 5.x
• Type Safety: TypeScript strict mode with OpenAPI-generated types

• Domain-Driven Design: Clear separation between handlers, services, and models
• Type Safety: End-to-end type safety from database to frontend
• Test-Driven Development: Red → Green → Refactor workflow
• OpenSpec Workflow: Proposal-based change management for significant features

cobalt-stack/
├── backend/              # Rust backend (Axum + SeaORM)
│   ├── src/
│   │   ├── handlers/    # HTTP request handlers
│   │   ├── services/    # Business logic (DDD)
│   │   ├── models/      # Database models
│   │   └── middleware/  # Auth and middleware
│   ├── migration/       # Database migrations
│   └── tests/           # Integration tests
├── frontend/            # Next.js frontend (Bun + React)
│   ├── src/
│   │   ├── app/        # App Router pages
│   │   ├── components/ # shadcn/ui components
│   │   └── lib/        # API client and utilities
├── openapi/            # Generated OpenAPI schema
├── docs/               # Project documentation
├── docker-compose.yml  # Development environment
└── Makefile           # Task automation

Copy .env.example to .env and customize:

# Service Ports
FRONTEND_PORT=2727
BACKEND_PORT=2750
POSTGRES_PORT=2800
REDIS_PORT=2900

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:2750

# Database
POSTGRES_DB=cobalt_dev
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

Required variables for docker-compose.prod.yml:

DATABASE_PASSWORD  # PostgreSQL password
REDIS_PASSWORD     # Redis password
JWT_SECRET         # JWT signing secret
EMAIL_MOCK=false   # Enable real SMTP

See Deployment Guide for complete production setup.

MIT License - see LICENSE file for details.

Copyright (c) 2025 Cobalt Stack Contributors

1. Review the Contributing Guide
2. Create OpenSpec proposal for significant changes
3. Follow TDD workflow (Red → Green → Refactor)
4. Ensure make ci passes before submitting PR

• Axum Documentation
• SeaORM Guide
• Next.js Documentation
• OpenSpec Workflow

Built with Rust, Axum, SeaORM, and Next.js