# GoodGo Platform — Infrastructure Quick Reference

## 🚀 Quick Start

```bash
# Development
docker compose up -d --wait

# Production
docker compose -f docker-compose.prod.yml up -d --wait

# CI/E2E
docker compose -f docker-compose.ci.yml up -d --wait
```

## 📊 Service Map (Dev)

| Service | Port | Health | Status |
|---------|------|--------|--------|
| **API (NestJS)** | 3001 | GET /health | 🟢 |
| **Web (Next.js)** | 3000 | GET / | 🟢 |
| **AI Services (Python)** | 8000 | GET /health | 🟢 |
| **PostgreSQL + PostGIS** | 5432 | pg_isready | 🟢 |
| **Redis** | 6379 | PING | 🟢 |
| **Typesense** | 8108 | GET /health | 🟢 |
| **MinIO** | 9000 | mc ready local | 🟢 |
| **Prometheus** | 9090 | GET /-/healthy | 🟢 |
| **Grafana** | 3002 | GET /api/health | 🟢 |
| **Loki** | 3100 | GET /ready | 🟢 |
| **Promtail** | 9080 | (passive) | 🟢 |

## 📊 Service Map (Prod)

Same as dev, plus **PgBouncer** (6432) for connection pooling.

## 🗄️ Database

- **Type:** PostgreSQL 16 + PostGIS
- **Schema:** 22 Prisma models
- **Backup:** Daily 02:00 UTC, 7-day retention
- **Connection Pooling (Prod):** PgBouncer (transaction mode, 20 connections)
- **Verification:** Weekly automated restore test

**Key Tables:**
- User, RefreshToken, OAuthAccount, Agent
- Property, PropertyMedia, Listing
- SavedSearch, Transaction, Inquiry, Lead
- Payment (VNPAY/MOMO/ZALOPAY/BANK_TRANSFER)
- Plan, Subscription, UsageRecord
- Valuation, MarketIndex, NotificationLog, AdminAuditLog, Review

## 💾 Cache & Search

- **Redis:** 512MB (prod), 256MB (dev), AOF persistence, LRU eviction
- **Typesense:** Full-text search on listings, geo-indexing support

## 📈 Monitoring

- **Prometheus:** 30-day retention (prod), 15-day (dev)
- **Grafana:** Pre-provisioned dashboards (7 total)
- **Loki:** 15-day log retention, Pino JSON parsing
- **Alerts:** p99 latency > 1s (warn), > 3s (critical), 5xx > 1%

## 💳 Payment Integration

| Gateway | Provider | Status Tracking | Callback Verification |
|---------|----------|-----------------|----------------------|
| VNPay | VNPAY | ✅ | HMAC SHA-256 |
| MoMo | MOMO | ✅ | HMAC |
| ZaloPay | ZALOPAY | ✅ | Key 1/2 |
| Bank Transfer | BANK_TRANSFER | Manual | N/A |

**Callback Handler:**
- Idempotent (updateIfStatus pattern)
- Atomic state transitions (PENDING → COMPLETED/FAILED)
- Domain event publishing (triggers downstream actions)

## 🏥 Health Checks

```bash
GET /health          # Liveness (always 200)
GET /health/ready    # Readiness (checks DB + Redis)
GET /health/db       # Database only
GET /health/redis    # Redis only
```

## 🔐 Environment Variables (Critical)

```env
# Database
DB_USER=goodgo
DB_PASSWORD=<required>
DATABASE_URL_DIRECT=postgresql://...  # For migrations

# Redis (Prod requires password)
REDIS_PASSWORD=<required-in-prod>

# Typesense API Key
TYPESENSE_API_KEY=<required>

# JWT Secrets (REQUIRED, min 32 chars)
JWT_SECRET=<openssl rand -base64 48>
JWT_REFRESH_SECRET=<openssl rand -base64 48>

# KYC Encryption (Prod only)
KYC_ENCRYPTION_KEY=<openssl rand -hex 32>  # 64 hex chars

# Payment Gateways (optional if disabled)
VNPAY_TMN_CODE=
MOMO_PARTNER_CODE=
ZALOPAY_APP_ID=
```

