Fullstack Starter
English | 한국어 | 简体中文 | 日本語 | Português
Template versioning via Release Please — see CHANGELOG.md for release history.
Production-ready fullstack monorepo template with Next.js 16, Litestar, Flutter, and GCP infrastructure.
3-Tier Architecture
graph TB
subgraph Client
Web[Next.js 16<br/>React 19]
Mobile[Flutter 3.44.8<br/>Riverpod]
end
subgraph GCP["GCP Cloud Run"]
API[Litestar<br/>Python 3.14]
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, Litestar, Flutter 3.44.8, TailwindCSS v4
- Type Safety: Full type support with TypeScript, msgspec, and Dart
- Authentication: Email/password, OAuth Authorization Code (Google/GitHub PKCE, Facebook), and WebAuthn passkeys
- 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 |
Litestar, msgspec, SQLAlchemy (async), PostgreSQL 16, Redis 7 |
| Mobile |
Flutter 3.44.8, Riverpod 3, go_router 17, Firebase Crashlytics, Fastlane |
| Worker |
Litestar + 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) |
API health/auth routes and worker health/task routes use Litestar Controllers. Routers group paths and dependencies. Worker health receives its scheduler through router-scoped dependency injection, keeping each application's runtime separate. The task controller's OIDC guard uses that application's settings and verifies each token once before background work runs, including when the controller is registered directly.
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/>Litestar]
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 .agents/workflows/work.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:
- Click Use this template to create a new repository
- Or Fork this repository
Prerequisites
Required for all platforms:
For mobile development (iOS/Android):
Optional:
1. Install Runtimes
# Install mise (if not installed)
curl https://mise.run | sh
# Trust project config (required on first clone)
mise trust
# Install all runtimes (Node 26, Python 3.14, 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/
├── package.json # bun workspace (apps/web, packages/*)
├── pyproject.toml # uv workspace (apps/api, apps/worker)
├── apps/
│ ├── api/ # Litestar 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)
├── .agents/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
API (apps/api)
| 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 |
Web (apps/web)
| 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 |
Mobile (apps/mobile)
| 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 |
Worker (apps/worker)
| 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 |
Infrastructure (apps/infra/gcp, apps/infra/aws, apps/infra/vm, ...)
| Command |
Description |
mise //apps/infra:gcp:init |
Initialize Terraform |
mise //apps/infra:gcp:plan |
Preview changes |
mise //apps/infra:gcp:apply |
Apply changes |
mise //apps/infra:gcp:plan:prod |
Preview production |
mise //apps/infra:gcp:apply:prod |
Apply production |
mise //apps/infra:vm:apply:prod |
Provision a single Compute Engine VM (Terraform) |
mise //apps/infra:vm:deploy |
Configure the VM and deploy images (Ansible) |
See apps/infra/README.md for all stacks (GCP, AWS, Azure, OCI, freemium, single VM).
i18n (packages/i18n)
| Command |
Description |
mise //packages/i18n:install |
Install dependencies |
mise //packages/i18n:build |
Build i18n files for web and mobile |
mise //packages/i18n:build:web |
Build for web only |
mise //packages/i18n:build:mobile |
Build for mobile only |
Design Tokens (packages/design-tokens)
| Command |
Description |
mise //packages/design-tokens:install |
Install dependencies |
mise //packages/design-tokens:build |
Build tokens for web and mobile |
mise //packages/design-tokens:dev |
Watch mode for development |
mise //packages/design-tokens:test |
Run tests |
Internationalization (i18n)
packages/i18n is the Single Source of Truth for i18n resources.
# Edit i18n files
packages/i18n/src/en.arb # English (default)
packages/i18n/src/ko.arb # Korean
packages/i18n/src/ja.arb # Japanese
# Build and deploy to each app
mise i18n:build
# Generated files:
# - apps/web/src/config/messages/*.json (Nested JSON)
# - apps/mobile/lib/i18n/messages/app_*.arb (Flutter ARB)
Design Tokens
packages/design-tokens is the Single Source of Truth for design tokens (colors, spacing, etc.).
# Edit tokens
packages/design-tokens/src/tokens.ts
# Build and distribute
mise tokens:build
# Generated files:
# - apps/web/src/app/[locale]/tokens.css (CSS variables)
# - apps/mobile/lib/core/theme/generated_theme.dart (Flutter Theme)
Configuration
Environment Variables
Copy example files and configure:
# API
cp apps/api/.env.example apps/api/.env
# Web
cp apps/web/.env.example apps/web/.env
# Infra
cp apps/infra/gcp/terraform.tfvars.example apps/infra/gcp/terraform.tfvars
GitHub Actions Secrets
Set these secrets in your repository:
| Secret |
Description |
GCP_PROJECT_ID |
GCP project ID |
GCP_REGION |
GCP region (e.g., asia-northeast3) |
WORKLOAD_IDENTITY_PROVIDER |
From Terraform output |
GCP_SERVICE_ACCOUNT |
From Terraform output |
FIREBASE_SERVICE_ACCOUNT_JSON |
Firebase service account JSON (for mobile deployment) |
FIREBASE_ANDROID_APP_ID |
Firebase Android app ID |
Firebase (Mobile)
- Install FlutterFire CLI:
dart pub global activate flutterfire_cli
- Configure Firebase for your project:
cd apps/mobile
flutterfire configure
This generates lib/firebase_options.dart with your Firebase configuration.
Deployment
GitHub Actions (Recommended)
Push to main branch triggers automatic deployment:
apps/api/ changes → Deploy API
apps/web/ changes → Deploy Web
apps/worker/ changes → Deploy Worker
apps/mobile/ changes → Build & Deploy to Firebase App Distribution
Manual Deployment
# Build and push Docker images from the repository root
docker build -f apps/api/Dockerfile -t gcr.io/PROJECT_ID/api .
docker push gcr.io/PROJECT_ID/api
# Deploy to Cloud Run
gcloud run deploy api --image gcr.io/PROJECT_ID/api --region REGION
Mobile (Fastlane)
The mobile app uses Fastlane for build automation and deployment.
cd apps/mobile
# Install Ruby dependencies
bundle install
# Available lanes
bundle exec fastlane android build # Build APK
bundle exec fastlane android firebase # Deploy to Firebase App Distribution
bundle exec fastlane android internal # Deploy to Play Store (internal)
bundle exec fastlane ios build # Build iOS (no codesign)
bundle exec fastlane ios testflight_deploy # Deploy to TestFlight
AI Agent Support
This template is designed to work with AI coding agents (Gemini, Claude, etc.).
.agents/rules/ - Guidelines for AI agents
.serena/ - Serena MCP configuration
Try oh-my-agent to maximize productivity with AI coding agents.
Documentation
License
MIT
Sponsors
If this project helped you, please consider buying me a coffee!

Or leave a star:
gh api --method PUT /user/starred/first-fluke/fullstack-starter
Star History