Integration Project Structure

Separate repository (marchay-integration) for all Integration Architecture services. This document defines the repo layout, tech stack, and conventions.

---

Repository Layout

marchay-integration/
├── gateway/                      # Main API Gateway service — Fastify
│   ├── src/
│   │   ├── app.ts                # Fastify app factory, plugins, lifecycle
│   │   ├── config.ts             # Settings via @fastify/env or envalid
│   │   ├── server.ts             # Server entry point
│   │   ├── plugins/
│   │   │   ├── auth.ts           # Authentication plugin (inbound + outbound)
│   │   │   ├── rate-limit.ts     # Rate limiting plugin
│   │   │   ├── circuit-breaker.ts
│   │   │   ├── error-handling.ts
│   │   │   ├── logging.ts        # Structured JSON logging
│   │   │   ├── tracing.ts        # OpenTelemetry tracing
│   │   │   └── cors.ts
│   │   ├── connectors/
│   │   │   ├── index.ts          # Connector registry
│   │   │   ├── types.ts          # Connector interface contract
│   │   │   ├── salesforce/
│   │   │   │   ├── index.ts
│   │   │   │   ├── auth.ts       # OAuth 2.0 JWT Bearer
│   │   │   │   ├── mapper.ts     # API translation
│   │   │   │   └── errors.ts     # Error mapping
│   │   │   ├── atlantes/
│   │   │   └── partner/          # Partner API connectors (stubs)
│   │   ├── routes/
│   │   │   ├── index.ts          # Route registration
│   │   │   ├── health.ts         # /healthz, /statusz
│   │   │   ├── members.ts        # /v1/members
│   │   │   ├── quotes.ts         # /v1/quotes
│   │   │   ├── bookings.ts       # /v1/bookings
│   │   │   └── webhooks/
│   │   │       ├── salesforce.ts # POST /v1/webhooks/salesforce/*
│   │   │       └── outbound.ts   # Outbound webhook delivery
│   │   ├── pipeline/
│   │   │   ├── index.ts          # Request pipeline orchestrator
│   │   │   ├── types.ts          # Pipeline step interface
│   │   │   └── steps/            # Individual pipeline steps
│   │   ├── webhooks/
│   │   │   ├── inbound.ts        # Webhook termination, verification
│   │   │   ├── outbound.ts       # Subscription model, delivery
│   │   │   └── dedup.ts          # Event deduplication
│   │   ├── errors/
│   │   │   ├── index.ts          # Error categories and types
│   │   │   ├── response.ts       # Uniform error response shape
│   │   │   └── circuit.ts        # Circuit breaker state machine
│   │   └── metrics/
│   │       ├── index.ts
│   │       └── gateway-metrics.ts
│   ├── tests/
│   │   ├── helpers/
│   │   │   └── fixtures.ts
│   │   ├── plugins/
│   │   ├── routes/
│   │   ├── connectors/
│   │   └── integration/
│   ├── migrations/
│   ├── package.json
│   ├── tsconfig.json
│   ├── Dockerfile
│   └── README.md
│
├── shared/                      # Common types and utilities
│   ├── src/
│   │   ├── types/
│   │   │   ├── consumer.ts      # Consumer, Credential types
│   │   │   ├── member.ts        # Member, Trip types
│   │   │   ├── quote.ts         # Quote types
│   │   │   └── booking.ts       # Booking types
│   │   ├── schemas/
│   │   │   ├── request.ts       # Request validation schemas (Zod)
│   │   │   └── response.ts      # Response schemas
│   │   └── utils/
│   │       ├── idempotency.ts
│   │       └── cursor.ts        # Cursor pagination utilities
│   ├── package.json
│   └── tsconfig.json
│
├── docker-compose.yml           # Local dev: Redis, Postgres
├── Makefile                     # Common commands
├── .gitlab-ci.yml               # CI/CD pipeline
└── README.md

---

Tech Stack

Component	Choice	Rationale
Language	TypeScript 5.4+	Type safety, IDE support, ecosystem
Framework	Fastify 5	High performance, plugin architecture, schema-based validation
Validation	JSON Schema (Fastify built-in)	Native integration, reject unknown fields
Auth	@fastify/jwt, @fastify/cors	Proven Fastify ecosystem
Rate Limiting	@fastify/rate-limit	Native Fastify plugin
Tracing	@fastify/helmet, OpenTelemetry	Industry standard
Logging	pino (Fastify default)	Structured JSON, high performance
Queue	Redis (Valkey fork)	Already provisioned, LPUSH/BRPOP
Testing	Vitest	Fast, native TypeScript support
Linting	Biome	Fast, comprehensive
Type Checking	TypeScript (strict)	Catch errors early
Build	tsup	Fast TypeScript bundler

---

Naming Conventions

• TypeScript: camelCase for functions, variables. PascalCase for classes, interfaces, types.
• Files: camelCase.ts for source, kebab-case.test.ts for tests
• Routes: /v1/{resource} (REST), /v1/webhooks/{vendor}/{event} (webhooks)
• Redis keys: session:{id}, dedup:{event_id}, circuit:{resource}
• Metrics: gateway_calls_total, gateway_errors_total, gateway_latency_p95
• Git branches: feat/gateway-foundation, fix/auth-timeout, chore/update-deps

---

Repo Relationship

This repo (marchay-integration) is separate from the architecture docs repo (marchay-docs) and the agent repo (marchay-agent).

Repo	Purpose	Contents
marchay-docs	Architecture planning	Design docs, build briefs, roadmaps
marchay-agent	Agent services	Orchestrator, research agents
marchay-integration	Integration services	API Gateway, connectors, webhooks

The build brief in marchay-docs serves as the spec. Implementation lives in marchay-integration.

---

Makefile

.PHONY: dev test lint typecheck build

dev:
	docker compose up -d
	cd gateway && pnpm dev

test:
	cd gateway && pnpm test

lint:
	pnpm biome check gateway/ shared/

typecheck:
	cd gateway && pnpm typecheck

build:
	cd gateway && pnpm build

docker:
	docker compose build

prod:
	docker compose -f docker-compose.prod.yml up -d