2
Service boundaries
Catalog and Diagnostic services communicate through explicit APIs.
Reference Implementation
gRPC Microservices Reference
A public reference implementation for contract-first gRPC services, service-owned persistence, durable diagnostic workflows, security boundaries, reliability controls, and OpenTelemetry-based observability.
GogRPCProtocol BuffersPostgreSQLOpenTelemetryDockerKubernetesJWT / RBAC
DB
Service-owned persistence
Each service owns its own PostgreSQL schema and application role.
JWT
JWT + RBAC
Least-privilege checks are enforced at service boundaries.
OTel
OpenTelemetry
Traces, metrics, and logs make local runtime behavior inspectable.
System Architecture
A minimal, production-inspired distributed system.
The runtime centers on Catalog and Diagnostic services. Callers authenticate at service boundaries, Diagnostic performs Catalog lookups through a gRPC client where required, each service persists through its own PostgreSQL ownership boundary, and telemetry flows through OpenTelemetry into local observability tools.
Engineering Decisions
Key engineering decisions
Trade-offs that make the system reliable, secure, and maintainable.
Contract-first gRPC APIs
Define service behavior through Protocol Buffer contracts and unary gRPC methods.
View ADR →Service-owned persistence
Use separate service-owned schemas and avoid cross-service joins or foreign keys.
View ADR →Durable jobs and transactional outbox
Persist jobs and event records through PostgreSQL-backed state and outbox tables.
View ADR →Bounded retry for transient downstream failures
Use deadlines and bounded retry only for selected transient Catalog lookup failures.
View ADR →Runtime Behavior
From request to response, with failure handling.
A caller submits a diagnostic request to the Diagnostic Service. The service authenticates and authorizes the caller, checks Catalog where service eligibility is required, persists the accepted job and idempotency record, and returns a bounded response.
Security Boundaries
Defense in depth at service boundaries.
- Bearer JWT validation happens at service boundaries.
- RBAC decisions are owned by each service.
- Catalog and Diagnostics use separate application database privileges.
- Migration privileges are separated from normal application access.
Observability
Built for inspection, not just operation.
- OpenTelemetry instrumentation covers distributed traces for service requests and internal work paths documented by the reference implementation.
- Structured logs carry stable request and correlation metadata where supported.
- Metrics are designed around bounded dimensions rather than high-cardinality identifiers.
- Local Jaeger and Prometheus support runtime inspection in the development environment.
Runtime Evidence
Verified Runtime Evidence
Selected behaviors were reproduced locally with synthetic data and captured as runtime evidence. These artifacts demonstrate correctness, failure handling, and observability boundaries without making performance or production-scale claims.
Distributed trace
Joined Diagnostic-to-Catalog trace
A Diagnostic create request propagates W3C Trace Context across the gRPC boundary into Catalog and its PostgreSQL lookup, with Diagnostic persistence visible in the same trace.
- Result
- One trace links Diagnostic Service, the Catalog client call, Catalog Service, and PostgreSQL work.
- Boundary
- This is observability evidence, not a latency or throughput claim.
Failure handling
Catalog dependency outage
The failed request is bounded, traceable, and represented with verified retry attempts.
Optimistic concurrency
Stale update rejected
The stale writer receives Aborted after the accepted update advances the version.
Idempotency and outbox
Durable Diagnostic admission
One idempotency key maps to one durable job and one unpublished job-created outbox row.
Scope And Limitations
A focused reference implementation.
Verified locally with synthetic data. No performance, scalability, availability, or production-reliability claims are implied.
No billing, tenant administration, or product-management workflows.
No broad API gateway, GraphQL layer, or MCP server in the core MVP.
No service mesh, streaming RPCs, CQRS, event sourcing, or cloud-provider-specific infrastructure in the current scope.