component-refactoring

• 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

| 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?](./docs/WHY.md) — Detailed reasoning behind each technology choice.


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

```mermaid

graph TB

subgraph Coordination["Coordination Layer"]

User([User Request])

PM[PM Agent
Task Decomposition]

end

subgraph Execution["Parallel Execution"]

FE[Frontend Agent
Next.js/Flutter]

BE[Backend Agent
FastAPI]

Infra[Infra Agent
Terraform]

end

subgraph Review["Quality Assurance"]

QA[QA Agent
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](.agent/workflows/coordinate.md) for the full orchestration workflow.

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

```bash

# Create from CLI

bun create fullstack-starter my-app

# or

npm create fullstack-starter my-app

```

Or use GitHub:

1. Click [Use this template](https://github.com/first-fluke/fullstack-starter/generate) to create a new repository
2. Or [Fork](https://github.com/first-fluke/fullstack-starter/fork) this repository

Prerequisites

Required for all platforms:

• [mise](https://mise.jdx.dev/) - Runtime version manager
• [Docker](https://www.docker.com/) or [Podman Desktop](https://podman-desktop.io/downloads) - Local infrastructure

For mobile development (iOS/Android):

• [Xcode](https://apps.apple.com/app/xcode/id497799835) - Includes iOS Simulator (macOS only)
• [Android Studio](https://developer.android.com/studio) - Includes Android SDK and emulator

Optional:

• [Terraform](https://www.terraform.io/) - Cloud infrastructure

1. Install Runtimes

```bash

# 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

```bash

# Install all dependencies at once

mise run install

```

3. Start Local Infrastructure

```bash

mise infra:up

```

This starts:

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

4. Run Database Migrations

```bash

mise db:migrate

```

5. Start Development Servers

```bash

# 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

```

```

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

```

mise Monorepo Tasks

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

```bash

# 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