Developer Onboarding

Welcome to the Gatelithix Gateway development team. This guide covers everything you need to get a local development environment running and understand the system architecture.

Prerequisites

Optional but recommended:

• direnv  for automatic environment setup per directory
• goose  for running database migrations locally
• ko  for building Go container images
• jq  for JSON output formatting

Local Setup

1. Clone the Repository

git clone git@github.com:gatelithix/gatelithix-gateway.git
cd gatelithix-gateway

2. Configure Environment

The repo includes a .envrc file for direnv . It sets:

• GCP account (thibault@paylithix.com) and project (gatelithix-core)
• Node.js 22 via nvm
• Local database/Redis connection defaults (matching docker-compose)
• Auth0 domain and audience

# If you have direnv installed (recommended):
direnv allow
 
# Otherwise, manually:
cp .env.example .env.local

Edit .env.local with your local development settings. The defaults are configured for the docker-compose services.

3. Start Local Services

docker-compose up -d

This starts:

• PostgreSQL (core) on port 5432 (user: gateway, db: gateway)
• PostgreSQL (PCI/vault) on port 5433 (user: vault, db: vault)
• Redis on port 6379

Verify all containers are healthy:

docker-compose ps

4. Run Database Migrations

# Core database
goose -dir db/migrations/core postgres \
  "host=localhost port=5432 user=gateway password=gateway dbname=gateway sslmode=disable" up
 
# PCI database
goose -dir db/migrations/pci postgres \
  "host=localhost port=5433 user=vault password=vault dbname=vault sslmode=disable" up

5. Build and Test

# Verify Go compilation
make build
 
# Run unit tests
make test
 
# Run the local smoke test
scripts/smoke-test.sh

6. Run Services Locally

# Start the gateway (reads from .env.local)
go run ./apps/gateway/
 
# In another terminal, start the vault
go run ./apps/vault/

Architecture Overview

Service Map

The system consists of 7 deployable services:

PCI Zones

The infrastructure is split into two GCP projects for PCI DSS compliance:

• Core project (gatelithix-core): Gateway, connectors, admin portal, docs, core database, Redis, Pub/Sub
• PCI project (gatelithix-pci): Token Vault, PCI database, Cloud KMS HSM

The vault runs with INTERNAL_ONLY ingress — it can only be reached by the gateway via VPC peering. This ensures cardholder data (PANs) never leaves the PCI CDE boundary.

Key Abstractions

PaymentIntent: The core payment lifecycle object. Created with an amount and currency, then transitions through states: requires_payment_method -> requires_confirmation -> processing -> succeeded/failed.

Token Lifecycle: Raw PANs are encrypted at the vault ingress. The vault returns a gateway token (opaque reference). Connectors use either gateway tokens or PSP-specific processor tokens for transactions.

Connector Interface: Each connector implements a standard interface (Authorize, Capture, Sale, Refund, Void) and declares its capabilities, retry rules, and webhook verification approach. Connectors run as separate Cloud Run services with circuit breakers.

Routing Engine: Determines which connector to use for a payment based on the merchant’s routing configuration (default connector + failover connector).

Data Flow

Client Request
  -> Cloud Load Balancer + Cloud Armor WAF
    -> API Gateway (auth, rate limit, idempotency)
      -> Routing Engine (select connector)
      -> Token Vault (if raw card data, via VPC peering)
      -> Connector Service (internal call)
        -> PSP API (external HTTPS)
      <- Normalized response
    <- PaymentIntent updated in Core DB
    <- Event published to Pub/Sub
      -> Merchant webhook delivery

Development Workflow

1. Branch: Create a feature branch from main
2. Develop: Write code, add tests, run make test locally
3. PR: Open a pull request — CI runs linting, tests, and security scans
4. Review: At least 1 reviewer for core, 2 reviewers for PCI changes
5. Merge: Merge to main triggers build-push and deploy workflows
6. Verify: Post-deploy smoke tests run automatically

Key Directories

gatelithix-gateway/
  apps/
    gateway/          # API Gateway service (Go)
    vault/            # Token Vault service (Go, PCI CDE)
    connectors/
      stripe/         # Stripe connector (Go)
      nmi/            # NMI connector (Go)
      fluidpay/       # FluidPay connector (Go)
    admin/            # Admin Portal (Next.js)
    docs/             # Docs Site (Nextra)
  pkg/                # Shared Go packages
    config/           # Configuration loading
    database/         # Database connection helpers
    middleware/       # HTTP middleware (auth, rate limit, etc.)
    models/           # Domain models
    store/            # Data access interfaces
  infra/
    terraform/
      core/           # Core project infrastructure
      pci/            # PCI project infrastructure
      modules/        # Reusable Terraform modules
  db/
    migrations/
      core/           # Core database migrations (goose)
      pci/            # PCI database migrations (goose)
  cmd/
    gatelithix/       # Debugging CLI tool
  scripts/            # Operational scripts (rotation, smoke test, etc.)
  .github/
    workflows/        # CI/CD pipeline definitions

Getting Help

• Architecture questions: See the Infrastructure Overview and Database Schema pages
• Deployment: See the Deployment Runbook
• Incidents: See the Incident Response Playbook
• PCI compliance: See the PCI Self-Assessment and Verification Evidence
• API spec: See PAYLITHIX_GATEWAY_SPEC_EXPORT_v0.2.md in the repo root