Skip to content

Latest commit

 

History

History
236 lines (177 loc) · 5.19 KB

GETTING_STARTED.md

File metadata and controls

236 lines (177 loc) · 5.19 KB

Getting Started

For Human Developers - If you're an AI assistant, read AI_BOOTSTRAP.md instead.

Get your app running in production in under 30 minutes.

Quick Start

1. Run Setup Script

./scripts/setup.sh

This interactive script will:

  • Check prerequisites (gcloud, pulumi, go)
  • Configure git hooks (pre-commit, commit-msg, pre-push)
  • Configure your Google Cloud project
  • Enable required APIs
  • Set up Pulumi infrastructure stacks

Quick setup without GCP (just git hooks and dependencies):

make setup-hooks     # Configure git hooks
cd backend && make deps  # Install Go dependencies

2. Deploy Infrastructure

cd infrastructure/pulumi
make deploy-dev

This creates:

  • Artifact Registry (for Docker images)
  • Cloud Run service
  • Firestore database
  • Service account with proper permissions

3. Run Backend Locally

cd backend
make run

Visit http://localhost:8080/health

4. Open Mobile Apps

iOS:

cd mobile/ios
xcodegen generate
open App.xcodeproj

Android:

  • Open mobile/android in Android Studio
  • Sync Gradle and run

Prerequisites

Tool Install Verify
gcloud Install Guide gcloud version
Pulumi brew install pulumi pulumi version
Go 1.24+ brew install go go version
Node.js brew install node node --version
Firebase CLI npm install -g firebase-tools firebase --version

Project Structure

.
├── backend/                 # Go API server
│   ├── cmd/api/main.go     # Entry point
│   └── Makefile            # Build commands
├── mobile/
│   ├── ios/                # SwiftUI app
│   │   ├── project.yml     # XcodeGen config
│   │   └── App/           # Source files
│   └── android/            # Kotlin/Compose app
│       └── app/           # Source files
├── infrastructure/
│   └── pulumi/             # Infrastructure as Code
│       ├── main.go        # Pulumi program
│       └── Makefile       # Deploy commands
├── scripts/
│   ├── setup.sh           # Initial setup
│   └── openapi_workflow.py # API code generation
└── docs/
    ├── ARCHITECTURE.md    # Technology decisions
    └── GETTING_STARTED.md # This file

Development Workflow

API-First Development

  1. Edit API spec: backend/api/openapi.yaml
  2. Regenerate code: python scripts/openapi_workflow.py --full
  3. Implement handlers: Backend handlers are regenerated
  4. Build clients: iOS and Android clients are regenerated

Making Changes

# Backend changes
cd backend && make test && make run

# iOS changes
cd mobile/ios && xcodegen generate
# Open Xcode, build and run

# Android changes
cd mobile/android && ./gradlew build
# Run in Android Studio

Deploying

# Deploy to development
cd infrastructure/pulumi
make deploy-dev

# Deploy to production (requires confirmation)
make deploy-prod

Environment Configuration

Development Stack (Pulumi.dev.yaml)

config:
  gcp:region: us-central1
  gcp:project: YOUR_DEV_PROJECT
  app-infrastructure:environment: dev

Production Stack (Pulumi.prod.yaml)

config:
  gcp:region: us-central1
  gcp:project: YOUR_PROD_PROJECT
  app-infrastructure:environment: prod

Firebase Setup

  1. Go to Firebase Console

  2. Add Firebase to your GCP project

  3. Enable services:

    • Firestore (Native mode, us-central1)
    • Authentication (Email, Google, Apple Sign-In)
    • Storage (for file uploads)

  4. Download config files:

    • iOS: GoogleService-Info.plist
    • Android: google-services.json

Troubleshooting

"Permission denied" on setup.sh

chmod +x scripts/setup.sh

Pulumi state issues

cd infrastructure/pulumi
pulumi cancel --yes
pulumi refresh --stack dev --yes

Backend won't start

cd backend
go mod tidy
make run

iOS build fails

cd mobile/ios
rm -rf App.xcodeproj
xcodegen generate

Secrets Management

Never commit secrets to git!

Environment Where to Store How to Access
Local Dev .env.local (gitignored) os.Getenv()
CI/CD GitHub Actions Secrets ${{ secrets.X }}
Production Google Secret Manager SDK or mount as env var

For API keys, database URLs, and other sensitive config:

  • Create secrets in GCP: gcloud secrets create my-secret --data-file=-
  • Mount in Cloud Run or use the Secret Manager SDK

See SECRETS.md for complete setup instructions.

Next Steps

  1. Customize the API: Edit backend/api/openapi.yaml
  2. Add authentication: See Firebase Auth docs
  3. Configure secrets: See SECRETS.md for production secrets
  4. Set up CI/CD: .github/workflows/ is pre-configured
  5. Read architecture: ARCHITECTURE.md

Need help? Check the Troubleshooting section or open an issue.