Stage 7 · Master
Meridian: A Multi-Tenant Go Platform
A technical reference course built around a complete Go microservices project: a multi-tenant HOA platform implemented as four independent services (gateway, identity, community, billing) sharing a common platform library. Chapters follow the project's actual structure and code — go.work, libs/platform, Postgres, Redis, Kafka, Docker, Kubernetes — with unimplemented areas marked explicitly as design specification, not fabricated code.
Prerequisite
The Complete Go Engineer. No prior backend experience required.
What this course leaves you with
- Read and reason about a multi-service Go monorepo: apps/, libs/platform, go.work
- Design multi-tenant isolation from the Postgres schema up through the gateway
- Apply SOLID in Go without a framework, and test the result honestly
- Ship every service as an independent, health-checked Kubernetes Deployment with CI/CD
Why this stage matters — You've finished Go fundamentals — this is where you study a real production Go platform, service by service.
Progress
0 of 60 lessons complete. Progress is stored locally in your browser so you can pick the path back up later.
course completion
Introduction to the Meridian Platform
Scope, domain, technology stack, and target architecture of the Meridian platform: a multi-tenant HOA management system built as four Go services plus a shared platform library.
- 01Welcome: How to Use This CourseWho this course is for, what you should already know, what to install, how each lesson is structured, and the four-stage learning path across all 20 chapters.10 min
- 02The Domain ModelThe HOA management domain: tenants, users and memberships, residents, units, announcements, complaints, invoices, and payments — and how responsibility for each is split across services.8 min
- 03Technology Stack and Target ArchitectureEvery component of the stack — Go, go.work, Postgres, Redis, Kafka, Docker, Kubernetes — and the target architecture: a single public gateway in front of four internal services.13 min
Workspace Layout, Design Principles, and the Platform Library
The go.work multi-module workspace, per-service module boundaries, cmd/internal conventions, how interfaces and constructor injection keep every service testable, and the shared libs/platform module used by every service.
- 01The go.work WorkspaceWhy the repository is organized as five modules under a single go.work file from the outset, and how local replace directives wire libs/platform into every service.14 min
- 02Command and Internal Package ConventionsThe cmd/<service>/main.go entrypoint convention and the internal/ package layout used to keep each service's implementation details unimportable from outside its module.10 min
- 03Interfaces and Dependency InversionDefining small interfaces at the point of use so domain packages depend on abstractions, not concrete infrastructure — and why every later chapter that mocks a dependency for a test relies on this.15 min
- 04Constructor Injection and TestabilityWiring dependencies explicitly in main.go via constructor functions, why this makes a DI framework unnecessary, and how it produces the testable seams used throughout the testing chapter.14 min
- 05The Platform Librarylibs/platform's five packages — config, logging, errors, response, and tenancy — and the shared conventions they enforce across all four services: environment-based config, structured slog logging, and the Platform Contract envelope.15 min
The Data Layer
Multi-tenant Postgres schema design, migrations, the repository pattern, and transactional tenant isolation.
- 01Multi-Tenant Schema DesignThe shared-schema, tenant_id-column isolation model used across every tenant-scoped table, and why it was chosen over schema-per-tenant.16 min
- 02Schema MigrationsVersioned SQL migrations kept separate from application code, and seed data conventions for local development.11 min
- 03The Repository Pattern with pgxIsolating SQL behind repository interfaces so domain and HTTP layers never depend on pgx directly.13 min
- 04Transactions and Tenant IsolationEnforcing tenant_id scoping at the query layer and wrapping multi-statement operations in explicit transactions.12 min
Identity Service: HTTP API Layer
The identity-service's HTTP layer: routing, request/response contracts, error handling, and pagination — built on net/http today, with Gin identified as a planned upgrade.
- 01HTTP RoutingThe stdlib net/http.ServeMux baseline used by every service today, and the route-group conventions a router upgrade (e.g. Gin) would need to preserve.12 min
- 02Request and Response ContractsMapping HTTP handlers onto the Platform Contract's response.Envelope type, and validating request payloads before they reach domain logic.13 min
- 03Error Handling ConventionsTranslating domain and infrastructure errors into libs/platform/errors.APIError values with stable codes and trace IDs.10 min
- 04Pagination, Filtering, and SortingConsistent list-endpoint conventions for cursor-based pagination, filter parameters, and sort ordering across services.11 min
Authentication and Authorization
Identity-service authentication and RBAC: password hashing, token issuance and rotation, and permission enforcement at the middleware layer.
- 01Password Hashing and Token IssuanceCredential storage and JWT issuance in identity-service, and how it interacts with the planned Auth0 token verification path.13 min
- 02Refresh Token RotationShort-lived access tokens paired with rotating refresh tokens to bound the blast radius of a leaked credential.11 min
- 03Permission ModelingA service:resource:action permission model layered over tenant-scoped memberships and roles.12 min
- 04Enforcing Authorization in MiddlewareCentralizing permission checks in shared middleware so handlers never re-implement authorization logic.12 min
The Gateway Service
apps/gateway as the platform's single public entrypoint: reverse proxying to internal services and tenant context propagation via libs/platform/tenancy.
- 01The Gateway PatternWhy apps/gateway is the only service exposed publicly, resolving a URL slug to a tenant UUID before forwarding requests to identity, community, and billing.14 min
- 02Context Propagation Across ServicesForwarding the resolved tenant UUID via the X-Tenant-Id header using libs/platform/tenancy, so internal services never resolve tenancy any other way.12 min
Testing Strategy
Unit, integration, and API-level testing conventions applied consistently across all four services and the shared platform library.
- 01Unit and Table-Driven TestsTable-driven test conventions for domain logic and the shared libs/platform packages.11 min
- 02Integration Tests with TestcontainersRunning real Postgres and Redis instances in CI to test repository and cache code against the databases they actually target.13 min
- 03Mocking Interfaces for TestsGenerating or hand-writing mocks for repository and client interfaces to keep handler tests fast and deterministic.10 min
- 04Coverage and CI GatesCoverage thresholds and workspace-wide test/vet invocation across module boundaries that go.work introduces.9 min
- 05API Testing with Postman and NewmanA Postman collection per service, environment variables for tenant and auth headers, and running the collection headlessly with Newman in CI.13 min
Caching and Rate Limiting
Redis usage across the platform: response caching, invalidation strategy, rate limiting, and session storage.
- 01What to Cache and Invalidation StrategySelecting cache candidates by read/write ratio and designing invalidation so cached data never contradicts Postgres.12 min
- 02Rate Limiting with RedisToken-bucket rate limiting at the gateway, keyed per tenant, backed by Redis counters.11 min
- 03Session Storage in RedisServer-side session state for flows that can't rely on stateless JWTs alone.9 min
Background Processing
Worker pools, job queues, and graceful shutdown for asynchronous work such as billing-service payment processing.
- 01Worker Pools in GoA bounded worker-pool pattern for processing background jobs without unbounded goroutine growth.12 min
- 02Job Queues, Retries, and SchedulingDurable job queues, retry-with-backoff semantics, and scheduling recurring work.13 min
- 03Graceful Worker ShutdownDraining in-flight jobs on SIGTERM so a Kubernetes rollout never kills work mid-execution.10 min
File Storage
Handling uploads for complaint attachments and billing receipts, and storing them in S3-compatible object storage.
- 01Handling Multipart and Streaming UploadsStreaming multipart uploads through the gateway to the owning service without buffering entire files in memory.12 min
- 02Object Storage with S3-Compatible APIsStoring uploaded files in object storage rather than Postgres, with presigned URLs for retrieval.11 min
Event-Driven Communication
Decoupling services with Kafka, and introducing reporting-service as a read-aggregating consumer once the platform's core services have real data to aggregate.
- 01Decoupling Services with EventsWhy reporting is designed as a Kafka consumer rather than a service the gateway calls synchronously.13 min
- 02Producing and Consuming Events IdempotentlyAt-least-once delivery semantics and idempotent consumer design so replayed events don't corrupt aggregated state.13 min
- 03The Outbox PatternWriting domain changes and outgoing events in the same database transaction to avoid dual-write inconsistency.12 min
Resilience Patterns
Timeouts, retries, and circuit breakers on gateway-to-service calls.
Observability
Structured logging via libs/platform/logging, Prometheus metrics, health checks, and distributed tracing across four services.
- 01Structured Logs and Error TaxonomiesJSON structured logs tagged with a service attribute so logs from all four services interleave cleanly, and a consistent error-code taxonomy.12 min
- 02Prometheus Metrics and Health ChecksExtending the existing /healthz endpoints with request-count and latency metrics scraped by Prometheus.11 min
- 03Distributed Tracing BasicsPropagating a trace ID from the gateway through every downstream call for cross-service request correlation.11 min
Advanced PostgreSQL
Indexing strategy for multi-tenant queries, connection pooling, and backup and recovery.
- 01Indexing for Multi-Tenant QueriesComposite indexes leading with tenant_id so every tenant-scoped query stays index-only.12 min
- 02Connection Pooling and N+1 Queriespgxpool sizing per service and eliminating N+1 query patterns in repository code.12 min
- 03Backups and Point-in-Time RecoveryWAL-based backup strategy and point-in-time recovery for the shared Postgres instance.10 min
API Versioning and the Platform Contract
Evolving the Platform Contract's request/response envelope without breaking existing clients, and documenting it with OpenAPI.
- 01Versioning and Backward-Compatible ChangesAdditive-only changes to the Platform Contract envelope, and when a breaking change actually requires a new version.11 min
- 02Documenting Contracts with OpenAPIGenerating OpenAPI specs from the Platform Contract types so meridian-web and other clients have a single source of truth.11 min
Containerization and Deployment
Multi-stage Docker builds per service and Kubernetes Deployments, Services, and Ingress for the platform.
- 01Multi-Stage Docker BuildsA shared multi-stage Dockerfile pattern producing a minimal runtime image per service.12 min
- 02Kubernetes Deployments, Services, and IngressOne Deployment per service, ClusterIP Services for internal traffic, and Ingress routing only to the gateway.13 min
- 03ConfigMaps, Secrets, and Resource LimitsExternalizing the .env.example values into ConfigMaps and Secrets, plus resource requests/limits per service.11 min
- 04Zero-Downtime DeploysReadiness probes and rolling update strategy so a deploy never drops in-flight requests.10 min
CI/CD Pipeline
Continuous integration for a multi-module go.work repository, and continuous deployment to Kubernetes.
- 01CI Pipeline for a Multi-Module RepositoryWhy go.work's module boundaries require explicit full-path test/vet invocations instead of a bare ./... from the repo root, and how the Makefile encodes this.12 min
- 02Continuous Deployment to KubernetesBuilding and pushing per-service images and applying manifests on merge to main.11 min
Security Hardening
Secret management, input sanitization, and dependency and image scanning across the platform.
Capstone: System Integration
Wiring the gateway, identity, community, billing, and reporting services together into one running platform, and load-testing the result.
- 01Wiring Every Service TogetherBringing up all five modules together locally and tracing a single request end-to-end from gateway to database.14 min
- 02Load Testing and an On-Call RunbookEstablishing a load-testing baseline per service and writing a runbook for the alerts observability introduced.13 min
Retrospective
What changed from the original architecture plan while building the platform, and what remains for future iterations.