feat: initial fullstack starter template

- Next.js 16 + React 19 + TailwindCSS v4 web app
- FastAPI + SQLAlchemy async backend
- Flutter 3.32 + Riverpod 3 mobile app
- Background worker with CloudTasks/PubSub
- Terraform GCP infrastructure (Cloud Run, Cloud SQL, etc.)
- GitHub Actions CI/CD with Workload Identity Federation
- AI agent guidelines for Gemini/Claude
- Multi-language support (ko, en, ja)

Author: gracefullight

.agent/rules/GEMINI.md

@@ -0,0 +1,101 @@
+# Fullstack Starter - Project Overview
+
+## Description
+Modern fullstack monorepo template with Next.js 16, FastAPI, Flutter, and GCP infrastructure.
+
+## Tech Stack
+
+### Frontend (apps/web)
+- **Framework**: Next.js 16 with React 19
+- **Styling**: TailwindCSS v4 + shadcn/ui
+- **State**: Jotai (global), TanStack Query (server)
+- **Auth**: better-auth
+- **i18n**: next-intl
+- **API Client**: Orval (OpenAPI codegen)
+- **Testing**: Vitest + Playwright
+
+### Backend (apps/api)
+- **Framework**: FastAPI with Python 3.13
+- **Database**: PostgreSQL 16 with SQLAlchemy async
+- **Cache**: Redis 7.2
+- **Migrations**: Alembic
+- **Storage**: GCS / MinIO
+- **Package Manager**: uv + poe tasks
+
+### Worker (apps/worker)
+- **Framework**: FastAPI (HTTP-based worker)
+- **Queue**: Cloud Tasks / Pub/Sub
+- **Retry**: tenacity
+
+### Mobile (apps/mobile)
+- **Framework**: Flutter 3
+- **State**: Riverpod
+- **Routing**: go_router
+- **API Client**: swagger_parser (OpenAPI codegen)
+- **l10n**: Flutter intl
+
+### Infrastructure (apps/infra)
+- **IaC**: Terraform
+- **Cloud**: GCP (Cloud Run, Cloud SQL, Memorystore, GCS, Cloud Tasks, Pub/Sub)
+- **CI/CD**: GitHub Actions with Workload Identity Federation
+
+## Project Structure
+```
+fullstack-starter/
+├── apps/
+│   ├── api/          # FastAPI backend
+│   ├── web/          # Next.js frontend
+│   ├── worker/       # Background worker
+│   ├── mobile/       # Flutter mobile app
+│   └── infra/        # Terraform infrastructure
+├── packages/         # Shared packages (if needed)
+├── docs/             # Documentation
+└── [config files]    # Root configuration
+```
+
+## Key Patterns
+
+### API Layer
+- Feature-based module structure
+- Repository pattern for data access
+- Dependency injection via FastAPI Depends
+- Abstract base classes for AI and Storage providers
+
+### Web Layer
+- App Router with Route Groups
+- Server Components by default
+- Client Components only when needed (interactivity, hooks)
+- Colocation of components with routes
+
+### Mobile Layer
+- Feature-first architecture
+- Riverpod for DI and state
+- Freezed for immutable models
+
+## Code Conventions
+
+### Naming
+- Files: kebab-case (e.g., `user-profile.tsx`)
+- Components: PascalCase (e.g., `UserProfile`)
+- Functions/Variables: camelCase (e.g., `getUserProfile`)
+- Python: snake_case (e.g., `get_user_profile`)
+- Constants: SCREAMING_SNAKE_CASE (e.g., `MAX_RETRY_COUNT`)
+
+### TypeScript
+- Prefer `interface` over `type` for object shapes
+- Use `type` for unions, intersections, and utility types
+- No `any` - use `unknown` and narrow types
+- Prefer named exports over default exports
+
+### Python
+- Type hints required for all function signatures
+- Async/await for all I/O operations
+- Pydantic models for request/response schemas
+- ABC for extensible components (AI providers, Storage, etc.)
+
+## Important Files
+- `mise.toml` - Runtime versions and task runner
+- `biome.json` - JS/TS linting and formatting
+- `apps/api/pyproject.toml` - Python dependencies and tasks
+- `apps/web/package.json` - Web dependencies and scripts
+- `apps/infra/variables.tf` - Infrastructure configuration

