Gateway Foundation Build Brief

Build brief for the first epic of the API Gateway: Gateway Foundation. This is the starting point for all Integration Architecture work.

---

Overview

Epic: Gateway Foundation Estimated effort: ~1-2 weeks Depends on: Nothing (this is the foundation) Enables: Auth, Error Handling, Rate Limiting, REST API, Webhooks

Build a stateless, connector-based API gateway that routes requests to external resources (Salesforce, partners, databases, payments) through a uniform pipeline. The gateway is the single ingress point for all platform traffic.

---

Acceptance Criteria

1. Project Setup

• ☐ Initialize marchay-integration repo with pnpm workspaces
• ☐ Create gateway/ and shared/ packages
• ☐ Set up Fastify with TypeScript, strict mode
• ☐ Configure Biome for linting and formatting
• ☐ Configure Vitest for testing
• ☐ Create Docker Compose with Redis and Postgres
• ☐ Create health endpoint (GET /healthz) returning 200 OK

2. Connector Abstraction

• ☐ Define Connector interface contract:

  interface Connector {
    name: string;
    health(): Promise<boolean>;
    request(resource: string, params: unknown): Promise<ConnectorResponse>;
  }

• ☐ Implement connector registry (register, get by name)
• ☐ Create Salesforce connector stub implementing the interface
• ☐ Create partner connector stubs (OpenTable, Resy, etc.)

3. Request Pipeline

• ☐ Build pipeline orchestrator with ordered steps:
  1. Parse request
  2. Authenticate (stub for now)
  3. Rate limit (stub for now)
  4. Route to connector
  5. Execute vendor call
  6. Handle errors
  7. Log request
  8. Respond
• ☐ Each step implements a PipelineStep interface:

  interface PipelineStep {
    name: string;
    execute(req: GatewayRequest, ctx: PipelineContext): Promise<PipelineContext>;
  }

4. Request Routing

• ☐ Implement stateless routing: any request hits any replica
• ☐ Build route configuration:

  interface RouteConfig {
    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
    path: string;
    connector: string;
    resource: string;
  }

• ☐ Register routes from configuration
• ☐ Return 404 for unknown routes

5. Basic Error Handling

• ☐ Implement error categories: Transient, Permanent, Quota, Unknown
• ☐ Build uniform error response shape:

  {
    "code": "TRANSIENT_ERROR",
    "message": "Vendor temporarily unavailable",
    "retryable": true,
    "vendor_code": 503,
    "request_id": "req_abc123"
  }

• ☐ Catch connector errors and map to uniform response

6. Logging

• ☐ Set up pino with structured JSON output
• ☐ Log every request with: request_id, method, path, status, latency_ms
• ☐ Log connector calls with: connector, resource, latency_ms, status

7. Tests

• ☐ Unit tests for connector registry
• ☐ Unit tests for pipeline orchestrator
• ☐ Unit tests for route matching
• ☐ Unit tests for error response shape
• ☐ Integration test: health endpoint returns 200
• ☐ Integration test: unknown route returns 404

---

File Structure (created by this brief)

marchay-integration/
├── gateway/
│   ├── src/
│   │   ├── app.ts
│   │   ├── config.ts
│   │   ├── server.ts
│   │   ├── connectors/
│   │   │   ├── index.ts
│   │   │   ├── types.ts
│   │   │   └── stubs/
│   │   │       ├── salesforce.ts
│   │   │       └── partner.ts
│   │   ├── routes/
│   │   │   ├── index.ts
│   │   │   └── health.ts
│   │   ├── pipeline/
│   │   │   ├── index.ts
│   │   │   └── types.ts
│   │   ├── errors/
│   │   │   ├── index.ts
│   │   │   └── response.ts
│   │   └── middleware/
│   │       └── logging.ts
│   ├── tests/
│   │   ├── connectors/
│   │   ├── routes/
│   │   └── pipeline/
│   ├── package.json
│   ├── tsconfig.json
│   └── Dockerfile
├── shared/
│   ├── src/
│   │   └── types/
│   ├── package.json
│   └── tsconfig.json
├── docker-compose.yml
├── pnpm-workspace.yaml
├── package.json
└── tsconfig.base.json

---

Implementation Phases

Phase 1: Project Scaffolding (Day 1)

1. Initialize pnpm workspace
2. Create gateway/ package with Fastify
3. Create shared/ package
4. Set up Docker Compose (Redis, Postgres)
5. Create health endpoint
6. Verify pnpm dev starts server

Phase 2: Connector Layer (Day 2-3)

1. Define Connector interface in shared/
2. Implement connector registry
3. Create Salesforce connector stub
4. Create partner connector stubs
5. Write tests for registry

Phase 3: Pipeline (Day 3-4)

1. Define PipelineStep interface
2. Build pipeline orchestrator
3. Implement basic logging step
4. Implement error handling step
5. Write tests for pipeline

Phase 4: Routing (Day 4-5)

1. Implement route configuration
2. Build route matching
3. Wire routes to pipeline
4. Write integration tests

Phase 5: Polish (Day 5)

1. Add structured logging
2. Add request_id generation
3. Run all tests
4. Fix lint and type errors
5. Create README.md

---

Dependencies

Dependency	Version	Purpose
fastify	^5.0.0	HTTP framework
@fastify/cors	^10.0.0	CORS handling
@fastify/helmet	^13.0.0	Security headers
pino	^9.0.0	Structured logging
pino-pretty	^11.0.0	Dev logging
redis	^4.6.0	Redis client
zod	^3.23.0	Schema validation
vitest	^2.0.0	Testing
@biomejs/biome	^1.7.0	Linting
tsup	^8.0.0	Build
typescript	^5.4.0	Type checking