Fullstack Starter

English | 한국어

Template versioning via Release Please — see CHANGELOG.md for release history.

Production-ready fullstack monorepo template with Next.js 16, FastAPI, Flutter, and GCP infrastructure.

3-Tier Architecture

graph TB
    subgraph Client
        Web[Next.js 16<br/>React 19]
        Mobile[Flutter 3.38<br/>Riverpod]
    end

    subgraph GCP["GCP Cloud Run"]
        API[FastAPI<br/>Python 3.12]
        Worker[Worker<br/>CloudTasks]
    end

    subgraph Data
        DB[(PostgreSQL 16)]
        Cache[(Redis 7)]
        Storage[(Cloud Storage)]
    end

    Web --> API
    Mobile --> API
    API --> DB
    API --> Cache
    API --> Worker
    Worker --> DB
    API --> Storage

    style Web fill:#0070f3,color:#fff
    style Mobile fill:#02569B,color:#fff
    style API fill:#009688,color:#fff
    style Worker fill:#009688,color:#fff
    style DB fill:#336791,color:#fff
    style Cache fill:#DC382D,color:#fff
    style Storage fill:#4285F4,color:#fff

Key Features

• Modern Stack: Next.js 16 + React 19, FastAPI, Flutter 3.38, TailwindCSS v4
• Type Safety: Full type support with TypeScript, Pydantic, and Dart
• Authentication: OAuth with better-auth (Google, GitHub, Facebook)
• Internationalization: next-intl (web), Flutter ARB (mobile), shared i18n package
• Auto-generated API Clients: Orval (web), swagger_parser (mobile)
• Infrastructure as Code: Terraform + GCP (Cloud Run, Cloud SQL, Cloud Storage)
• CI/CD: GitHub Actions + Workload Identity Federation (keyless deployment)
• AI Agent Support: Guidelines for AI coding agents (Gemini, Claude, etc.)
• mise Monorepo: mise-based task management and unified tool versions

Tech Stack

| Layer | Technology | |-------|------------| | Frontend | Next.js 16, React 19, TailwindCSS v4, shadcn/ui, TanStack Query, Jotai | | Backend | FastAPI, SQLAlchemy (async), PostgreSQL 16, Redis 7 | | Mobile | Flutter 3.38, Riverpod 3, go_router 17, Firebase Crashlytics, Fastlane | | Worker | FastAPI + CloudTasks/PubSub | | Infrastructure | Terraform, GCP (Cloud Run, Cloud SQL, Cloud Storage, CDN) | | CI/CD | GitHub Actions, Workload Identity Federation | | Tool Management | mise (unified Node, Python, Flutter, Terraform versions) |

Why this tech stack? — Detailed reasoning behind each technology choice.

AI Agent Orchestration

This template includes a multi-agent coordination workflow for complex cross-domain tasks.

graph TB
    subgraph Coordination["Coordination Layer"]
        User([User Request])
        PM[PM Agent<br/>Task Decomposition]
    end

    subgraph Execution["Parallel Execution"]
        FE[Frontend Agent<br/>Next.js/Flutter]
        BE[Backend Agent<br/>FastAPI]
        Infra[Infra Agent<br/>Terraform]
    end

    subgraph Review["Quality Assurance"]
        QA[QA Agent<br/>Security/A11y/Perf]
    end

    User --> PM
    PM --> FE & BE & Infra
    FE & BE & Infra --> QA
    QA -->|Issues Found| FE & BE & Infra
    QA -->|Approved| Done([Complete])

    style PM fill:#8B5CF6,color:#fff
    style FE fill:#0070f3,color:#fff
    style BE fill:#009688,color:#fff
    style Infra fill:#F59E0B,color:#fff
    style QA fill:#EF4444,color:#fff

| Agent | Role | |-------|------| | PM Agent | Analyzes requirements, defines API contracts, creates prioritized task breakdown | | Domain Agents | Frontend, Backend, Mobile, Infra agents execute tasks in parallel by priority | | QA Agent | Reviews security (OWASP), performance, accessibility (WCAG 2.1 AA) |

See .agent/workflows/coordinate.md for the full orchestration workflow.

Quick Start

Choose one of the following methods to start with this template:

# Create from CLI
bun create fullstack-starter my-app
# or
npm create fullstack-starter my-app

Or use GitHub:

