Stage 7 · Master
Introduction to the Meridian Platform
Technology Stack and Target Architecture
The full Meridian technology stack, the chapter that introduces each component, and the target microservices architecture the platform is built toward.
The Stack
Meridian's stack is fixed for the duration of this course. Each row lists the chapter that introduces the component and its function within the platform.
| Layer | Component | Introduced | Function |
|---|---|---|---|
| Language & runtime | Go 1.26 | Chapter 2 | Implementation language for all five modules in the go.work workspace. |
| HTTP layer | net/http (stdlib), Gin planned | Chapter 4 | Request routing. Gin is a planned upgrade path, not yet a dependency of any service. |
| Primary datastore | PostgreSQL | Chapter 3 | Shared-schema, tenant_id-isolated relational storage for tenants, users, residents, units, invoices. |
| Schema migrations | SQL migration files | Chapter 3 | Versioned, reviewable schema changes, tracked separately from application code. |
| Auth | JWT, planned Auth0 verification | Chapter 5 | Token issuance in identity-service; RBAC enforcement in middleware. |
| Cache / sessions / rate limiting | Redis | Chapter 8 | Read-through caching, session storage, per-tenant rate limiting. |
| Background work | Go worker pools | Chapter 9 | Asynchronous processing, primarily for billing-service payment workflows. |
| Object storage | S3-compatible | Chapter 10 | Complaint attachments and billing receipts. |
| Async messaging | Kafka | Chapter 11 | Decouples reporting-service from the transactional services via event consumption. |
| Structured logging | log/slog via libs/platform/logging | Chapter 2 | JSON logs tagged with a service attribute, consistent across all four services. |
| Metrics & tracing | Prometheus, OpenTelemetry (planned) | Chapter 13 | Runtime visibility beyond the current /healthz-only baseline. |
| Containerization | Docker, multi-stage builds | Chapter 16 | One minimal runtime image per service. |
| Orchestration | Kubernetes | Chapter 16 | One Deployment per service, matching the repository's deploy/k8s/ layout. |
| CI/CD | GitHub Actions | Chapter 17 | Per-module test/vet/build across go.work boundaries. |
As of this writing, every service builds and exposes only a /healthz endpoint. No handler yet uses the response.Envelope or errors.APIError types, no service queries Postgres, and no Kafka producer or consumer exists. Chapters covering this unimplemented surface are marked as design specification, grounded in the Platform Contract types that do exist in libs/platform, not as working code.
Target Architecture
Meridian is structured as five Go modules under one go.work file from the outset: apps/gateway, apps/identity-service, apps/community-service, apps/billing-service, and libs/platform. The workspace-level module boundary is established in Chapter 2; it does not evolve incrementally from a single binary the way some smaller reference projects do.
The Gateway as Single Entrypoint
A client resolves a tenant by a human-readable slug in the URL. Only the gateway translates that slug to a tenant UUID; internal services receive the UUID via the X-Tenant-Id header defined in libs/platform/tenancy and never resolve tenancy any other way. This is covered in full in Chapter 6.
Multi-Tenancy Summary
Every tenant-scoped table carries a tenant_id column; there is no database or schema per tenant. Chapter 3 covers the schema design in full. Every later chapter that touches tenant-scoped data — caching, events, indexing — re-applies the same tenant_id discipline at its own layer.
Current Implementation Status
- go.work and all five go.mod files exist; each service module has a local replace directive pointing at libs/platform.
- libs/platform ships five packages: config, logging, errors, response, tenancy — all implemented, none yet consumed by a handler.
- Each service exposes cmd/<service>/main.go and only a /healthz route.
- apps/gateway/internal/router/router.go has no reverse-proxy routes yet; internal/middleware/middleware.go implements panic recovery only.
- apps/identity-service, apps/community-service, and apps/billing-service each have an empty internal/domain/domain.go, pending the implementation phase for their respective entities.
Running the Stack Locally
Postgres and Redis run as containers via docker-compose, added when Chapter 3 and Chapter 8 introduce the corresponding dependency, not before.
A bare go test ./... from the repository root does not traverse go.work module boundaries. The Makefile's test and vet targets pass explicit paths (github.com/thesyscoder/meridian/apps/... and .../libs/...) for this reason. Chapter 17 covers this in the CI pipeline context.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.