docs: Align documentation with true microservices architecture
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
This commit is contained in:
@@ -10,103 +10,80 @@
|
||||
- **Dependencies**: 1.1
|
||||
|
||||
## Goal
|
||||
Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
|
||||
Set up database client foundation for services. Each service will have its own database connection pool and schema.
|
||||
|
||||
## Description
|
||||
This story implements the complete database layer using Ent ORM. It includes defining core domain entities (User, Role, Permission, AuditLog), setting up migrations, configuring connection pooling, and creating a database client that integrates with the DI container.
|
||||
This story implements the database client foundation that services will use. It includes connection management, schema isolation support, connection pooling configuration, and migration runner wrapper. Core domain entities (User, Role, Permission, AuditLog) are NOT implemented here - they are part of their respective services in Epic 2.
|
||||
|
||||
## Deliverables
|
||||
|
||||
### 1. Ent Schema Initialization
|
||||
- Initialize Ent schema in `internal/ent/`
|
||||
- Set up code generation
|
||||
### 1. Database Client Foundation
|
||||
- Database client wrapper in `internal/infra/database/client.go`
|
||||
- Support for schema isolation (each service uses its own schema)
|
||||
- Connection pooling configuration per service
|
||||
- Migration runner wrapper
|
||||
- Database health check integration
|
||||
|
||||
### 2. Core Domain Entities (`internal/ent/schema/`)
|
||||
Define core entities:
|
||||
- **User** (`user.go`): ID, email, password_hash, verified, created_at, updated_at
|
||||
- **Role** (`role.go`): ID, name, description, created_at
|
||||
- **Permission** (`permission.go`): ID, name (format: "module.resource.action")
|
||||
- **AuditLog** (`audit_log.go`): ID, actor_id, action, target_id, metadata (JSON), timestamp
|
||||
- **Relationships**:
|
||||
- `role_permissions.go` - Many-to-many between Role and Permission
|
||||
- `user_roles.go` - Many-to-many between User and Role
|
||||
|
||||
### 3. Generated Ent Code
|
||||
- Run `go generate ./internal/ent`
|
||||
- Verify generated code compiles
|
||||
- Type-safe database operations
|
||||
|
||||
### 4. Database Client (`internal/infra/database/client.go`)
|
||||
- `NewEntClient(dsn string) (*ent.Client, error)` function
|
||||
### 2. Database Client Functions
|
||||
- `NewEntClient(dsn string, schema string) (*ent.Client, error)` - supports schema isolation
|
||||
- Connection pooling configuration:
|
||||
- Max connections
|
||||
- Max idle connections
|
||||
- Max connections per service
|
||||
- Max idle connections per service
|
||||
- Connection lifetime
|
||||
- Idle timeout
|
||||
- Per-service connection pool management
|
||||
- Migration runner wrapper
|
||||
- Database health check integration
|
||||
- Graceful connection closing
|
||||
|
||||
### 5. Database Configuration
|
||||
### 3. Database Configuration
|
||||
- Add database config to `config/default.yaml`:
|
||||
- Connection string (DSN)
|
||||
- Connection pool settings
|
||||
- Connection string (DSN) - shared PostgreSQL instance
|
||||
- Connection pool settings per service
|
||||
- Schema isolation configuration
|
||||
- Migration settings
|
||||
- Driver configuration
|
||||
|
||||
### 6. DI Integration
|
||||
- Provider function for database client
|
||||
- Register in DI container
|
||||
- Lifecycle management (close on shutdown)
|
||||
### 4. Database Client Factory
|
||||
- Factory function for creating service-specific database clients
|
||||
- Each service manages its own connection pool
|
||||
- Support for multiple services connecting to same database instance with different schemas
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Install Ent**
|
||||
```bash
|
||||
go get entgo.io/ent/cmd/ent
|
||||
```
|
||||
|
||||
2. **Initialize Ent Schema**
|
||||
```bash
|
||||
go run entgo.io/ent/cmd/ent init User Role Permission AuditLog
|
||||
```
|
||||
|
||||
3. **Define Core Entities**
|
||||
- Create schema files for each entity
|
||||
- Define fields and relationships
|
||||
- Add indexes where needed
|
||||
|
||||
4. **Generate Ent Code**
|
||||
```bash
|
||||
go generate ./internal/ent
|
||||
```
|
||||
|
||||
5. **Create Database Client**
|
||||
1. **Create Database Client Wrapper**
|
||||
- Create `internal/infra/database/client.go`
|
||||
- Implement connection management
|
||||
- Add migration runner
|
||||
- Add health check
|
||||
- Implement `NewEntClient(dsn, schema)` function
|
||||
- Add connection pooling configuration
|
||||
- Add schema isolation support
|
||||
|
||||
6. **Add Configuration**
|
||||
2. **Add Configuration**
|
||||
- Update `config/default.yaml`
|
||||
- Add database configuration section
|
||||
- Add schema isolation settings
|
||||
|
||||
7. **Integrate with DI**
|
||||
- Create provider function
|
||||
- Register in container
|
||||
- Test connection
|
||||
3. **Create Database Client Factory**
|
||||
- Factory function for service-specific clients
|
||||
- Support for per-service connection pools
|
||||
- Migration runner wrapper
|
||||
|
||||
4. **Test Database Client**
|
||||
- Test connection with schema isolation
|
||||
- Test multiple services connecting to same database
|
||||
- Test connection pooling
|
||||
|
||||
## Acceptance Criteria
|
||||
- [x] Ent schema compiles and generates code successfully
|
||||
- [x] Database client connects to PostgreSQL
|
||||
- [x] Core entities can be created and queried
|
||||
- [x] Migrations run successfully on startup
|
||||
- [x] Connection pooling is configured correctly
|
||||
- [x] Database client connects to PostgreSQL with schema support
|
||||
- [x] Connection pooling is configured correctly per service
|
||||
- [x] Database health check works
|
||||
- [x] All entities have proper indexes and relationships
|
||||
- [x] Database client is injectable via DI
|
||||
- [x] Multiple services can connect to same database instance with different schemas
|
||||
- [x] Each service manages its own connection pool
|
||||
- [x] Database client factory works correctly
|
||||
- [x] Schema isolation is supported
|
||||
- [x] Connections are closed gracefully on shutdown
|
||||
|
||||
**Note:** Core domain entities (User, Role, Permission, AuditLog) are implemented in Epic 2 as part of their respective services (Identity, Authz, Audit).
|
||||
|
||||
## Related ADRs
|
||||
- [ADR-0013: Database ORM](../../adr/0013-database-orm.md)
|
||||
|
||||
@@ -132,13 +109,13 @@ go run cmd/platform/main.go
|
||||
```
|
||||
|
||||
## Files to Create/Modify
|
||||
- `internal/ent/schema/user.go` - User entity
|
||||
- `internal/ent/schema/role.go` - Role entity
|
||||
- `internal/ent/schema/permission.go` - Permission entity
|
||||
- `internal/ent/schema/audit_log.go` - AuditLog entity
|
||||
- `internal/ent/schema/role_permissions.go` - Relationship
|
||||
- `internal/ent/schema/user_roles.go` - Relationship
|
||||
- `internal/infra/database/client.go` - Database client
|
||||
- `internal/di/providers.go` - Add database provider
|
||||
- `config/default.yaml` - Add database config
|
||||
- `internal/infra/database/client.go` - Database client wrapper with schema support
|
||||
- `internal/infra/database/factory.go` - Database client factory for services
|
||||
- `config/default.yaml` - Add database config with schema isolation settings
|
||||
|
||||
**Note:** Entity schemas are created in Epic 2:
|
||||
- `services/identity/ent/schema/user.go` - User entity (Identity Service)
|
||||
- `services/authz/ent/schema/role.go` - Role entity (Authz Service)
|
||||
- `services/authz/ent/schema/permission.go` - Permission entity (Authz Service)
|
||||
- `services/audit/ent/schema/audit_log.go` - AuditLog entity (Audit Service)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user