goplt/docs/content/architecture/module-requirements.md

# Module Requirements

This document provides detailed requirements for each module in the Go Platform, including interfaces, responsibilities, and integration points.

## Table of Contents

- [Core Kernel Modules](#core-kernel-modules)
- [Security Modules](#security-modules)
- [Infrastructure Modules](#infrastructure-modules)
- [Feature Modules](#feature-modules)

## Core Kernel Modules

### Configuration Module

**Purpose**: Hierarchical configuration management with support for multiple sources.

**Requirements**:
- Load configuration from YAML files (default, environment-specific)
- Support environment variable overrides
- Support secret manager integration (AWS Secrets Manager, Vault)
- Type-safe configuration access
- Configuration validation

**Interface**:
```go
type ConfigProvider interface {
    Get(key string) any
    Unmarshal(v any) error
    GetString(key string) string
    GetInt(key string) int
    GetBool(key string) bool
    GetStringSlice(key string) []string
    GetDuration(key string) time.Duration
    IsSet(key string) bool
}
```

**Implementation**:
- Uses `github.com/spf13/viper` for configuration loading
- Load order: `default.yaml` → `{env}.yaml` → environment variables → secrets
- Supports nested configuration keys (e.g., `server.port`)

**Configuration Schema**:
```yaml
environment: development
server:
  port: 8080
  host: "0.0.0.0"
  timeout: 30s
database:
  driver: "postgres"
  dsn: ""
  max_connections: 25
  max_idle_connections: 5
logging:
  level: "info"
  format: "json"
  output: "stdout"
cache:
  enabled: true
  ttl: 5m
```

**Dependencies**: None (foundation module)

---

### Logging Module

**Purpose**: Structured logging with support for multiple outputs and log levels.

**Requirements**:
- Structured JSON logging for production
- Human-readable logging for development
- Support for log levels (debug, info, warn, error)
- Request-scoped fields (request_id, user_id, trace_id)
- Contextual logging (with fields)
- Performance: minimal overhead

**Interface**:
```go
type Field interface{}

type Logger interface {
    Debug(msg string, fields ...Field)
    Info(msg string, fields ...Field)
    Warn(msg string, fields ...Field)
    Error(msg string, fields ...Field)
    Fatal(msg string, fields ...Field)
    With(fields ...Field) Logger
}

// Helper functions
func String(key, value string) Field
func Int(key string, value int) Field
func Error(err error) Field
func Duration(key string, value time.Duration) Field
```

**Implementation**:
- Uses `go.uber.org/zap` for high-performance logging
- JSON encoder for production, console encoder for development
- Global logger instance accessible via `pkg/logger`
- Request-scoped logger via context

**Example Usage**:
```go
logger.Info("User logged in",
    logger.String("user_id", userID),
    logger.String("ip", ipAddress),
    logger.Duration("duration", duration),
)
```

**Dependencies**: Configuration Module

---

### Dependency Injection Module

**Purpose**: Service registration and lifecycle management.

**Requirements**:
- Service registration via constructors
- Lifecycle management (OnStart/OnStop hooks)
- Dependency resolution
- Service overrides for testing
- Module-based service composition

**Implementation**:
- Uses `go.uber.org/fx` for dependency injection
- Core services registered in `internal/di/core_module.go`
- Modules register services via `fx.Provide()` in `Init()`
- Lifecycle hooks via `fx.Lifecycle`

**Core Module Structure**:
```go
var CoreModule = fx.Options(
    fx.Provide(ProvideConfig),
    fx.Provide(ProvideLogger),
    fx.Provide(ProvideDatabase),
    fx.Provide(ProvideHealthCheckers),
    fx.Provide(ProvideMetrics),
    fx.Provide(ProvideErrorBus),
    fx.Provide(ProvideEventBus),
    // ... other core services
)
```

**Dependencies**: Configuration Module, Logging Module

---

### Health & Metrics Module

**Purpose**: Health checks and metrics collection.

**Requirements**:
- Liveness endpoint (`/healthz`)
- Readiness endpoint (`/ready`)
- Metrics endpoint (`/metrics`) in Prometheus format
- Composable health checkers
- Custom metrics support

**Interface**:
```go
type HealthChecker interface {
    Check(ctx context.Context) error
}

type HealthRegistry interface {
    Register(name string, checker HealthChecker)
    Check(ctx context.Context) map[string]error
}
```

**Core Health Checkers**:
- Database connectivity
- Redis connectivity
- Kafka connectivity (if enabled)
- Disk space
- Memory usage

**Metrics**:
- HTTP request duration (histogram)
- HTTP request count (counter)
- Database query duration (histogram)
- Cache hit/miss ratio (gauge)
- Error count (counter)

**Dependencies**: Configuration Module, Logging Module

---

### Error Bus Module

**Purpose**: Centralized error handling and reporting.

**Requirements**:
- Non-blocking error publishing
- Multiple error sinks (logger, Sentry)
- Error context preservation
- Panic recovery integration

**Interface**:
```go
type ErrorPublisher interface {
    Publish(err error)
    PublishWithContext(ctx context.Context, err error)
}
```

**Implementation**:
- Channel-based error bus
- Background goroutine consumes errors
- Pluggable sinks (logger, Sentry)
- Context extraction (user_id, trace_id, module)

**Dependencies**: Logging Module

---

## Security Modules

### Authentication Module

**Purpose**: User authentication via JWT tokens.

**Requirements**:
- JWT access token generation (short-lived, 15 minutes)
- JWT refresh token generation (long-lived, 7 days)
- Token validation and verification
- Token claims extraction
- Refresh token storage and revocation

**Interface**:
```go
type Authenticator interface {
    GenerateAccessToken(userID string, roles []string, tenantID string) (string, error)
    GenerateRefreshToken(userID string) (string, error)
    VerifyToken(token string) (*TokenClaims, error)
    RevokeRefreshToken(tokenHash string) error
}

type TokenClaims struct {
    UserID   string
    Roles    []string
    TenantID string
    ExpiresAt time.Time
    IssuedAt time.Time
}
```

**Token Format**:
- Algorithm: HS256 or RS256
- Claims: `sub` (user ID), `roles`, `tenant_id`, `exp`, `iat`
- Refresh tokens stored in database with hash

**Endpoints**:
- `POST /api/v1/auth/login` - Authenticate and get tokens
- `POST /api/v1/auth/refresh` - Refresh access token
- `POST /api/v1/auth/logout` - Revoke refresh token

**Dependencies**: Identity Module, Configuration Module

---

### Authorization Module

**Purpose**: Role-based and attribute-based access control.

**Requirements**:
- Permission-based authorization
- Role-to-permission mapping
- User-to-role assignment
- Permission caching
- Context-aware authorization

**Interface**:
```go
type PermissionResolver interface {
    HasPermission(ctx context.Context, userID string, perm Permission) (bool, error)
    GetUserPermissions(ctx context.Context, userID string) ([]Permission, error)
}

type Authorizer interface {
    Authorize(ctx context.Context, perm Permission) error
}
```

**Permission Format**:
- String format: `"{module}.{resource}.{action}"`
- Examples: `blog.post.create`, `user.read`, `system.health.check`
- Code-generated constants for type safety

**Authorization Flow**:
```mermaid
sequenceDiagram
    participant Request
    participant AuthzMiddleware
    participant Authorizer
    participant PermissionResolver
    participant Cache
    participant DB
    
    Request->>AuthzMiddleware: HTTP request with permission
    AuthzMiddleware->>Authorizer: Authorize(ctx, permission)
    Authorizer->>Authorizer: Extract user from context
    Authorizer->>PermissionResolver: HasPermission(user, permission)
    PermissionResolver->>Cache: Check cache
    Cache-->>PermissionResolver: Cache miss
    PermissionResolver->>DB: Load user roles
    PermissionResolver->>DB: Load role permissions
    DB-->>PermissionResolver: Permissions
    PermissionResolver->>Cache: Store in cache
    PermissionResolver-->>Authorizer: Has permission: true/false
    Authorizer-->>AuthzMiddleware: Authorized or error
    AuthzMiddleware-->>Request: Continue or 403
```

**Dependencies**: Identity Module, Cache Module

---

### Identity Module

**Purpose**: User and role management.

**Requirements**:
- User CRUD operations
- Password hashing (argon2id)
- Email verification
- Password reset flow
- Role management
- Permission management
- User-role assignment

**Interfaces**:
```go
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*User, error)
    FindByEmail(ctx context.Context, email string) (*User, error)
    Create(ctx context.Context, u *User) error
    Update(ctx context.Context, u *User) error
    Delete(ctx context.Context, id string) error
    List(ctx context.Context, filters UserFilters) ([]*User, error)
}

type UserService interface {
    Register(ctx context.Context, email, password string) (*User, error)
    VerifyEmail(ctx context.Context, token string) error
    ResetPassword(ctx context.Context, email string) error
    ChangePassword(ctx context.Context, userID, oldPassword, newPassword string) error
    UpdateProfile(ctx context.Context, userID string, updates UserUpdates) error
}

type RoleRepository interface {
    FindByID(ctx context.Context, id string) (*Role, error)
    Create(ctx context.Context, r *Role) error
    Update(ctx context.Context, r *Role) error
    Delete(ctx context.Context, id string) error
    AssignPermissions(ctx context.Context, roleID string, permissions []Permission) error
    AssignToUser(ctx context.Context, userID string, roleIDs []string) error
}
```

**User Entity**:
- ID (UUID)
- Email (unique, verified)
- Password hash (argon2id)
- Email verified (boolean)
- Created at, updated at
- Tenant ID (optional, for multi-tenancy)

**Role Entity**:
- ID (UUID)
- Name (unique)
- Description
- Created at
- Permissions (many-to-many)

**Dependencies**: Database Module, Notification Module, Cache Module

---

### Audit Module

**Purpose**: Immutable audit logging of security-relevant actions.

**Requirements**:
- Append-only audit log
- Actor tracking (user ID)
- Action tracking (what was done)
- Target tracking (what was affected)
- Metadata storage (JSON)
- Correlation IDs
- High-performance writes

**Interface**:
```go
type Auditor interface {
    Record(ctx context.Context, action AuditAction) error
    Query(ctx context.Context, filters AuditFilters) ([]AuditEntry, error)
}

type AuditAction struct {
    ActorID  string
    Action   string  // e.g., "user.created", "role.assigned"
    TargetID string
    Metadata map[string]any
    IPAddress string
    UserAgent string
}
```

**Audit Log Schema**:
- ID (UUID)
- Actor ID (user ID)
- Action (string)
- Target ID (resource ID)
- Metadata (JSONB)
- Timestamp
- Request ID
- IP Address
- User Agent

**Automatic Audit Events**:
- User login/logout
- Password changes
- Role assignments
- Permission grants
- Data modifications (configurable)

**Dependencies**: Database Module, Logging Module

---

## Infrastructure Modules

### Database Module

**Purpose**: Database access and ORM functionality.

**Requirements**:
- PostgreSQL support (primary)
- Connection pooling
- Transaction support
- Migration management
- Query instrumentation (OpenTelemetry)
- Multi-tenancy support (tenant_id filtering)

**Implementation**:
- Uses `entgo.io/ent` for code generation
- Ent schemas for all entities
- Migration runner on startup
- Connection pool configuration

**Database Client Interface**:
```go
type DatabaseClient interface {
    Client() *ent.Client
    Migrate(ctx context.Context) error
    Close() error
    HealthCheck(ctx context.Context) error
}
```

**Connection Pooling**:
- Max connections: 25
- Max idle connections: 5
- Connection lifetime: 5 minutes
- Idle timeout: 10 minutes

**Multi-Tenancy**:
- Automatic tenant_id filtering via Ent interceptors
- Tenant-aware queries
- Tenant isolation at application level

**Dependencies**: Configuration Module, Logging Module

---

### Cache Module

**Purpose**: Distributed caching with Redis.

**Requirements**:
- Key-value storage
- TTL support
- Distributed caching (shared across instances)
- Cache invalidation
- Fallback to in-memory cache

**Interface**:
```go
type Cache interface {
    Get(ctx context.Context, key string) ([]byte, error)
    Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
    Delete(ctx context.Context, key string) error
    Exists(ctx context.Context, key string) (bool, error)
    Increment(ctx context.Context, key string) (int64, error)
}
```

**Use Cases**:
- User permissions caching
- Role assignments caching
- Session data
- Rate limiting state
- Query result caching (optional)

**Cache Key Format**:
- `user:{user_id}:permissions`
- `role:{role_id}:permissions`
- `session:{session_id}`
- `ratelimit:{user_id}:{endpoint}`

**Dependencies**: Configuration Module, Logging Module

---

### Event Bus Module

**Purpose**: Event-driven communication between modules.

**Requirements**:
- Publish/subscribe pattern
- Topic-based routing
- In-process bus (development)
- Kafka bus (production)
- Error handling and retries
- Event ordering (per partition)

**Interface**:
```go
type EventBus interface {
    Publish(ctx context.Context, topic string, event Event) error
    Subscribe(topic string, handler EventHandler) error
    Unsubscribe(topic string) error
}

type Event struct {
    ID        string
    Type      string
    Source    string
    Timestamp time.Time
    Data      map[string]any
}

type EventHandler func(ctx context.Context, event Event) error
```

**Core Events**:
- `platform.user.created`
- `platform.user.updated`
- `platform.user.deleted`
- `platform.role.assigned`
- `platform.role.revoked`
- `platform.permission.granted`

**Event Flow**:
```mermaid
graph LR
    Publisher[Module Publisher]
    Bus[Event Bus]
    Subscriber1[Module Subscriber 1]
    Subscriber2[Module Subscriber 2]
    Subscriber3[Module Subscriber 3]
    
    Publisher -->|Publish| Bus
    Bus -->|Deliver| Subscriber1
    Bus -->|Deliver| Subscriber2
    Bus -->|Deliver| Subscriber3
```

**Dependencies**: Configuration Module, Logging Module

---

### Scheduler Module

**Purpose**: Background job processing and cron scheduling.

**Requirements**:
- Cron job scheduling
- Async job queuing
- Job retries with backoff
- Job status tracking
- Concurrency control
- Job persistence

**Interface**:
```go
type Scheduler interface {
    Cron(spec string, job JobFunc) error
    Enqueue(queue string, payload any) error
    EnqueueWithRetry(queue string, payload any, retries int) error
}

type JobFunc func(ctx context.Context) error
```

**Implementation**:
- Uses `github.com/robfig/cron/v3` for cron jobs
- Uses `github.com/hibiken/asynq` for job queuing
- Redis-backed job queue
- Job processor with worker pool

**Example Jobs**:
- Cleanup expired tokens (daily)
- Send digest emails (weekly)
- Generate reports (monthly)
- Data archival (custom schedule)

**Dependencies**: Cache Module (Redis), Logging Module

---

### Blob Storage Module

**Purpose**: File and blob storage abstraction.

**Requirements**:
- File upload
- File download
- File deletion
- Signed URL generation
- Versioning support (optional)

**Interface**:
```go
type BlobStore interface {
    Upload(ctx context.Context, key string, data []byte, contentType string) error
    Download(ctx context.Context, key string) ([]byte, error)
    Delete(ctx context.Context, key string) error
    GetSignedURL(ctx context.Context, key string, ttl time.Duration) (string, error)
    Exists(ctx context.Context, key string) (bool, error)
}
```

**Implementation**:
- AWS S3 adapter (primary)
- Local file system adapter (development)
- GCS adapter (optional)

**Key Format**:
- `{module}/{resource_type}/{resource_id}/{filename}`
- Example: `blog/posts/abc123/image.jpg`

**Dependencies**: Configuration Module, Logging Module

---

### Notification Module

**Purpose**: Multi-channel notifications (email, SMS, push).

**Requirements**:
- Email sending (SMTP, AWS SES)
- SMS sending (Twilio, optional)
- Push notifications (FCM, APNs, optional)
- Webhook notifications
- Template support
- Retry logic

**Interface**:
```go
type Notifier interface {
    SendEmail(ctx context.Context, to, subject, body string) error
    SendEmailWithTemplate(ctx context.Context, to, template string, data map[string]any) error
    SendSMS(ctx context.Context, to, message string) error
    SendPush(ctx context.Context, deviceToken string, payload PushPayload) error
    SendWebhook(ctx context.Context, url string, payload map[string]any) error
}
```

**Email Templates**:
- Email verification
- Password reset
- Welcome email
- Notification digest

**Dependencies**: Configuration Module, Logging Module, Event Bus Module

---

## Feature Modules

### Blog Module (Example)

**Purpose**: Blog post management functionality.

**Requirements**:
- Post CRUD operations
- Comment system (optional)
- Author-based access control
- Post publishing workflow
- Tag/category support

**Permissions**:
- `blog.post.create`
- `blog.post.read`
- `blog.post.update`
- `blog.post.delete`
- `blog.post.publish`

**Routes**:
- `POST /api/v1/blog/posts` - Create post
- `GET /api/v1/blog/posts` - List posts
- `GET /api/v1/blog/posts/:id` - Get post
- `PUT /api/v1/blog/posts/:id` - Update post
- `DELETE /api/v1/blog/posts/:id` - Delete post

**Domain Model**:
```go
type Post struct {
    ID        string
    Title     string
    Content   string
    AuthorID  string
    Status    PostStatus  // draft, published, archived
    CreatedAt time.Time
    UpdatedAt time.Time
    PublishedAt *time.Time
}
```

**Events Published**:
- `blog.post.created`
- `blog.post.updated`
- `blog.post.published`
- `blog.post.deleted`

**Dependencies**: Core Kernel, Identity Module, Event Bus Module

---

## Module Integration Matrix

```mermaid
graph TB
    subgraph "Core Kernel (Required)"
        Config[Config]
        Logger[Logger]
        DI[DI Container]
        Health[Health]
    end
    
    subgraph "Security (Required)"
        Auth[Auth]
        Authz[Authz]
        Identity[Identity]
        Audit[Audit]
    end
    
    subgraph "Infrastructure (Optional)"
        DB[Database]
        Cache[Cache]
        EventBus[Event Bus]
        Scheduler[Scheduler]
        BlobStore[Blob Store]
        Notifier[Notifier]
    end
    
    subgraph "Feature Modules"
        Blog[Blog]
        Billing[Billing]
        Custom[Custom Modules]
    end
    
    Config --> Logger
    Config --> DI
    DI --> Health
    DI --> Auth
    DI --> Authz
    DI --> Identity
    DI --> Audit
    DI --> DB
    DI --> Cache
    DI --> EventBus
    DI --> Scheduler
    DI --> BlobStore
    DI --> Notifier
    
    Auth --> Identity
    Authz --> Identity
    Authz --> Audit
    
    Blog --> Auth
    Blog --> Authz
    Blog --> DB
    Blog --> EventBus
    Blog --> Cache
    
    Billing --> Auth
    Billing --> Authz
    Billing --> DB
    Billing --> EventBus
    Billing --> Cache
    
    Custom --> Auth
    Custom --> Authz
    Custom --> DB
    
    style Config fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
    style Auth fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
    style Blog fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
```

## Next Steps

- [Component Relationships](./component-relationships.md) - Detailed component interactions
- [System Architecture](./architecture.md) - Overall system architecture
- [Module Architecture](./architecture-modules.md) - Module design and integration