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

Tool	Version	Purpose
Go	1.26+	Backend services (gateway, vault, connectors)
Node.js	22+	Admin portal and docs site
Docker	Latest	Local PostgreSQL, Redis containers
gcloud CLI	Latest	Google Cloud interactions
git	Latest	Source control

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 the Full Stack

The easiest way to start everything locally:


make dev       # Backend: infra + migrations + vault + connectors + gateway
make dev-all   # Backend + dashboard (:4002) + docs site (:4003)

This single command:

Starts PostgreSQL (core :5432, PCI :5433) and Redis (:6379) via Docker
Runs database migrations with goose
Builds and starts vault (:4001), 3 connectors (:4010-4012), and gateway (:4000)
Enables DEV_MODE (auth bypassed, sandbox connector seeded)

Press Ctrl+C to stop services. Infrastructure containers keep running between sessions.


make dev-stop  # Stop infrastructure containers when done for the day

4. Build and Test


make build     # Verify Go compilation
make test      # Run unit tests
make smoke     # Automated smoke test (builds, starts, tests, stops)

5. Run Services Individually (alternative)

If you prefer separate terminals:


# First: start infrastructure
docker compose up -d
 
# Run migrations
GOOSE_DRIVER=postgres GOOSE_DBSTRING="host=localhost port=5432 user=gateway password=gateway dbname=gateway sslmode=disable" goose -dir db/migrations up
GOOSE_DRIVER=postgres GOOSE_DBSTRING="host=localhost port=5433 user=vault password=vault dbname=vault sslmode=disable" goose -dir db/migrations/vault up
 
# Terminal 1: Vault
make run-vault
 
# Terminal 2: Gateway
make run-gateway
 
# Terminal 3 (optional): Admin portal
make admin-dev
 
# Terminal 4 (optional): Docs site
make docs-dev

Architecture Overview

Service Map

The system consists of 7 deployable services:

Service	Language	Directory	Description
API Gateway	Go	`apps/gateway/`	Public-facing API, auth, routing, orchestration
Token Vault	Go	`apps/vault/`	PCI CDE, PAN encryption/tokenization
Stripe Connector	Go	`apps/connectors/stripe/`	Stripe PSP integration
NMI Connector	Go	`apps/connectors/nmi/`	NMI PSP integration
FluidPay Connector	Go	`apps/connectors/fluidpay/`	FluidPay PSP integration
Dashboard	TypeScript/Next.js	`apps/dashboard/`	Merchant management dashboard
Docs Site	TypeScript/Nextra	`apps/docs/`	Developer documentation (this site)

PCI Zones

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

Core project (gatelithix-core): Gateway, connectors, dashboard, 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

Branch: Create a feature branch from main
Develop: Write code, add tests, run make test locally
PR: Open a pull request — CI runs linting, tests, and security scans
Review: At least 1 reviewer for core, 2 reviewers for PCI changes
Merge: Merge to main triggers build-push and deploy workflows
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)
    dashboard/        # Dashboard (Next.js)
    docs/             # Docs Site (Nextra)
  pkg/                # Shared Go packages
    payment/          # Payment engine, models, store
    database/         # PostgreSQL pool, transactions, scan helpers
    middleware/       # HTTP middleware (auth, rate limit, CORS, PAN filter)
    vault/            # Encryption, token models, KMS client
    webhook/          # Webhook ingestion, normalization, delivery
    commercial/       # Metering, ISO hierarchy, pricing, ledger
    connector/        # Connector interface, circuit breaker, metrics
    auth/             # JWT validation, RBAC
  infra/
    terraform/
      core/           # Core project infrastructure
      pci/            # PCI project infrastructure
      modules/        # Reusable Terraform modules (Cloud Run, VPC)
  db/
    migrations/       # Core database migrations (20 files, goose)
      vault/          # PCI vault database migrations (4 files, goose)
  cmd/
    gatelithix/       # Debugging CLI tool
  scripts/            # Operational scripts (rotation, smoke test, etc.)
  .github/
    workflows/        # CI/CD pipeline definitions

E2E Testing

ISO Hierarchy E2E Test

The ISO hierarchy E2E test creates a realistic multi-level ISO structure with merchants and transactions against the locally running gateway and vault services.

Prerequisites:

Full stack running locally (make dev — starts infra, vault, connectors, and gateway)
jq installed (brew install jq)

Run:


make e2e-iso

What it creates:


Gatelithix USA (Master ISO)
├── Gatelithix Texas (Sub-ISO)
│   ├── Gatelithix Austin (Sub-Sub-ISO)
│   │   ├── Austin Coffee Roasters (Merchant)
│   │   └── Sixth Street Electronics (Merchant)
│   └── Gatelithix Dallas (Sub-Sub-ISO)
│       ├── Deep Ellum Vinyl Shop (Merchant)
│       └── Dallas BBQ Supply Co (Merchant)
├── Gatelithix California (Sub-ISO)
│   ├── Gatelithix San Francisco (Sub-Sub-ISO)
│   │   ├── Bay Area Bike Works (Merchant)
│   │   └── Mission Street Tacos (Merchant)
│   └── Gatelithix Los Angeles (Sub-Sub-ISO)
│       ├── Sunset Boulevard Books (Merchant)
│       └── Venice Beach Surf Co (Merchant)
└── Gatelithix New York (Sub-ISO)
    ├── Gatelithix Manhattan (Sub-Sub-ISO)
    │   ├── Chelsea Market Flowers (Merchant)
    │   └── SoHo Design Studio (Merchant)
    └── Gatelithix Brooklyn (Sub-Sub-ISO)
        ├── Williamsburg Craft Brewery (Merchant)
        └── DUMBO Tech Repair (Merchant)

Totals: 1 master ISO, 3 sub-ISOs, 6 sub-sub-ISOs, 12 merchants, 36 transactions (3 per merchant, authorize + capture, random amounts $7.01-$89.50).

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 (historical filename preserved)