1. Click Use this template to create a new repository
2. Or Fork this repository

Prerequisites

Required for all platforms:

• mise - Runtime version manager
• Docker or Podman Desktop - Local infrastructure

For mobile development (iOS/Android):

• Xcode - Includes iOS Simulator (macOS only)
• Android Studio - Includes Android SDK and emulator

Optional:

• Terraform - Cloud infrastructure

1. Install Runtimes

# Install mise (if not installed)
curl https://mise.run | sh

# Install all runtimes (Node 24, Python 3.12, Flutter 3, bun, uv, Terraform)
mise install

2. Install Dependencies

# Install all dependencies at once
mise run install

3. Start Local Infrastructure

mise infra:up

This starts:

• PostgreSQL (5432)
• Redis (6379)
• MinIO (9000, 9001)

4. Run Database Migrations

mise db:migrate

5. Start Development Servers

# Start API and Web services (recommended for web development)
mise dev:web

# Start API and Mobile services (recommended for mobile development)
mise dev:mobile

# Or start all services
mise dev

Project Structure

fullstack-starter/
├── apps/
│   ├── api/           # FastAPI backend
│   ├── web/           # Next.js frontend
│   ├── worker/        # Background worker
│   ├── mobile/        # Flutter mobile app
│   └── infra/         # Terraform infrastructure
├── packages/
│   ├── design-tokens/ # Shared design tokens (Source of Truth)
│   └── i18n/          # Shared i18n package (Source of Truth)
├── .agent/rules/      # AI agent guidelines
├── .serena/           # Serena MCP config
└── .github/workflows/ # CI/CD

Commands

mise Monorepo Tasks

This project uses mise monorepo mode with //path:task syntax.

# List all available tasks
mise tasks --all

| Command | Description | |---------|-------------| | mise db:migrate | Run database migrations | | mise dev | Start all services | | mise dev:web | Start API and Web services | | mise dev:mobile | Start API and Mobile services | | mise format | Format all apps | | mise gen:api | Generate OpenAPI schema and API clients | | mise i18n:build | Build i18n files | | mise infra:down | Stop local infrastructure | | mise infra:up | Start local infrastructure | | mise lint | Lint all apps | | mise run install | Install all dependencies | | mise test | Test all apps | | mise tokens:build | Build design tokens | | mise typecheck | Type check |

App-specific Tasks

| Command | Description | |---------|-------------| | mise //apps/api:install | Install dependencies | | mise //apps/api:dev | Start development server | | mise //apps/api:test | Run tests | | mise //apps/api:lint | Run linter | | mise //apps/api:format | Format code | | mise //apps/api:typecheck | Type check | | mise //apps/api:migrate | Run migrations | | mise //apps/api:migrate:create | Create new migration | | mise //apps/api:gen:openapi | Generate OpenAPI schema | | mise //apps/api:infra:up | Start local infrastructure | | mise //apps/api:infra:down | Stop local infrastructure |

| Command | Description | |---------|-------------| | mise //apps/web:install | Install dependencies | | mise //apps/web:dev | Start development server | | mise //apps/web:build | Production build | | mise //apps/web:test | Run tests | | mise //apps/web:lint | Run linter | | mise //apps/web:format | Format code | | mise //apps/web:typecheck | Type check | | mise //apps/web:gen:api | Generate API client |

| Command | Description | |---------|-------------| | mise //apps/mobile:install | Install dependencies | | mise //apps/mobile:dev | Run on device/simulator | | mise //apps/mobile:build | Build | | mise //apps/mobile:test | Run tests | | mise //apps/mobile:lint | Run analyzer | | mise //apps/mobile:format | Format code | | mise //apps/mobile:gen:l10n | Generate localizations | | mise //apps/mobile:gen:api | Generate API client |

| Command | Description | |---------|-------------| | mise //apps/worker:install | Install dependencies | | mise //apps/worker:dev | Start worker | | mise //apps/worker:test | Run tests | | mise //apps/worker:lint | Run linter | | mise //apps/worker:format | Format code |

| Command | Description | |---------|-------------| | mise //apps/infra:init | Initialize Terraform | | mise //apps/infra:plan | Preview changes | | mise //apps/infra:apply | Apply changes | | mise //apps/infra:plan:prod | Preview production | | mise //apps/infra:apply:prod | Apply production |

| Command | Descri