Course outline

01 · Introduction to the Meridian Platform3/3

02 · Workspace Layout, Design Principles, and the Platform Library5/5

03 · The Data Layer4/4

04 · Identity Service: HTTP API Layer4/4

05 · Authentication and Authorization4/4

06 · The Gateway Service2/2

07 · Testing Strategy5/5

08 · Caching and Rate Limiting3/3

09 · Background Processing3/3

10 · File Storage2/2

11 · Event-Driven Communication3/3

12 · Resilience Patterns2/2

13 · Observability3/3

14 · Advanced PostgreSQL3/3

15 · API Versioning and the Platform Contract2/2

16 · Containerization and Deployment4/4

17 · CI/CD Pipeline2/2

18 · Security Hardening2/2

19 · Capstone: System Integration2/2

20 · Retrospective2/2

Stage 7 · Master

API Versioning and the Platform Contract

Documenting Contracts with OpenAPI

OpenAPI does not exist in meridian yet. This chapter defines the future documentation source of truth: the gateway publishes the public specification, and the schemas mirror the response.Envelope and APIError types already implemented in libs/platform.

15 min readMeridian: A Multi-Tenant Go PlatformMaster

Why the Gateway Publishes the Spec

Because gateway is the only public entrypoint, it must also own the public contract artifact. Publishing separate OpenAPI documents from identity-service, community-service, and billing-service would expose internal boundaries the browser never calls and would make compatibility review harder. The gateway spec should describe client-visible routes, DTOs, and shared envelope behavior, while internal service contracts stay implementation detail unless another external consumer emerges.

Specification is planned, not present

There is no OpenAPI file, generator, or CI publication flow in the current repository. The chapter defines the documentation contract for the phase where versioned gateway routes first appear.

Schema from the Platform Contract

The starting point is already concrete: successful responses must wrap payloads in the Envelope shape from libs/platform/response, and failures must match libs/platform/errors.APIError. OpenAPI should therefore encode those shared schemas once and reuse them across gateway paths. That keeps documentation aligned with the existing Go types and prevents every endpoint from hand-describing the same outer contract differently.

Planned reusable schemas

components:
  schemas:
    ApiError:
      type: object
      required: [code, message, trace_id]
      properties:
        code:
          type: string
        message:
          type: string
        trace_id:
          type: string
        details:
          type: object
          additionalProperties:
            type: string
    EnvelopeResidents:
      type: object
      required: [data, error]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Resident'
        meta:
          $ref: '#/components/schemas/ListMeta'
        error:
          type: 'null'

The outer schema mirrors the platform library types. Endpoint-specific variation lives under data, not in the envelope itself.

Publication Workflow

Files in this step— Planned contract-documentation artifacts.

apps/gateway/openapi/openapi.yamlcreate

Responsibility: Hold the published gateway contract for public client integration and review.

Why now: The public contract needs one authoritative artifact owned by the only public entrypoint.

Connects to: Documents the versioned routes added under apps/gateway/internal/router/router.go.

apps/gateway/openapi/components/platform-contract.yamlcreate

Responsibility: Define reusable schemas for Envelope and APIError-derived structures.

Why now: Shared contract pieces should not be duplicated across every path item.

Connects to: Mirrors libs/platform/response and libs/platform/errors.

.github/workflows/openapi.ymlcreate

Responsibility: Validate the spec on each change and publish rendered docs or artifacts for review.

Why now: Contract drift is easier to catch in CI than after a frontend integration breaks.

Connects to: Runs whenever gateway route DTOs or OpenAPI sources change.

Terminal — planned OpenAPI scaffolding

$mkdir -p apps/gateway/openapi/components

// Create the gateway OpenAPI directory and its shared-components subdirectory in one step.

$touch apps/gateway/openapi/openapi.yaml

// Add the planned top-level public contract file owned by the gateway.

$touch apps/gateway/openapi/components/platform-contract.yaml

// Add the planned shared schema file that mirrors the platform response and error envelopes.

$mkdir -p .github/workflows

// Create the workflow directory for spec validation and publication automation.

$touch .github/workflows/openapi.yml

// Add the planned CI workflow file that will validate and publish OpenAPI artifacts.

The workflow should make contract review visible in pull requests. A route change in gateway should produce an OpenAPI diff that reviewers can inspect before merge. That matters more in a multi-service repo because internal implementation churn can be high while the public boundary must remain disciplined.

Limits of OpenAPI

OpenAPI proves field shape, requiredness, and basic examples; it does not prove authorization rules by itself.
Tenant resolution semantics, rate limits, and eventual consistency behaviors still need prose documentation and tests.
The spec should describe public gateway routes, not every internal service endpoint used only for intra-cluster traffic.

The Decision

Meridian's future OpenAPI source of truth lives at the gateway and reuses the Platform Contract shapes that already exist in libs/platform. The publication workflow should make public-contract drift reviewable in CI, while acknowledging that schema documentation complements rather than replaces semantic tests and prose architecture notes.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.