Skip to main content

Local Development Setup

Prerequisites​

  • Node.js 18+
  • pnpm 8+
  • Docker & Docker Compose
  • PostgreSQL client (psql)

Quick Start​

1. Clone and Install​

git clone <repository-url>
cd hub
pnpm install

2. Start Dependencies​

# Start PostgreSQL, Redis, and other services
docker-compose up -d

3. Database Setup​

# Run wallet database migrations
pnpm nx run wallet-prisma:migrate:dev

# Seed test data (optional)
pnpm nx run wallet-prisma:seed

4. Environment Variables​

Create .env.local in the wallet API project:

# Database
DATABASE_URL="postgresql://user:pass@localhost:5432/wallet_dev"

# Redis
REDIS_URL="redis://localhost:6379"

# Payment Provider (test mode)
PEACH_API_URL="https://test.ppay.io"
PEACH_API_KEY="your-test-key"

# Pass Provider
APPLE_PASS_TYPE_ID="pass.com.yourclub.member"
APPLE_TEAM_ID="YOUR_TEAM_ID"
GOOGLE_PAY_ISSUER_ID="your-issuer-id"

5. Run the API​

# Development mode with hot reload
pnpm nx serve wallet-api

# Or run with watch
pnpm nx run wallet-api:serve:development

API available at http://localhost:3000/api/wallet

Project Structure​

libs/wallet/
├── core/               # Domain models, business logic
│   ├── src/
│   │   ├── models/     # Domain entities
│   │   ├── services/   # Business logic services
│   │   └── types/      # TypeScript types
│   └── README.md
├── prisma/             # Database schema and client
│   ├── schema.prisma
│   ├── migrations/
│   └── seed.ts
├── api/                # REST controllers
│   ├── src/
│   │   ├── portal/     # Member-facing endpoints
│   │   └── admin/      # Staff-facing endpoints
│   └── README.md
├── pass/               # Apple/Google Wallet integration
│   ├── src/
│   │   ├── apple/
│   │   └── google/
│   └── README.md
└── notifications/      # Notification handlers
    ├── src/
    │   └── handlers/
    └── README.md

Running Tests​

# Run all wallet tests
pnpm nx run-many --target=test --projects=wallet-*

# Run specific library tests
pnpm nx test wallet-core
pnpm nx test wallet-api

# Run with coverage
pnpm nx test wallet-core --coverage

# Run e2e tests
pnpm nx e2e wallet-api-e2e

Database Operations​

Migrations​

# Create a new migration
pnpm nx run wallet-prisma:migrate:dev --name add_feature

# Apply migrations (production)
pnpm nx run wallet-prisma:migrate:deploy

# Reset database (development only)
pnpm nx run wallet-prisma:migrate:reset

Prisma Studio​

# Open database GUI
pnpm nx run wallet-prisma:studio

Common Tasks​

Add a New Endpoint​

  1. Define types in wallet-core/src/types/
  2. Add service method in wallet-core/src/services/
  3. Create controller method in wallet-api/src/
  4. Add route and validation
  5. Write tests

Add a New Notification​

  1. Create handler in wallet-notifications/src/handlers/
  2. Register handler in notification service
  3. Add event key to types
  4. Update preference model if needed
  5. Write tests

Update Pass Template​

  1. Modify template in wallet-pass/src/templates/
  2. Update pass generation logic
  3. Test with Apple/Google sandbox
  4. Push update to existing passes

Debugging​

API Logs​

# View logs in development
pnpm nx serve wallet-api 2>&1 | bunyan

# Filter by level
LOG_LEVEL=debug pnpm nx serve wallet-api

Database Queries​

# Enable query logging
DEBUG=prisma:query pnpm nx serve wallet-api

Redis Queues​

# View BullMQ dashboard (if configured)
open http://localhost:3000/admin/queues

Troubleshooting​

"Cannot connect to database"​

  • Verify Docker is running: docker ps
  • Check DATABASE_URL in .env
  • Run docker-compose up -d postgres

"Migration failed"​

  • Reset and re-migrate: pnpm nx run wallet-prisma:migrate:reset
  • Check for schema conflicts

"Tests timing out"​

  • Ensure test database is running
  • Check Redis connection
  • Increase timeout in jest config