{"id":37797497,"url":"https://github.com/first-fluke/fullstack-starter","last_synced_at":"2026-04-02T14:25:02.945Z","repository":{"id":331742440,"uuid":"1129537143","full_name":"first-fluke/fullstack-starter","owner":"first-fluke","description":"Production-ready fullstack monorepo template with Next.js, FastAPI, Flutter, Terraform, and mise","archived":false,"fork":false,"pushed_at":"2026-04-01T03:10:23.000Z","size":1892,"stargazers_count":204,"open_issues_count":0,"forks_count":30,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-01T04:10:35.400Z","etag":null,"topics":["antigravity","fastapi","flutter","gcp","mise","monorepo","nextjs","opencode","python","template","terraform","typescript"],"latest_commit_sha":null,"homepage":"https://deepwiki.org/first-fluke/fullstack-starter","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/first-fluke.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"first-fluke","buy_me_a_coffee":"firstfluke"}},"created_at":"2026-01-07T08:24:56.000Z","updated_at":"2026-04-01T03:10:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/first-fluke/fullstack-starter","commit_stats":null,"previous_names":["first-fluke/fullstack-starter"],"tags_count":27,"template":true,"template_full_name":null,"purl":"pkg:github/first-fluke/fullstack-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/first-fluke%2Ffullstack-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/first-fluke%2Ffullstack-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/first-fluke%2Ffullstack-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/first-fluke%2Ffullstack-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/first-fluke","download_url":"https://codeload.github.com/first-fluke/fullstack-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/first-fluke%2Ffullstack-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antigravity","fastapi","flutter","gcp","mise","monorepo","nextjs","opencode","python","template","terraform","typescript"],"created_at":"2026-01-16T15:21:37.830Z","updated_at":"2026-04-02T14:25:02.939Z","avatar_url":"https://github.com/first-fluke.png","language":"TypeScript","readme":"# Fullstack Starter\n\n[![GitHub Repo stars](https://img.shields.io/github/stars/first-fluke/fullstack-starter?logo=githubsponsors)](https://github.com/first-fluke/fullstack-starter/stargazers)\n[![Last Commit](https://img.shields.io/github/last-commit/first-fluke/fullstack-starter/main?label=last%20updated\u0026logo=github\u0026logoColor=white)](https://github.com/first-fluke/fullstack-starter)\n[![Version](https://img.shields.io/github/v/release/first-fluke/fullstack-starter?label=version)](https://github.com/first-fluke/fullstack-starter/releases)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/first-fluke/fullstack-starter)\n\nEnglish | [한국어](./docs/README.ko.md) | [简体中文](./docs/README.cn.md) | [日本語](./docs/README.jp.md) | [Português](./docs/README.pt.md)\n\n\u003e Template versioning via [Release Please](https://github.com/googleapis/release-please) — see [CHANGELOG.md](./CHANGELOG.md) for release history.\n\nProduction-ready fullstack monorepo template with Next.js 16, FastAPI, Flutter, and GCP infrastructure.\n\n### 3-Tier Architecture\n\n```mermaid\ngraph TB\n    subgraph Client\n        Web[Next.js 16\u003cbr/\u003eReact 19]\n        Mobile[Flutter 3.41.2\u003cbr/\u003eRiverpod]\n    end\n\n    subgraph GCP[\"GCP Cloud Run\"]\n        API[FastAPI\u003cbr/\u003ePython 3.12]\n        Worker[Worker\u003cbr/\u003eCloudTasks]\n    end\n\n    subgraph Data\n        DB[(PostgreSQL 16)]\n        Cache[(Redis 7)]\n        Storage[(Cloud Storage)]\n    end\n\n    Web --\u003e API\n    Mobile --\u003e API\n    API --\u003e DB\n    API --\u003e Cache\n    API --\u003e Worker\n    Worker --\u003e DB\n    API --\u003e Storage\n\n    style Web fill:#0070f3,color:#fff\n    style Mobile fill:#02569B,color:#fff\n    style API fill:#009688,color:#fff\n    style Worker fill:#009688,color:#fff\n    style DB fill:#336791,color:#fff\n    style Cache fill:#DC382D,color:#fff\n    style Storage fill:#4285F4,color:#fff\n```\n\n## Key Features\n\n- **Modern Stack**: Next.js 16 + React 19, FastAPI, Flutter 3.41.2, TailwindCSS v4\n- **Type Safety**: Full type support with TypeScript, Pydantic, and Dart\n- **Authentication**: OAuth with better-auth (Google, GitHub, Facebook)\n- **Internationalization**: next-intl (web), Flutter ARB (mobile), shared i18n package\n- **Auto-generated API Clients**: Orval (web), swagger_parser (mobile)\n- **Infrastructure as Code**: Terraform + GCP (Cloud Run, Cloud SQL, Cloud Storage)\n- **CI/CD**: GitHub Actions + Workload Identity Federation (keyless deployment)\n- **AI Agent Support**: Guidelines for AI coding agents (Gemini, Claude, etc.)\n- **mise Monorepo**: mise-based task management and unified tool versions\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| **Frontend** | Next.js 16, React 19, TailwindCSS v4, shadcn/ui, TanStack Query, Jotai |\n| **Backend** | FastAPI, SQLAlchemy (async), PostgreSQL 16, Redis 7 |\n| **Mobile** | Flutter 3.41.2, Riverpod 3, go_router 17, Firebase Crashlytics, Fastlane |\n| **Worker** | FastAPI + CloudTasks/PubSub |\n| **Infrastructure** | Terraform, GCP (Cloud Run, Cloud SQL, Cloud Storage, CDN) |\n| **CI/CD** | GitHub Actions, Workload Identity Federation |\n| **Tool Management** | mise (unified Node, Python, Flutter, Terraform versions) |\n\n\u003e **[Why this tech stack?](./docs/WHY.md)** — Detailed reasoning behind each technology choice.\n\n![Fullstack](./docs/fullstack.jpg)\n\n## AI Agent Orchestration\n\nThis template includes a multi-agent coordination workflow for complex cross-domain tasks.\n\n```mermaid\ngraph TB\n    subgraph Coordination[\"Coordination Layer\"]\n        User([User Request])\n        PM[PM Agent\u003cbr/\u003eTask Decomposition]\n    end\n\n    subgraph Execution[\"Parallel Execution\"]\n        FE[Frontend Agent\u003cbr/\u003eNext.js/Flutter]\n        BE[Backend Agent\u003cbr/\u003eFastAPI]\n        Infra[Infra Agent\u003cbr/\u003eTerraform]\n    end\n\n    subgraph Review[\"Quality Assurance\"]\n        QA[QA Agent\u003cbr/\u003eSecurity/A11y/Perf]\n    end\n\n    User --\u003e PM\n    PM --\u003e FE \u0026 BE \u0026 Infra\n    FE \u0026 BE \u0026 Infra --\u003e QA\n    QA --\u003e|Issues Found| FE \u0026 BE \u0026 Infra\n    QA --\u003e|Approved| Done([Complete])\n\n    style PM fill:#8B5CF6,color:#fff\n    style FE fill:#0070f3,color:#fff\n    style BE fill:#009688,color:#fff\n    style Infra fill:#F59E0B,color:#fff\n    style QA fill:#EF4444,color:#fff\n```\n\n| Agent | Role |\n|-------|------|\n| **PM Agent** | Analyzes requirements, defines API contracts, creates prioritized task breakdown |\n| **Domain Agents** | Frontend, Backend, Mobile, Infra agents execute tasks in parallel by priority |\n| **QA Agent** | Reviews security (OWASP), performance, accessibility (WCAG 2.1 AA) |\n\n\u003e See [`.agents/workflows/coordinate.md`](.agents/workflows/coordinate.md) for the full orchestration workflow.\n\n## Quick Start\n\nChoose one of the following methods to start with this template:\n\n```bash\n# Create from CLI\nbun create fullstack-starter my-app\n# or\nnpm create fullstack-starter my-app\n```\n\nOr use GitHub:\n\n1. Click **[Use this template](https://github.com/first-fluke/fullstack-starter/generate)** to create a new repository\n2. Or **[Fork](https://github.com/first-fluke/fullstack-starter/fork)** this repository\n\n### Prerequisites\n\n**Required for all platforms:**\n- [mise](https://mise.jdx.dev/) - Runtime version manager\n- [Docker](https://www.docker.com/), [OrbStack](https://orbstack.dev/) (macOS), or [Podman Desktop](https://podman-desktop.io/downloads) - Local infrastructure\n\n**For mobile development (iOS/Android):**\n- [Xcode](https://apps.apple.com/app/xcode/id497799835) - Includes iOS Simulator (macOS only)\n- [Android Studio](https://developer.android.com/studio) - Includes Android SDK and emulator\n\n**Optional:**\n- [Terraform](https://www.terraform.io/) - Cloud infrastructure\n\n### 1. Install Runtimes\n\n```bash\n# Install mise (if not installed)\ncurl https://mise.run | sh\n\n# Trust project config (required on first clone)\nmise trust\n\n# Install all runtimes (Node 24, Python 3.12, Flutter 3, bun, uv, Terraform)\nmise install\n```\n\n### 2. Install Dependencies\n\n```bash\n# Install all dependencies at once\nmise run install\n```\n\n### 3. Start Local Infrastructure\n\n```bash\nmise infra:up\n```\n\nThis starts:\n- PostgreSQL (5432)\n- Redis (6379)\n- MinIO (9000, 9001)\n\n### 4. Run Database Migrations\n\n```bash\nmise db:migrate\n```\n\n### 5. Start Development Servers\n\n```bash\n# Start API and Web services (recommended for web development)\nmise dev:web\n\n# Start API and Mobile services (recommended for mobile development)\nmise dev:mobile\n\n# Or start all services\nmise dev\n```\n\n## Project Structure\n\n```\nfullstack-starter/\n├── apps/\n│   ├── api/           # FastAPI backend\n│   ├── web/           # Next.js frontend\n│   ├── worker/        # Background worker\n│   ├── mobile/        # Flutter mobile app\n│   └── infra/         # Terraform infrastructure\n├── packages/\n│   ├── design-tokens/ # Shared design tokens (Source of Truth)\n│   └── i18n/          # Shared i18n package (Source of Truth)\n├── .agents/rules/      # AI agent guidelines\n├── .serena/           # Serena MCP config\n└── .github/workflows/ # CI/CD\n```\n\n## Commands\n\n### mise Monorepo Tasks\n\nThis project uses mise monorepo mode with `//path:task` syntax.\n\n```bash\n# List all available tasks\nmise tasks --all\n```\n\n| Command | Description |\n|---------|-------------|\n| `mise db:migrate` | Run database migrations |\n| `mise dev` | Start all services |\n| `mise dev:web` | Start API and Web services |\n| `mise dev:mobile` | Start API and Mobile services |\n| `mise format` | Format all apps |\n| `mise gen:api` | Generate OpenAPI schema and API clients |\n| `mise i18n:build` | Build i18n files |\n| `mise infra:down` | Stop local infrastructure |\n| `mise infra:up` | Start local infrastructure |\n| `mise lint` | Lint all apps |\n| `mise run install` | Install all dependencies |\n| `mise test` | Test all apps |\n| `mise tokens:build` | Build design tokens |\n| `mise typecheck` | Type check |\n\n### App-specific Tasks\n\n\u003cdetails\u003e\n\u003csummary\u003eAPI (apps/api)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `mise //apps/api:install` | Install dependencies |\n| `mise //apps/api:dev` | Start development server |\n| `mise //apps/api:test` | Run tests |\n| `mise //apps/api:lint` | Run linter |\n| `mise //apps/api:format` | Format code |\n| `mise //apps/api:typecheck` | Type check |\n| `mise //apps/api:migrate` | Run migrations |\n| `mise //apps/api:migrate:create` | Create new migration |\n| `mise //apps/api:gen:openapi` | Generate OpenAPI schema |\n| `mise //apps/api:infra:up` | Start local infrastructure |\n| `mise //apps/api:infra:down` | Stop local infrastructure |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWeb (apps/web)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `mise //apps/web:install` | Install dependencies |\n| `mise //apps/web:dev` | Start development server |\n| `mise //apps/web:build` | Production build |\n| `mise //apps/web:test` | Run tests |\n| `mise //apps/web:lint` | Run linter |\n| `mise //apps/web:format` | Format code |\n| `mise //apps/web:typecheck` | Type check |\n| `mise //apps/web:gen:api` | Generate API client |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMobile (apps/mobile)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `mise //apps/mobile:install` | Install dependencies |\n| `mise //apps/mobile:dev` | Run on device/simulator |\n| `mise //apps/mobile:build` | Build |\n| `mise //apps/mobile:test` | Run tests |\n| `mise //apps/mobile:lint` | Run analyzer |\n| `mise //apps/mobile:format` | Format code |\n| `mise //apps/mobile:gen:l10n` | Generate localizations |\n| `mise //apps/mobile:gen:api` | Generate API client |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWorker (apps/worker)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `mise //apps/worker:install` | Install dependencies |\n| `mise //apps/worker:dev` | Start worker |\n| `mise //apps/worker:test` | Run tests |\n| `mise //apps/worker:lint` | Run linter |\n| `mise //apps/worker:format` | Format code |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInfrastructure (apps/infra)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `mise //apps/infra:init` | Initialize Terraform |\n| `mise //apps/infra:plan` | Preview changes |\n| `mise //apps/infra:apply` | Apply changes |\n| `mise //apps/infra:plan:prod` | Preview production |\n| `mise //apps/infra:apply:prod` | Apply production |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ei18n (packages/i18n)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `mise //packages/i18n:install` | Install dependencies |\n| `mise //packages/i18n:build` | Build i18n files for web and mobile |\n| `mise //packages/i18n:build:web` | Build for web only |\n| `mise //packages/i18n:build:mobile` | Build for mobile only |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDesign Tokens (packages/design-tokens)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `mise //packages/design-tokens:install` | Install dependencies |\n| `mise //packages/design-tokens:build` | Build tokens for web and mobile |\n| `mise //packages/design-tokens:dev` | Watch mode for development |\n| `mise //packages/design-tokens:test` | Run tests |\n\n\u003c/details\u003e\n\n## Internationalization (i18n)\n\n`packages/i18n` is the Single Source of Truth for i18n resources.\n\n```bash\n# Edit i18n files\npackages/i18n/src/en.arb  # English (default)\npackages/i18n/src/ko.arb  # Korean\npackages/i18n/src/ja.arb  # Japanese\n\n# Build and deploy to each app\nmise i18n:build\n# Generated files:\n# - apps/web/src/config/messages/*.json (Nested JSON)\n# - apps/mobile/lib/i18n/messages/app_*.arb (Flutter ARB)\n```\n\n## Design Tokens\n\n`packages/design-tokens` is the Single Source of Truth for design tokens (colors, spacing, etc.).\n\n```bash\n# Edit tokens\npackages/design-tokens/src/tokens.ts\n\n# Build and distribute\nmise tokens:build\n# Generated files:\n# - apps/web/src/app/[locale]/tokens.css (CSS variables)\n# - apps/mobile/lib/core/theme/generated_theme.dart (Flutter Theme)\n```\n\n## Configuration\n\n### Environment Variables\n\nCopy example files and configure:\n\n```bash\n# API\ncp apps/api/.env.example apps/api/.env\n\n# Web\ncp apps/web/.env.example apps/web/.env\n\n# Infra\ncp apps/infra/terraform.tfvars.example apps/infra/terraform.tfvars\n```\n\n### GitHub Actions Secrets\n\nSet these secrets in your repository:\n\n| Secret | Description |\n|--------|-------------|\n| `GCP_PROJECT_ID` | GCP project ID |\n| `GCP_REGION` | GCP region (e.g., `asia-northeast3`) |\n| `WORKLOAD_IDENTITY_PROVIDER` | From Terraform output |\n| `GCP_SERVICE_ACCOUNT` | From Terraform output |\n| `FIREBASE_SERVICE_ACCOUNT_JSON` | Firebase service account JSON (for mobile deployment) |\n| `FIREBASE_ANDROID_APP_ID` | Firebase Android app ID |\n\n### Firebase (Mobile)\n\n1. Install FlutterFire CLI:\n\n```bash\ndart pub global activate flutterfire_cli\n```\n\n2. Configure Firebase for your project:\n\n```bash\ncd apps/mobile\nflutterfire configure\n```\n\nThis generates `lib/firebase_options.dart` with your Firebase configuration.\n\n## Deployment\n\n### GitHub Actions (Recommended)\n\nPush to `main` branch triggers automatic deployment:\n- `apps/api/` changes → Deploy API\n- `apps/web/` changes → Deploy Web\n- `apps/worker/` changes → Deploy Worker\n- `apps/mobile/` changes → Build \u0026 Deploy to Firebase App Distribution\n\n### Manual Deployment\n\n```bash\n# Build and push Docker images\ncd apps/api\ndocker build -t gcr.io/PROJECT_ID/api .\ndocker push gcr.io/PROJECT_ID/api\n\n# Deploy to Cloud Run\ngcloud run deploy api --image gcr.io/PROJECT_ID/api --region REGION\n```\n\n### Mobile (Fastlane)\n\nThe mobile app uses Fastlane for build automation and deployment.\n\n```bash\ncd apps/mobile\n\n# Install Ruby dependencies\nbundle install\n\n# Available lanes\nbundle exec fastlane android build       # Build APK\nbundle exec fastlane android firebase    # Deploy to Firebase App Distribution\nbundle exec fastlane android internal    # Deploy to Play Store (internal)\nbundle exec fastlane ios build           # Build iOS (no codesign)\nbundle exec fastlane ios testflight_deploy  # Deploy to TestFlight\n```\n\n## AI Agent Support\n\nThis template is designed to work with AI coding agents (Gemini, Claude, etc.).\n\n- `.agents/rules/` - Guidelines for AI agents\n- `.serena/` - Serena MCP configuration\n\n\u003e Try [oh-my-agent](https://github.com/first-fluke/oh-my-agent) to maximize productivity with AI coding agents.\n\n## Documentation\n\n- [Build Guide](.agents/rules/build-guide.md)\n- [Lint \u0026 Format Guide](.agents/rules/lint-format-guide.md)\n- [Test Guide](.agents/rules/test-guide.md)\n\n## License\n\nMIT\n\n## Sponsors\n\nIf this project helped you, please consider buying me a coffee!\n\n\u003ca href=\"https://www.buymeacoffee.com/firstfluke\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n\nOr leave a star:\n\n```bash\ngh api --method PUT /user/starred/first-fluke/fullstack-starter\n```\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=first-fluke/fullstack-starter\u0026type=date\u0026legend=bottom-right)](https://www.star-history.com/#first-fluke/fullstack-starter\u0026type=date\u0026legend=bottom-right)\n","funding_links":["https://github.com/sponsors/first-fluke","https://buymeacoffee.com/firstfluke","https://www.buymeacoffee.com/firstfluke"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirst-fluke%2Ffullstack-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirst-fluke%2Ffullstack-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirst-fluke%2Ffullstack-starter/lists"}