Files

0x1d 66b0c3b40d docs: update dead links

2025-11-05 11:00:36 +01:00

19 KiB

Raw Blame History

Module Requirements

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

Core Kernel Modules
Security Modules
Infrastructure 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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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 - Detailed component interactions
System Architecture - Overall system architecture
Module Architecture - Module design and integration

19 KiB Raw Blame History

Module Requirements

Table of Contents

Core Kernel Modules

Configuration Module

Logging Module

Dependency Injection Module

Health & Metrics Module

Error Bus Module

Security Modules

Authentication Module

Authorization Module

Identity Module

Audit Module

Infrastructure Modules

Database Module

Cache Module

Event Bus Module

Scheduler Module

Blob Storage Module

Notification Module

Feature Modules

Blog Module (Example)

Module Integration Matrix

Next Steps

19 KiB

Raw Blame History