Back to Portfolio

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.

View SourceBack to Portfolio

Stack

GogRPCProtocol BuffersPostgreSQLOpenTelemetryDockerKubernetesJWT / RBAC

What This Demonstrates

Engineering capabilities made inspectable.

Distributed Systems

  • gRPC service boundaries
  • contract-first APIs
  • remote failure handling
  • service-owned data
  • optimistic concurrency

Reliability

  • deadlines
  • bounded retries
  • health checks
  • graceful shutdown
  • controlled failure propagation

Security

  • JWT authentication
  • RBAC authorization
  • least-privilege application roles
  • explicit trust boundaries

Operational Engineering

  • OpenTelemetry
  • structured logging
  • migrations
  • CI / validation
  • containerized local environment

Problem And Constraints

A narrow domain for visible engineering decisions.

Many sample microservice systems either collapse data ownership into one shared database or expand into platform scope before contracts, trust boundaries, and failure behavior are clear. This reference keeps the domain intentionally small so reviewers can inspect the engineering choices directly.

Services own their data and avoid cross-service database joins.
Cross-service communication occurs through documented gRPC contracts.
Authorization is enforced at service boundaries rather than delegated to callers.
Downstream failures are expected and translated into bounded service responses.
The system remains independently runnable as a public reference implementation.
Observability uses OpenTelemetry-compatible traces, metrics, and structured logs.
Shared database coupling and broad platform scope are intentionally avoided.

System Architecture

Bounded services, explicit contracts, portable telemetry.

Service Responsibilities

Ownership stays with the service.

Catalog Service

Owns

  • fictional service records
  • catalog authorization rules
  • service metadata validation

Exposes

  • register service
  • get service
  • update service

Depends on

  • PostgreSQL catalog schema
  • JWT validation

Persistence

Catalog-owned PostgreSQL schema and application role

Diagnostic Service

Owns

  • diagnostic job acceptance
  • job retrieval
  • idempotency records
  • diagnostic workflow state

Exposes

  • create diagnostic job
  • get diagnostic job

Depends on

  • Catalog gRPC lookup
  • PostgreSQL diagnostics schema
  • JWT validation

Persistence

Diagnostics-owned PostgreSQL schema and application role

Request Flow

Create Diagnostic Job flow.

Create Diagnostic Job

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.

Where controls apply

  • Deadlines bound downstream Catalog calls.
  • Authorization is enforced before protected service behavior.
  • gRPC errors are translated into documented status responses.

Engineering Decisions

Trade-offs, not just technology choices.

Contract-first gRPC APIs

Source ADR
Context
The services need explicit API boundaries that can be reviewed independently from implementation details.
Decision
Define service behavior through Protocol Buffer contracts and unary gRPC methods.
Trade-off
Contracts become easy to inspect and test, while clients must handle typed remote errors explicitly.

Service-owned persistence

Source ADR
Context
Shared tables would make the example easier to wire, but would hide ownership boundaries.
Decision
Use separate service-owned schemas and avoid cross-service joins or foreign keys.
Trade-off
Ownership is clear, at the cost of explicit cross-service reads where one service needs another service's state.

Durable jobs and transactional outbox

Source ADR
Context
Diagnostic requests need a durable acceptance path without claiming exactly-once processing.
Decision
Persist jobs and event records through PostgreSQL-backed state and outbox tables.
Trade-off
The implementation can recover committed work, while publication and consumers still need idempotency.

Bounded retry for transient downstream failures

Source ADR
Context
Blind retries across every layer can amplify outages, but selected safe reads can tolerate transient failure.
Decision
Use deadlines and bounded retry only for selected transient Catalog lookup failures.
Trade-off
The system improves resilience for safe calls without obscuring persistent downstream failures.

JWT and RBAC at service boundaries

Source ADR
Context
A service should not trust a caller or adapter to have already performed authorization correctly.
Decision
Validate bearer tokens and enforce role checks in the owning service.
Trade-off
Trust boundaries are explicit, while local development needs signed token fixtures.

OpenTelemetry as telemetry standard

Source ADR
Context
The reference needs traces, metrics, and logs without binding the core design to one vendor.
Decision
Use OpenTelemetry-compatible instrumentation and local observability tooling.
Trade-off
Telemetry remains portable, while runtime evidence still needs to be captured from verified local runs.

Reliability And Failure Model

Implemented behavior is separated from future evidence.

Implemented behavior

Invalid or expired credentials

Requests fail closed before protected service behavior executes.

Implemented behavior

Insufficient role

The owning service rejects the operation through RBAC authorization.

Implemented behavior

Catalog unavailable

Diagnostic-to-Catalog calls are bounded by deadlines and documented error translation.

Implemented behavior

Request deadline exceeded

The service returns a bounded failure rather than waiting indefinitely.

Implemented behavior

Optimistic-lock conflict

Concurrent stale updates are rejected rather than silently overwriting service metadata.

Implemented behavior

Database failure

Readiness and persistence paths surface failure through service status and errors.

Implemented behavior

Graceful shutdown

Server lifecycle code is designed to stop accepting work and shut down cleanly.

Security Boundaries

Authentication, authorization, and persistence privileges.

Caller

then

Service boundary

then

Application logic

then

PostgreSQL
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.
Diagnostic-to-Catalog communication uses a dedicated service credential in local development.
Logs and telemetry avoid recording authorization headers or secrets by default.

Observability

Telemetry designed for local inspection and future evidence.

OpenTelemetry instrumentation covers 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 trace and metric evidence will be added from verified local runs.

Verified Behavior

Documented behavior without inflated claims.

Service registration

Catalog accepts valid service registration through the documented gRPC API.

Duplicate registration handling

Duplicate Catalog records are rejected through documented service behavior.

Service lookup

Catalog retrieves registered service metadata by identifier.

Optimistic update conflict handling

Catalog update paths use version-aware conflict behavior.

Diagnostic job creation

Diagnostic accepts job creation requests after authorization and Catalog validation.

Diagnostic job retrieval

Diagnostic exposes retrieval for accepted jobs.

Health service reporting

Catalog and Diagnostic services expose gRPC health responses.

Unit and integration validation

The reference repository documents validation across service, repository, transport, auth, and reliability paths.

Trade-offs And Limitations

Deliberate scope boundaries.

Trade-offs

The reference intentionally limits service count so boundaries stay inspectable.
Synchronous gRPC is used where immediate validation is valuable; broader event-driven scope is deferred.
The design avoids premature multi-region architecture and complex multi-tenancy.
Services do not share database ownership, which makes some cross-service reads explicit.
The local observability environment is lightweight and intended for inspection, not managed operations.
Performance and scalability claims require measured experiments before being added.

Non-goals

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.
No fabricated benchmarks, screenshots, or production-readiness claims.

Future Extensions

Neutral technical extensions, gated by evidence.

Add asynchronous workflows where decoupling adds clear value.
Capture deeper failure-testing evidence from repeatable local runs.
Run measured load experiments and document the results.
Add verified trace and metric artifacts from Jaeger and Prometheus.
Integrate controlled AI or MCP diagnostic adapters through documented APIs.
Add optional experience or API layers without changing service ownership boundaries.