## 📦 Deployment

**Containers:**
- `goodgo-api:${IMAGE_TAG}` — NestJS API
- `goodgo-web:${IMAGE_TAG}` — Next.js Frontend
- `goodgo-ai-services:${IMAGE_TAG}` — Python FastAPI

**Registry:** `ghcr.io/goodgo/`

**CI/CD:** GitHub Actions
- **ci.yml** — Test, build, lint on push
- **deploy.yml** — Build images, deploy to staging (auto) or prod (manual)
- **backup-verify.yml** — Weekly restore verification
- **e2e.yml** — End-to-end test suite

## 🆘 Troubleshooting

**API not healthy?**
```bash
docker compose exec api curl http://localhost:3001/health/ready
docker compose logs api --tail=50
```

**Database connection pooling full?**
```bash
docker compose exec pgbouncer psql -h 127.0.0.1 -p 6432 -U pgbouncer_stats -c "SHOW stats"
```

**Redis down?**
```bash
docker compose exec redis redis-cli ping
# App continues working (DB fallback), but slower
```

**Typesense not indexing?**
```bash
curl http://localhost:8108/collections/listings -H "X-TYPESENSE-API-KEY: ${KEY}"
# Reindex: docker compose exec api npx ts-node scripts/reindex-listings.ts
```

**Payment callback failing?**
```bash
docker compose logs api | grep -i callback
# Check VNPAY_HASH_SECRET / MOMO_SECRET_KEY / ZALOPAY_KEY1
```

**Backup stuck?**
```bash
docker compose exec pg-backup bash -c "tail -f /var/log/pg-backup.log"
docker compose exec postgres psql -U goodgo -d goodgo -c "SELECT * FROM pg_stat_activity WHERE wait_event_type IS NOT NULL;"
```

## 📝 Key Files

| Path | Purpose |
|------|---------|
| `docker-compose.yml` | Dev (no resource limits, all services) |
| `docker-compose.prod.yml` | Prod (PgBouncer, limits, secrets) |
| `docker-compose.ci.yml` | Test (tmpfs, minimal services) |
| `INFRASTRUCTURE_RUNBOOK.md` | Full documentation (this file's companion) |
| `prisma/schema.prisma` | Complete data model |
| `infra/pgbouncer/pgbouncer.ini` | Connection pooling config |
| `monitoring/prometheus/alert-rules.yml` | Alert definitions |
| `scripts/backup/pg-backup.sh` | Daily backup automation |
| `scripts/backup/pg-verify-backup.sh` | Restore verification |
| `.github/workflows/*.yml` | CI/CD pipelines |

## 🔗 Links

- **Grafana:** http://localhost:3002 (admin/admin)
- **Prometheus:** http://localhost:9090
- **MinIO Console:** http://localhost:9001
- **API Docs:** http://localhost:3001/api (if Swagger enabled)
- **Frontend:** http://localhost:3000

## 📞 Common Commands

```bash
# View all services
docker compose ps

# Tail logs
docker compose logs -f api web postgres redis

# Execute command in container
docker compose exec api npx prisma db push
docker compose exec postgres psql -U goodgo -d goodgo

# Restart single service
docker compose restart api

# Full cleanup (dev only!)
docker compose down -v && docker compose up -d --wait

# Database backup & restore
docker compose exec postgres pg_dump -U goodgo -d goodgo | gzip > backup.sql.gz
docker compose exec postgres pg_restore -U goodgo -d goodgo backup.sql.gz

# Check health endpoints
curl http://localhost:3001/health/ready | jq
curl http://localhost:3001/health/db | jq
curl http://localhost:3001/health/redis | jq
```

---

**For detailed information, see `INFRASTRUCTURE_RUNBOOK.md`**

Last updated: April 11, 2026