.agent/rules/build-guide.md

@@ -0,0 +1,202 @@
+# Build Guide
+
+## Quick Start
+
+### Prerequisites
+Ensure you have `mise` installed for runtime management.
+
+```bash
+# Install all runtimes
+mise install
+
+# Verify versions
+mise current
+```
+
+## Build Commands
+
+### Root (All Apps)
+```bash
+# Install all dependencies
+pnpm install        # JS/TS packages
+uv sync --frozen    # Python packages (in apps/api and apps/worker)
+flutter pub get     # Flutter packages (in apps/mobile)
+
+# Build all
+pnpm build
+```
+
+### API (apps/api)
+```bash
+cd apps/api
+
+# Install dependencies
+uv sync --frozen
+
+# Run development server
+poe dev
+
+# Run with auto-reload
+poe dev:reload
+
+# Build Docker image
+docker build -t api .
+```
+
+### Web (apps/web)
+```bash
+cd apps/web
+
+# Install dependencies
+pnpm install
+
+# Development server
+pnpm dev
+
+# Production build
+pnpm build
+
+# Start production server
+pnpm start
+
+# Generate API client from OpenAPI
+pnpm generate:api
+
+# Build Docker image
+docker build -t web .
+```
+
+### Worker (apps/worker)
+```bash
+cd apps/worker
+
+# Install dependencies
+uv sync --frozen
+
+# Run development server
+poe dev
+
+# Build Docker image
+docker build -t worker .
+```
+
+### Mobile (apps/mobile)
+```bash
+cd apps/mobile
+
+# Install dependencies
+flutter pub get
+
+# Generate code (Freezed, Riverpod, etc.)
+flutter pub run build_runner build --delete-conflicting-outputs
+
+# Generate l10n
+flutter gen-l10n
+
+# Generate API client
+dart run swagger_parser:generate
+
+# Run app
+flutter run
+
+# Build APK
+flutter build apk --release
+
+# Build iOS
+flutter build ios --release
+```
+
+### Infrastructure (apps/infra)
+```bash
+cd apps/infra
+
+# Initialize Terraform
+terraform init -backend-config="bucket=your-tfstate-bucket"
+
+# Plan changes
+terraform plan -var-file="terraform.tfvars"
+
+# Apply changes
+terraform apply -var-file="terraform.tfvars"
+
+# Destroy (careful!)
+terraform destroy -var-file="terraform.tfvars"
+```
+
+## Docker Compose (Local Development)
+
+### Start Infrastructure
+```bash
+cd apps/api
+docker compose -f docker-compose.infra.yml up -d
+```
+
+This starts:
+- PostgreSQL (port 5432)
+- Redis (port 6379)
+- MinIO (ports 9000, 9001)
+
+### Stop Infrastructure
+```bash
+docker compose -f docker-compose.infra.yml down
+```
+
+### Reset Infrastructure (with data)
+```bash
+docker compose -f docker-compose.infra.yml down -v
+```
+
+## Database Migrations
+
+### Create Migration
+```bash
+cd apps/api
+poe migration "description of changes"
+```
+
+### Apply Migrations
+```bash
+cd apps/api
+poe migrate
+```
+
+### Rollback Migration
+```bash
+cd apps/api
+alembic downgrade -1
+```
+
+## Common Build Issues
+
+### Python Import Errors
+```bash
+# Ensure virtual environment is activated
+source .venv/bin/activate  # or let mise handle it
+
+# Reinstall dependencies
+uv sync --frozen
+```
+
+### Node Module Issues
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules pnpm-lock.yaml
+pnpm install
+```
+
+### Flutter Build Issues
+```bash
+# Clean and rebuild
+flutter clean
+flutter pub get
+flutter pub run build_runner build --delete-conflicting-outputs
+```
+
+### Terraform State Issues
+```bash
+# Refresh state from cloud
+terraform refresh -var-file="terraform.tfvars"
+
+# Import existing resource
+terraform import -var-file="terraform.tfvars" google_storage_bucket.uploads your-bucket-name
+```