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
64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# 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:
|
|
1. **entgo.io/ent** - Code-generated, type-safe ORM
|
|
2. **gorm.io/gorm** - Feature-rich ORM with reflection
|
|
3. **sqlx** - Lightweight wrapper around database/sql
|
|
4. **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:generate` directives 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
|
|
|