Gateway Foundation — Build Summary

Date: 2026-08-14 Epic: Gateway Foundation Status: Complete

---

What Was Built

The Marchay Integration Gateway — a stateless, connector-based API gateway that routes requests to external resources through a uniform pipeline. This is the foundation for all Integration Architecture work.

Core Components

Component	Location	Purpose
Fastify App	gateway/src/app.ts	App factory, hooks, catch-all routing
Config	gateway/src/config.ts	Environment-based config (port, Redis, Postgres)
Server	gateway/src/server.ts	Entry point, registers connectors and routes
Connector Registry	gateway/src/connectors/index.ts	Register, retrieve, list connectors
Connector Interface	gateway/src/connectors/types.ts	Connector contract: name, health(), request()
Pipeline	gateway/src/pipeline/index.ts	Ordered step executor
Route Matching	gateway/src/routes/index.ts	Route config and lookup
Error Handling	gateway/src/errors/	Categorization + uniform error response

Connectors (Stubs)

Name	File	Status
salesforce	gateway/src/connectors/stubs/salesforce.ts	Stub — returns mock data
opentable	gateway/src/connectors/stubs/partner.ts	Stub — returns mock data
resy	gateway/src/connectors/stubs/partner.ts	Stub — returns mock data

Pipeline Steps

1. parse-request — Extract method, path, body, query
2. authenticate — Stub (always passes)
3. rate-limit — Stub (always passes)
4. route-to-connector — Look up connector, execute vendor call
5. error-handling — Set status code based on error
6. logging — Track latency

Shared Package

File	Purpose
shared/src/types/consumer.ts	Consumer, RateLimitConfig types
shared/src/types/member.ts	Member, Trip types
shared/src/types/quote.ts	Quote, QuoteItem types
shared/src/types/booking.ts	Booking types
shared/src/schemas/request.ts	Zod validation schemas
shared/src/schemas/response.ts	Response schemas
shared/src/utils/cursor.ts	Cursor pagination
shared/src/utils/idempotency.ts	Idempotency key generation

---

File Structure

marchay-integration/
├── gateway/
│   ├── src/
│   │   ├── app.ts
│   │   ├── config.ts
│   │   ├── server.ts
│   │   ├── connectors/
│   │   │   ├── index.ts
│   │   │   ├── types.ts
│   │   │   └── stubs/
│   │   │       ├── salesforce.ts
│   │   │       └── partner.ts
│   │   ├── middleware/
│   │   │   ├── authenticate.ts
│   │   │   ├── error-handling.ts
│   │   │   ├── logging.ts
│   │   │   ├── parse-request.ts
│   │   │   ├── rate-limit.ts
│   │   │   └── route-to-connector.ts
│   │   ├── pipeline/
│   │   │   ├── index.ts
│   │   │   └── types.ts
│   │   ├── routes/
│   │   │   ├── index.ts
│   │   │   └── health.ts
│   │   └── errors/
│   │       ├── index.ts
│   │       └── response.ts
│   ├── tests/
│   │   ├── connectors/registry.test.ts
│   │   ├── pipeline/pipeline.test.ts
│   │   ├── routes/routing.test.ts
│   │   ├── routes/error-response.test.ts
│   │   ├── routes/health.test.ts
│   │   └── integration/routes.integration.test.ts
│   ├── package.json
│   ├── tsconfig.json
│   ├── vitest.config.ts
│   └── Dockerfile
├── shared/
│   ├── src/
│   │   ├── types/
│   │   ├── schemas/
│   │   └── utils/
│   ├── package.json
│   └── tsconfig.json
├── docker-compose.yml
├── pnpm-workspace.yaml
├── package.json
├── tsconfig.base.json
├── biome.json
├── Makefile
└── README.md

---

How to Run

cd marchay-integration

# Install
pnpm install

# Start infrastructure
docker compose up -d

# Start dev server (port 3001)
pnpm dev

# Run tests
pnpm test

# Lint + typecheck
pnpm biome check gateway/ shared/
cd gateway && pnpm tsc --noEmit

Endpoints

Method	Path	Description
GET	/healthz	Health check — returns 200 with uptime
GET	/statusz	Status — returns version info
GET	/v1/members	Routes to salesforce connector
POST	/v1/members	Routes to salesforce connector
GET	/v1/quotes	Routes to salesforce connector
POST	/v1/quotes	Routes to salesforce connector
POST	/v1/bookings	Routes to salesforce connector

---

Tests

6 test files, 26 tests — all passing.

File	Tests	Coverage
connectors/registry.test.ts	5	Registry CRUD
pipeline/pipeline.test.ts	4	Step execution, error handling
routes/routing.test.ts	5	Route matching
routes/error-response.test.ts	8	Error categorization, formatting
routes/health.test.ts	2	Health endpoints
integration/routes.integration.test.ts	2	End-to-end routing

---

Acceptance Criteria Met

• [x] pnpm workspaces with gateway/ and shared/
• [x] Fastify 5 + TypeScript strict mode
• [x] Biome linting and formatting
• [x] Vitest testing
• [x] Docker Compose with Redis and Postgres
• [x] Health endpoint (GET /healthz) returns 200
• [x] Connector interface contract (name, health(), request())
• [x] Connector registry (register, get, list)
• [x] Salesforce connector stub
• [x] Partner connector stubs
• [x] Pipeline orchestrator with ordered steps
• [x] PipelineStep interface
• [x] Stateless routing
• [x] Route configuration and matching
• [x] 404 for unknown routes
• [x] Error categories (transient, permanent, quota, unknown)
• [x] Uniform error response shape
• [x] Structured logging with request_id, latency
• [x] All tests passing
• [x] Biome check clean
• [x] TypeScript --noEmit clean

---

What's Next (Future Epics)

1. Authentication System — Inbound consumer auth (API key + secret), outbound vendor auth (OAuth 2.0 JWT Bearer), token caching
2. Error Handling & Resilience — Bounded retries, idempotency keys, circuit breakers
3. Rate Limiting & Quota Management — Per-consumer inbound limits, per-resource outbound quotas, Salesforce governor limits
4. REST API — Full CRUD for members, quotes, bookings
5. Webhooks — Inbound webhook termination, outbound delivery