feat: reword phase to epic, update mkdocs

docs/content/stories/epic1/1.2-database-layer.md

@@ -0,0 +1,144 @@
+# Story 1.2: Database Layer with Ent ORM
+
+## Metadata
+- **Story ID**: 1.2
+- **Title**: Database Layer with Ent ORM
+- **Epic**: 1 - Core Kernel & Infrastructure
+- **Status**: Pending
+- **Priority**: High
+- **Estimated Time**: 6-8 hours
+- **Dependencies**: 1.1
+
+## Goal
+Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
+
+## 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.
+
+## Deliverables
+
+### 1. Ent Schema Initialization
+- Initialize Ent schema in `internal/ent/`
+- Set up code generation
+
+### 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
+- Connection pooling configuration:
+  - Max connections
+  - Max idle connections
+  - Connection lifetime
+  - Idle timeout
+- Migration runner wrapper
+- Database health check integration
+- Graceful connection closing
+
+### 5. Database Configuration
+- Add database config to `config/default.yaml`:
+  - Connection string (DSN)
+  - Connection pool settings
+  - Migration settings
+  - Driver configuration
+
+### 6. DI Integration
+- Provider function for database client
+- Register in DI container
+- Lifecycle management (close on shutdown)
+
+## 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**
+   - Create `internal/infra/database/client.go`
+   - Implement connection management
+   - Add migration runner
+   - Add health check
+
+6. **Add Configuration**
+   - Update `config/default.yaml`
+   - Add database configuration section
+
+7. **Integrate with DI**
+   - Create provider function
+   - Register in container
+   - Test connection
+
+## Acceptance Criteria
+- [ ] Ent schema compiles and generates code successfully
+- [ ] Database client connects to PostgreSQL
+- [ ] Core entities can be created and queried
+- [ ] Migrations run successfully on startup
+- [ ] Connection pooling is configured correctly
+- [ ] Database health check works
+- [ ] All entities have proper indexes and relationships
+- [ ] Database client is injectable via DI
+- [ ] Connections are closed gracefully on shutdown
+
+## Related ADRs
+- [ADR-0013: Database ORM](../../adr/0013-database-orm.md)
+
+## Implementation Notes
+- Use Ent for type-safe database operations
+- Configure connection pooling appropriately
+- Run migrations on application startup
+- Add proper indexes for performance
+- Handle database connection errors gracefully
+- Support for database migrations in future epics
+
+## Testing
+```bash
+# Test Ent schema generation
+go generate ./internal/ent
+go build ./internal/ent
+
+# Test database connection
+go test ./internal/infra/database/...
+
+# Test migrations
+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
+