Skip to content

Quick Start Guide

Prerequisites

  • Node.js 18+ (check: node --version)
  • npm 8+ (check: npm --version)
  • Firebase CLI (npm install -g firebase-tools)
  • Google Cloud Project with Firestore enabled
  • Firebase Authentication enabled

Local Development Setup

1. Clone Repository

git clone https://github.com/Golfklubb-IT/Gavekort-multitennenant.git
cd Gavekort-multitennenant

2. Install Dependencies

cd functions
npm install
cd ..

3. Configure Firebase Project

Create a .firebaserc file in the repository root:

{
  "projects": {
    "default": "your-project-id"
  }
}

# Install emulator
firebase emulators:start

# In another terminal, run functions locally:
cd functions
npm run serve

5. Deploy to Firebase

# Deploy functions
firebase deploy --only functions

# Deploy firestore rules and indexes
firebase deploy --only firestore

Development Workflow

Building TypeScript

cd functions
npm run build

Running Tests

cd functions
npm run test  # (when tests are added)

Testing Endpoints Locally

With Firebase Emulator running:

# Get an auth token (for testing)
firebase auth:sign-in-as admin@example.com

# Issue giftcard
curl -X POST http://localhost:5001/your-project/us-central1/giftcards_issue \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "productId": "giftcard-100nok"
  }'

Project Structure

Gavekort-multitennenant/
├── functions/                      # Cloud Functions backend
│   ├── src/
│   │   ├── index.ts               # Main entry point (all function exports)
│   │   ├── api.ts                 # REST API HTTP wrappers
│   │   ├── types.ts               # TypeScript domain models
│   │   ├── operations/            # Core business logic
│   │   │   ├── issueGiftCard.ts
│   │   │   ├── redeemValue.ts
│   │   │   └── claimCode.ts
│   │   └── utils/                 # Shared utilities
│   │       ├── idempotency.ts
│   │       ├── codeHashing.ts
│   │       └── projections.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── lib/                       # Compiled JavaScript (generated)
├── docs/                          # MkDocs documentation
│   ├── index.md
│   ├── architecture.md
│   ├── api.md
│   ├── rest-api.md
│   └── ...
├── firestore.rules                # Firestore security rules
├── FIRESTORE_INDEXES.md          # Index definitions
├── openapi.yaml                   # OpenAPI 3.0 specification
├── mkdocs.yml                     # MkDocs configuration
└── README.md

Key Technologies

  • Backend Runtime: Node.js 18 + TypeScript
  • Database: Google Cloud Firestore
  • Authentication: Firebase Authentication
  • Functions: Google Cloud Functions (HTTP + Callable)
  • Documentation: MkDocs with Material theme
  • Version Control: Git + GitHub
  • API Specification: OpenAPI 3.0

Environment Variables

Create a .env file in the functions/ directory:

# Firebase project settings
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_API_KEY=your-api-key

# Security (optional - for code hashing pepper)
CODE_PEPPER=your-secret-pepper-string

# App configuration
NODE_ENV=development
LOG_LEVEL=info

Firestore Indexes

Required indexes are defined in FIRESTORE_INDEXES.md. Deploy via:

firebase firestore:indexes:deploy

Or create manually via Firebase Console.

API Documentation

See REST API for endpoint documentation.

Full OpenAPI specification in openapi.yaml can be used to: - Generate client SDKs - Validate requests/responses - Generate API documentation websites - Mock servers

Troubleshooting

"firebase: command not found"

npm install -g firebase-tools

TypeScript compilation errors

cd functions
npm run build
# Check error messages, fix, and rebuild

Firestore connection issues

  • Ensure Google Cloud project has Firestore enabled
  • Check Firebase configuration in firebase.json
  • Verify .firebaserc has correct project ID

Port already in use (emulator)

# Kill process on port 8080
lsof -ti:8080 | xargs kill -9

# Or use different port
firebase emulators:start --project=emulator --port=9000

Next Steps

  1. Frontend: Build User Wallet app (React/Vue)
  2. Admin Interface: Build Backoffice/Admin panel
  3. Testing: Add integration and load tests
  4. Deployment: Set up CI/CD pipeline (GitHub Actions)
  5. Monitoring: Configure Cloud Logging and Monitoring