114 lines
5.2 KiB
Markdown
114 lines
5.2 KiB
Markdown
# 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](https://microservices.io/patterns/data/service-per-database.html)
|
|
- [Service Discovery Patterns](https://microservices.io/patterns/service-registry.html)
|
|
- [gRPC Documentation](https://grpc.io/docs/)
|
|
|