0x1d
38a251968c
Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.
Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
- Each service has own entry point (cmd/{service}/)
- Each service has own gRPC server and database schema
- Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
- Single entry point for all external traffic
- Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation
Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files
New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)
New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation
2.5 KiB
2.5 KiB
ADR-0013: Database ORM Selection
Status
Accepted
Context
The platform follows a microservices architecture where each service has its own database connection. The ORM/library must:
- Support PostgreSQL (primary database)
- Provide type-safe query building
- Support code generation (reduces boilerplate)
- Handle migrations per service
- Support relationships (many-to-many, etc.)
- Integrate with Ent (code generation)
- Support schema isolation (each service owns its schema)
Options considered:
- entgo.io/ent - Code-generated, type-safe ORM
- gorm.io/gorm - Feature-rich ORM with reflection
- sqlx - Lightweight wrapper around database/sql
- Standard library database/sql - No ORM, raw SQL
Decision
Use entgo.io/ent as the primary ORM for the platform.
Rationale:
- Code generation provides compile-time type safety
- Excellent schema definition and migration support
- Strong relationship modeling
- Good performance (no reflection at runtime)
- Active development and good documentation
- Recommended in playbook.md
- Easy to integrate with OpenTelemetry
Consequences
Positive
- Type-safe queries eliminate runtime errors
- Schema changes are explicit and versioned
- Code generation reduces boilerplate
- Good migration support
- Strong relationship support
Negative
- Requires code generation step (
go generate) - Learning curve for developers unfamiliar with Ent
- Less flexible than raw SQL for complex queries
- Generated code must be committed or verified in CI
Database Access Pattern
- Each service has its own database connection pool: Services do not share database connections
- Schema isolation: Each service owns its database schema (e.g.,
auth_schema,identity_schema,blog_schema) - No cross-service database access: Services communicate via APIs, not direct database queries
- Shared database instance: Services share the same PostgreSQL instance but use different schemas
- Alternative: Database-per-service pattern (each service has its own database) for maximum isolation
Implementation Notes
- Install:
go get entgo.io/ent/cmd/ent - Each service initializes its own schema:
go run entgo.io/ent/cmd/ent init User Role Permission(Identity Service) - Use
//go:generatedirectives for code generation per service - Run migrations on startup via
client.Schema.Create()for each service - Create database client wrapper per service in
services/{service}/internal/database/client.go - Each service manages its own connection pool configuration