goplt/docs/content/adr/0029-microservices-architecture.md

ADR-0029: Microservices Architecture

Status

Accepted

Context

The platform needs to scale independently, support team autonomy, and enable flexible deployment. A microservices architecture provides these benefits from day one, and the complexity of supporting both monolith and microservices modes is unnecessary.

Decision

Design the platform as microservices architecture from day one:

1. Core Services: Core business services are separate microservices:

   • Auth Service (cmd/auth-service/): JWT token generation/validation
   • Identity Service (cmd/identity-service/): User CRUD, password management
   • Authz Service (cmd/authz-service/): Permission resolution, authorization
   • Audit Service (cmd/audit-service/): Audit logging
   • Each service has its own process, database connection, and deployment

2. API Gateway: Core infrastructure component (implemented in Epic 1):

   • Single entry point for all external traffic
   • Routes requests to backend services via service discovery
   • Handles authentication, rate limiting, CORS at the edge
   • Not optional - required for microservices architecture

3. Service-Based Architecture: All modules are independent services:

   • Each module/service is a separate service with its own process
   • Services communicate via gRPC (primary) or HTTP (fallback)
   • Service client interfaces for all inter-service communication
   • No direct in-process calls between services

4. Service Registry: Central registry for service discovery:

   • All services register on startup
   • Service discovery via registry
   • Health checking and automatic deregistration
   • Support for Consul, etcd, or Kubernetes service discovery

5. Communication Patterns:

   • Synchronous: gRPC service calls (primary), HTTP/REST (fallback)
   • Asynchronous: Event bus via Kafka
   • Shared Infrastructure: Cache (Redis) and Database (PostgreSQL instance)
   • Database Access: Each service has its own connection pool and schema

6. Service Boundaries: Each service is independent:

   • Independent Go modules (go.mod)
   • Own database schema (via Ent) - schema isolation
   • Own API routes (gRPC/HTTP)
   • Own process and deployment
   • Can be scaled independently

7. Development Mode: For local development, services run in the same repository:

   • Each service has its own entry point and process
   • Services still communicate via service clients (gRPC/HTTP)
   • No direct in-process calls
   • Docker Compose for easy local setup

Consequences

Positive

• Simplified Architecture: Single architecture pattern, no dual-mode complexity
• Independent Scaling: Scale individual services based on load
• Team Autonomy: Teams can own and deploy their services independently
• Technology Diversity: Different services can use different tech stacks (future)
• Fault Isolation: Failure in one service doesn't bring down entire platform
• Deployment Flexibility: Deploy services independently
• Clear Boundaries: Service boundaries are explicit from the start

Negative

• Network Latency: Inter-service calls have network overhead
• Distributed System Challenges: Need to handle network failures, retries, timeouts
• Service Discovery Overhead: Additional infrastructure needed
• Debugging Complexity: Distributed tracing becomes essential
• Data Consistency: Cross-service transactions become challenging
• Development Setup: More complex local development (multiple services)

Mitigations

• API Gateway: Implemented in Epic 1 as core infrastructure - handles routing, authentication, rate limiting
• Service Mesh: Use service mesh (Istio, Linkerd) for advanced microservices features (optional)
• Event Sourcing: Use events for eventual consistency
• Circuit Breakers: Implement circuit breakers for resilience
• Comprehensive Observability: OpenTelemetry, metrics, logging essential
• Docker Compose: Simplify local development with docker-compose
• Service Clients: All inter-service communication via service clients (gRPC/HTTP)

Implementation Strategy

Epic 1: Core Kernel & Infrastructure

• Core kernel (infrastructure only): config, logger, DI, health, metrics, observability
• API Gateway implementation (core infrastructure component)
• Service client interfaces for all core services
• Service registry interface and basic implementation

Epic 2: Core Services Separation

• Separate Auth, Identity, Authz, Audit into independent services
• Each service: own entry point (cmd/{service}/), gRPC server, database connection
• Service client implementations (gRPC/HTTP)
• Service registration with registry

Epic 3: Service Registry & Discovery (Epic 3)

• Complete service registry implementation
• Service discovery (Consul, Kubernetes)
• Service health checking and deregistration

Epic 5: gRPC Services (Epic 5)

• Complete gRPC service definitions for all services
• gRPC clients for service communication
• HTTP clients as fallback option

References

• Service Abstraction Pattern
• Service Discovery Patterns
• gRPC Documentation