docs: add mkdocs, update links, add architecture documentation

.dockerignore

@@ -0,0 +1,14 @@
+# Docker ignore file for MkDocs build
+site/
+.mkdocs_cache/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+venv/
+env/
+ENV/
+.git/
+.gitignore
+

.gitignore

@@ -0,0 +1,24 @@
+# MkDocs build output
+docs/site/
+docs/.mkdocs_cache/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+
+# Go (if not already present)
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+go.work
+

Makefile

@@ -0,0 +1,106 @@
+.PHONY: help docs-install docs-serve docs-build docs-deploy docs-clean docs-validate
+.PHONY: docs-docker-build docs-docker-serve docs-docker-build-site docs-docker-clean docs-docker-compose-up docs-docker-compose-down
+
+# Default target
+help:
+	@echo "Available targets:"
+	@echo ""
+	@echo "Local commands (require Python/pip):"
+	@echo "  make docs-install    - Install MkDocs dependencies"
+	@echo "  make docs-serve      - Serve documentation locally (http://127.0.0.1:8000)"
+	@echo "  make docs-build      - Build static documentation site"
+	@echo "  make docs-deploy     - Deploy documentation to GitHub Pages"
+	@echo "  make docs-clean      - Clean build artifacts"
+	@echo "  make docs-validate   - Validate MkDocs configuration"
+	@echo ""
+	@echo "Docker commands (no Python installation required):"
+	@echo "  make docs-docker-build        - Build Docker image for MkDocs"
+	@echo "  make docs-docker-serve        - Serve documentation using Docker"
+	@echo "  make docs-docker-build-site   - Build static site in Docker container"
+	@echo "  make docs-docker-clean        - Clean Docker images and containers"
+	@echo "  make docs-docker-compose-up   - Start docs server with docker-compose"
+	@echo "  make docs-docker-compose-down - Stop docs server with docker-compose"
+	@echo ""
+	@echo "Documentation shortcuts:"
+	@echo "  make docs            - Alias for docs-serve"
+	@echo "  make build-docs      - Alias for docs-build"
+	@echo "  make docs-docker     - Alias for docs-docker-serve"
+
+# Install MkDocs and dependencies
+docs-install:
+	@echo "Installing MkDocs dependencies..."
+	cd docs && pip install -r requirements.txt
+
+# Serve documentation locally with auto-reload
+docs-serve:
+	@echo "Starting MkDocs development server..."
+	@echo "Documentation will be available at http://127.0.0.1:8000"
+	cd docs && mkdocs serve
+
+# Build static documentation site
+docs-build:
+	@echo "Building static documentation site..."
+	cd docs && mkdocs build
+	@echo "Build complete! Output is in the 'docs/site/' directory"
+
+# Deploy documentation to GitHub Pages
+docs-deploy:
+	@echo "Deploying documentation to GitHub Pages..."
+	cd docs && mkdocs gh-deploy
+
+# Clean build artifacts
+docs-clean:
+	@echo "Cleaning MkDocs build artifacts..."
+	rm -rf docs/site/
+	rm -rf docs/.mkdocs_cache/
+	@echo "Clean complete!"
+
+# Validate MkDocs configuration
+docs-validate:
+	@echo "Validating MkDocs configuration..."
+	cd docs && mkdocs build --strict
+	@echo "Configuration is valid!"
+
+# Docker commands
+docs-docker-build:
+	@echo "Building Docker image for MkDocs..."
+	cd docs && docker build -f Dockerfile -t goplt-docs:latest .
+
+docs-docker-serve: docs-docker-build
+	@echo "Starting MkDocs development server in Docker..."
+	@echo "Documentation will be available at http://127.0.0.1:8000"
+	cd docs && docker run --rm -it \
+		-p 8000:8000 \
+		-v "$$(pwd):/docs:ro" \
+		goplt-docs:latest
+
+docs-docker-build-site: docs-docker-build
+	@echo "Building static documentation site in Docker..."
+	cd docs && docker run --rm \
+		-v "$$(pwd):/docs:ro" \
+		-v "$$(pwd)/site:/docs/site" \
+		goplt-docs:latest mkdocs build
+	@echo "Build complete! Output is in the 'docs/site/' directory"
+
+docs-docker-clean:
+	@echo "Cleaning Docker images and containers..."
+	-docker stop goplt-docs 2>/dev/null || true
+	-docker rm goplt-docs 2>/dev/null || true
+	-docker rmi goplt-docs:latest 2>/dev/null || true
+	@echo "Clean complete!"
+
+docs-docker-compose-up:
+	@echo "Starting MkDocs server with docker-compose..."
+	@echo "Documentation will be available at http://127.0.0.1:8000"
+	cd docs && docker-compose -f docker-compose.yml up --build
+
+docs-docker-compose-down:
+	@echo "Stopping MkDocs server..."
+	cd docs && docker-compose -f docker-compose.yml down
+
+# Convenience aliases
+docs: docs-serve
+build-docs: docs-build
+clean-docs: docs-clean
+docs-docker: docs-docker-serve
+

docs/.dockerignore

@@ -0,0 +1,14 @@
+# Docker ignore file for MkDocs build
+site/
+.mkdocs_cache/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+venv/
+env/
+ENV/
+.git/
+.gitignore
+

docs/Dockerfile

@@ -0,0 +1,26 @@
+# Dockerfile for MkDocs documentation
+FROM python:3.11-slim
+
+WORKDIR /docs
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy all documentation files
+COPY . .
+
+# Expose MkDocs default port
+EXPOSE 8000
+
+# Default command: serve documentation
+CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]
+

docs/MKDOCS_README.md

@@ -0,0 +1,163 @@
+# MkDocs Setup
+
+This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) for documentation.
+
+All documentation tooling files are self-contained in the `docs/` directory.
+
+## Prerequisites
+
+You can run MkDocs in two ways:
+
+**Option 1: Local Python Installation**
+- Python 3.8 or higher
+- pip (Python package manager)
+
+**Option 2: Docker (Recommended - No Python installation needed)**
+- Docker and Docker Compose
+
+## Installation
+
+1. Install the required Python packages:
+
+```bash
+cd docs
+pip install -r requirements.txt
+```
+
+Or if you prefer using a virtual environment:
+
+```bash
+cd docs
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+## Usage
+
+You can use either the Makefile commands from the project root (recommended) or run MkDocs directly from the `docs/` directory.
+
+### Using Makefile (Recommended)
+
+From the project root, use the Makefile commands:
+
+```bash
+# Using Docker (easiest, no Python needed)
+make docs-docker-compose-up
+# or
+make docs-docker
+
+# Using local Python
+make docs-install    # Install dependencies
+make docs-serve      # Serve documentation
+make docs-build    # Build static site
+make docs-deploy    # Deploy to GitHub Pages
+
+# Show all available commands
+make help
+```
+
+The documentation will be available at `http://127.0.0.1:8000` with live reload enabled.
+
+### Using Docker Directly
+
+From the `docs/` directory:
+
+```bash
+cd docs
+
+# Using docker-compose (easiest)
+docker-compose up --build
+
+# Using Docker directly
+docker build -t goplt-docs:latest .
+docker run --rm -it -p 8000:8000 -v "$(pwd):/docs:ro" goplt-docs:latest
+
+# Build static site
+docker run --rm -v "$(pwd):/docs:ro" -v "$(pwd)/site:/docs/site" goplt-docs:latest mkdocs build
+```
+
+### Using MkDocs Directly
+
+From the `docs/` directory:
+
+```bash
+cd docs
+
+# Serve documentation locally with auto-reload
+mkdocs serve
+
+# Build static site
+mkdocs build
+
+# Deploy to GitHub Pages
+mkdocs gh-deploy
+```
+
+## Configuration
+
+The main configuration file is `docs/mkdocs.yml`. Key settings:
+
+- **Site name and metadata**: Configured at the top
+- **Theme**: Material theme with light/dark mode support
+- **Navigation**: Defined in the `nav` section
+- **Plugins**: Search and git revision date plugins enabled
+- **Markdown extensions**: Various extensions for code highlighting, tables, etc.
+- **docs_dir**: Set to "content" - markdown files are in the content/ subdirectory
+
+## Project Structure
+
+```
+goplt/
+├── docs/                    # Documentation directory (self-contained)
+│   ├── mkdocs.yml          # MkDocs configuration
+│   ├── requirements.txt    # Python dependencies
+│   ├── Dockerfile          # Docker image for MkDocs
+│   ├── docker-compose.yml  # Docker Compose configuration
+│   ├── .dockerignore       # Docker ignore patterns
+│   ├── MKDOCS_README.md    # This file
+│   ├── content/           # Documentation content (markdown files)
+│   │   ├── index.md       # Home page
+│   │   ├── requirements.md # Requirements document
+│   │   ├── plan.md        # Implementation plan
+│   │   ├── playbook.md    # Implementation playbook
+│   │   ├── adr/           # Architecture Decision Records
+│   │   └── stories/       # Implementation tasks
+│   └── site/              # Generated site (gitignored)
+└── Makefile               # Makefile with docs commands (runs from root)
+```
+
+## Adding New Documentation
+
+1. Add markdown files to the `docs/content/` directory
+2. Update `docs/mkdocs.yml` to add entries to the `nav` section
+3. Run `make docs-serve` or `make docs-docker` from project root to preview changes
+
+## Customization
+
+### Theme Colors
+
+Edit the `theme.palette` section in `docs/mkdocs.yml` to change colors.
+
+### Navigation
+
+Update the `nav` section in `docs/mkdocs.yml` to reorganize or add new pages.
+
+### Plugins
+
+Add or remove plugins in the `plugins` section of `docs/mkdocs.yml`.
+
+## Troubleshooting
+
+- **Import errors**: Make sure all dependencies are installed: `cd docs && pip install -r requirements.txt`
+- **Navigation issues**: Check that file paths in `docs/mkdocs.yml` match actual file locations
+- **Build errors**: Run `mkdocs build --verbose` from the `docs/` directory for detailed error messages
+- **Docker issues**: Make sure Docker is running and you have permissions to run containers
+
+## Benefits of Self-Contained Docs
+
+- All documentation tooling is in one place
+- Easy to share or move the docs directory
+- Doesn't pollute the project root
+- Can be versioned or deployed independently
+

docs/content/architecture-modules.md

@@ -0,0 +1,561 @@
+# Module Architecture
+
+This document details the architecture of modules, how they are structured, how they interact with the core platform, and how multiple modules work together.
+
+## Table of Contents
+
+- [Module Structure](#module-structure)
+- [Module Interface](#module-interface)
+- [Module Lifecycle](#module-lifecycle)
+- [Module Dependencies](#module-dependencies)
+- [Module Communication](#module-communication)
+- [Module Data Isolation](#module-data-isolation)
+- [Module Examples](#module-examples)
+
+## Module Structure
+
+Every module follows a consistent structure that separates concerns and enables clean integration with the platform.
+
+```mermaid
+graph TD
+    subgraph "Module Structure"
+        Manifest[module.yaml<br/>Manifest]
+        
+        subgraph "Public API (pkg/)"
+            ModuleInterface[IModule Interface]
+            ModuleTypes[Public Types]
+        end
+        
+        subgraph "Internal Implementation (internal/)"
+            API[API Handlers]
+            Service[Domain Services]
+            Repo[Repositories]
+            Domain[Domain Models]
+        end
+        
+        subgraph "Database Schema"
+            EntSchema[Ent Schemas]
+            Migrations[Migrations]
+        end
+    end
+    
+    Manifest --> ModuleInterface
+    ModuleInterface --> API
+    API --> Service
+    Service --> Repo
+    Repo --> Domain
+    Repo --> EntSchema
+    EntSchema --> Migrations
+    
+    style Manifest fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style ModuleInterface fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style Service fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+### Module Directory Structure
+
+```
+modules/blog/
+├── go.mod                    # Module dependencies
+├── module.yaml               # Module manifest
+├── pkg/
+│   └── module.go            # IModule implementation
+├── internal/
+│   ├── api/
+│   │   └── handler.go       # HTTP handlers
+│   ├── domain/
+│   │   ├── post.go          # Domain entities
+│   │   └── post_repo.go     # Repository interface
+│   ├── service/
+│   │   └── post_service.go  # Business logic
+│   └── ent/
+│       ├── schema/
+│       │   └── post.go      # Ent schema
+│       └── migrate/         # Migrations
+└── tests/
+    └── integration_test.go
+```
+
+## Module Interface
+
+All modules must implement the `IModule` interface to integrate with the platform.
+
+```mermaid
+classDiagram
+    class IModule {
+        <<interface>>
+        +Name() string
+        +Version() string
+        +Dependencies() []string
+        +Init() fx.Option
+        +Migrations() []MigrationFunc
+        +OnStart(ctx) error
+        +OnStop(ctx) error
+    }
+    
+    class BlogModule {
+        +Name() string
+        +Version() string
+        +Dependencies() []string
+        +Init() fx.Option
+        +Migrations() []MigrationFunc
+    }
+    
+    class BillingModule {
+        +Name() string
+        +Version() string
+        +Dependencies() []string
+        +Init() fx.Option
+        +Migrations() []MigrationFunc
+    }
+    
+    IModule <|.. BlogModule
+    IModule <|.. BillingModule
+```
+
+### IModule Interface
+
+```go
+type IModule interface {
+    // Name returns a unique, human-readable identifier
+    Name() string
+    
+    // Version returns the module version (semantic versioning)
+    Version() string
+    
+    // Dependencies returns list of required modules (e.g., ["core >= 1.0.0"])
+    Dependencies() []string
+    
+    // Init returns fx.Option that registers all module services
+    Init() fx.Option
+    
+    // Migrations returns database migration functions
+    Migrations() []func(*ent.Client) error
+    
+    // OnStart is called during application startup (optional)
+    OnStart(ctx context.Context) error
+    
+    // OnStop is called during graceful shutdown (optional)
+    OnStop(ctx context.Context) error
+}
+```
+
+## Module Lifecycle
+
+Modules go through a well-defined lifecycle from discovery to shutdown.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Discovered: Module found
+    Discovered --> Validated: Check dependencies
+    Validated --> Loaded: Load module
+    Loaded --> Initialized: Call Init()
+    Initialized --> Migrated: Run migrations
+    Migrated --> Started: Call OnStart()
+    Started --> Running: Module active
+    Running --> Stopping: Shutdown signal
+    Stopping --> Stopped: Call OnStop()
+    Stopped --> [*]
+    
+    Validated --> Rejected: Dependency check fails
+    Rejected --> [*]
+```
+
+### Module Initialization Sequence
+
+```mermaid
+sequenceDiagram
+    participant Main
+    participant Loader
+    participant Registry
+    participant Module
+    participant DI
+    participant Router
+    participant DB
+    participant Scheduler
+    
+    Main->>Loader: DiscoverModules()
+    Loader->>Registry: Scan for modules
+    Registry-->>Loader: Module list
+    
+    loop For each module
+        Loader->>Module: Load module
+        Module->>Registry: Register module
+        Registry->>Registry: Validate dependencies
+    end
+    
+    Main->>Registry: GetAllModules()
+    Registry->>Registry: Resolve dependencies (topological sort)
+    Registry-->>Main: Ordered module list
+    
+    Main->>DI: Create fx container
+    
+    loop For each module (in dependency order)
+        Main->>Module: Init()
+        Module->>DI: fx.Provide(services)
+        Module->>Router: Register routes
+        Module->>Scheduler: Register jobs
+        Module->>DB: Register migrations
+    end
+    
+    Main->>DB: Run migrations (core first)
+    Main->>DI: Start container
+    Main->>Module: OnStart() (optional)
+    Main->>Router: Start HTTP server
+```
+
+## Module Dependencies
+
+Modules can depend on other modules, creating a dependency graph that must be resolved.
+
+```mermaid
+graph TD
+    Core[Core Kernel]
+    Blog[Blog Module]
+    Billing[Billing Module]
+    Analytics[Analytics Module]
+    Notifications[Notification Module]
+    
+    Blog --> Core
+    Billing --> Core
+    Analytics --> Core
+    Notifications --> Core
+    
+    Analytics --> Blog
+    Analytics --> Billing
+    Billing --> Blog
+    Notifications --> Blog
+    Notifications --> Billing
+    
+    style Core fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Blog fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style Billing fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+### Dependency Resolution
+
+```mermaid
+graph LR
+    subgraph "Module Dependency Graph"
+        M1[Module A<br/>depends on: Core]
+        M2[Module B<br/>depends on: Core, Module A]
+        M3[Module C<br/>depends on: Core, Module B]
+        Core[Core Kernel]
+    end
+    
+    subgraph "Resolved Load Order"
+        Step1[1. Core Kernel]
+        Step2[2. Module A]
+        Step3[3. Module B]
+        Step4[4. Module C]
+    end
+    
+    Core --> M1
+    M1 --> M2
+    M2 --> M3
+    
+    Step1 --> Step2
+    Step2 --> Step3
+    Step3 --> Step4
+    
+    style Core fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Step1 fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+```
+
+## Module Communication
+
+Modules communicate through well-defined interfaces provided by the core platform.
+
+### Communication Patterns
+
+```mermaid
+graph TB
+    subgraph "Communication Patterns"
+        Direct[Direct Service Calls<br/>via DI]
+        Events[Event Bus<br/>Publish/Subscribe]
+        Shared[Shared Interfaces<br/>Core Services]
+    end
+    
+    subgraph "Module A"
+        AService[Service A]
+        AHandler[Handler A]
+    end
+    
+    subgraph "Core Services"
+        EventBus[Event Bus]
+        AuthService[Auth Service]
+        CacheService[Cache Service]
+    end
+    
+    subgraph "Module B"
+        BService[Service B]
+        BHandler[Handler B]
+    end
+    
+    AHandler --> AService
+    AService --> AuthService
+    AService --> CacheService
+    AService -->|Publish| EventBus
+    EventBus -->|Subscribe| BService
+    BService --> AuthService
+    BHandler --> BService
+    
+    style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style AService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style BService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+### Event-Driven Communication
+
+```mermaid
+sequenceDiagram
+    participant BlogModule
+    participant EventBus
+    participant AnalyticsModule
+    participant NotificationModule
+    participant AuditModule
+    
+    BlogModule->>EventBus: Publish("blog.post.created", event)
+    EventBus->>AnalyticsModule: Deliver event
+    EventBus->>NotificationModule: Deliver event
+    EventBus->>AuditModule: Deliver event
+    
+    AnalyticsModule->>AnalyticsModule: Track post creation
+    NotificationModule->>NotificationModule: Send notification
+    AuditModule->>AuditModule: Log audit entry
+```
+
+## Module Data Isolation
+
+Modules can have their own database tables while sharing core tables.
+
+```mermaid
+erDiagram
+    USERS ||--o{ USER_ROLES : has
+    ROLES ||--o{ USER_ROLES : assigned_to
+    ROLES ||--o{ ROLE_PERMISSIONS : has
+    PERMISSIONS ||--o{ ROLE_PERMISSIONS : assigned_to
+    
+    BLOG_POSTS {
+        string id PK
+        string author_id FK
+        string title
+        string content
+        timestamp created_at
+    }
+    
+    BILLING_SUBSCRIPTIONS {
+        string id PK
+        string user_id FK
+        string plan
+        timestamp expires_at
+    }
+    
+    USERS ||--o{ BLOG_POSTS : creates
+    USERS ||--o{ BILLING_SUBSCRIPTIONS : subscribes
+    
+    AUDIT_LOGS {
+        string id PK
+        string actor_id
+        string action
+        string target_id
+        jsonb metadata
+    }
+    
+    USERS ||--o{ AUDIT_LOGS : performs
+```
+
+### Multi-Tenancy Data Isolation
+
+```mermaid
+graph TB
+    subgraph "Single Database"
+        subgraph "Core Tables"
+            Users[users<br/>tenant_id]
+            Roles[roles<br/>tenant_id]
+        end
+        
+        subgraph "Blog Module Tables"
+            Posts[blog_posts<br/>tenant_id]
+            Comments[blog_comments<br/>tenant_id]
+        end
+        
+        subgraph "Billing Module Tables"
+            Subscriptions[billing_subscriptions<br/>tenant_id]
+            Invoices[billing_invoices<br/>tenant_id]
+        end
+    end
+    
+    subgraph "Query Filtering"
+        EntInterceptor[Ent Interceptor]
+        TenantFilter[WHERE tenant_id = ?]
+    end
+    
+    Users --> EntInterceptor
+    Posts --> EntInterceptor
+    Subscriptions --> EntInterceptor
+    EntInterceptor --> TenantFilter
+    
+    style EntInterceptor fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+```
+
+## Module Examples
+
+### Example: Blog Module
+
+```mermaid
+graph TB
+    subgraph "Blog Module"
+        BlogHandler[Blog Handler<br/>/api/v1/blog/posts]
+        BlogService[Post Service]
+        PostRepo[Post Repository]
+        PostEntity[Post Entity]
+    end
+    
+    subgraph "Core Services Used"
+        AuthService[Auth Service]
+        AuthzService[Authorization Service]
+        EventBus[Event Bus]
+        AuditService[Audit Service]
+        CacheService[Cache Service]
+    end
+    
+    subgraph "Database"
+        PostsTable[(blog_posts)]
+    end
+    
+    BlogHandler --> AuthService
+    BlogHandler --> AuthzService
+    BlogHandler --> BlogService
+    
+    BlogService --> PostRepo
+    BlogService --> EventBus
+    BlogService --> AuditService
+    BlogService --> CacheService
+    
+    PostRepo --> PostsTable
+    PostRepo --> PostEntity
+    
+    style BlogModule fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style AuthService fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+```
+
+### Module Integration Example
+
+```mermaid
+graph LR
+    subgraph "Request Flow"
+        Request[HTTP Request<br/>POST /api/v1/blog/posts]
+        Auth[Auth Middleware]
+        Authz[Authz Middleware]
+        Handler[Blog Handler]
+        Service[Blog Service]
+        Repo[Blog Repository]
+        DB[(Database)]
+    end
+    
+    subgraph "Side Effects"
+        EventBus[Event Bus]
+        Audit[Audit Log]
+        Cache[Cache]
+    end
+    
+    Request --> Auth
+    Auth --> Authz
+    Authz --> Handler
+    Handler --> Service
+    Service --> Repo
+    Repo --> DB
+    
+    Service --> EventBus
+    Service --> Audit
+    Service --> Cache
+    
+    style Request fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style Service fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+## Module Registration Flow
+
+```mermaid
+flowchart TD
+    Start([Application Start]) --> LoadManifests["Load module.yaml files"]
+    LoadManifests --> ValidateDeps["Validate dependencies"]
+    ValidateDeps -->|Valid| SortModules["Topological sort modules"]
+    ValidateDeps -->|Invalid| Error([Error: Missing dependencies])
+    
+    SortModules --> CreateDI["Create DI container"]
+    CreateDI --> RegisterCore["Register core services"]
+    
+    RegisterCore --> LoopModules{"More modules?"}
+    LoopModules -->|Yes| LoadModule["Load module"]
+    LoadModule --> CallInit["Call module.Init()"]
+    CallInit --> RegisterServices["Register module services"]
+    RegisterServices --> RegisterRoutes["Register module routes"]
+    RegisterRoutes --> RegisterJobs["Register module jobs"]
+    RegisterJobs --> RegisterMigrations["Register module migrations"]
+    RegisterMigrations --> LoopModules
+    
+    LoopModules -->|No| RunMigrations["Run all migrations"]
+    RunMigrations --> StartModules["Call OnStart() for each module"]
+    StartModules --> StartServer["Start HTTP server"]
+    StartServer --> Running([Application Running])
+    
+    Running --> Shutdown([Shutdown Signal])
+    Shutdown --> StopServer["Stop HTTP server"]
+    StopServer --> StopModules["Call OnStop() for each module"]
+    StopModules --> Cleanup["Cleanup resources"]
+    Cleanup --> End([Application Stopped])
+    
+    style Start fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style Running fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style Error fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+```
+
+## Module Permissions Integration
+
+Modules declare permissions that are automatically integrated into the permission system.
+
+```mermaid
+graph TB
+    subgraph "Permission Generation"
+        Manifest["module.yaml<br/>permissions: array"]
+        Generator["Permission Generator"]
+        GeneratedCode["pkg/perm/generated.go"]
+    end
+    
+    subgraph "Permission Resolution"
+        Request["HTTP Request"]
+        AuthzMiddleware["Authz Middleware"]
+        PermissionResolver["Permission Resolver"]
+        UserRoles["User Roles"]
+        RolePermissions["Role Permissions"]
+        Response["HTTP Response"]
+    end
+    
+    Manifest --> Generator
+    Generator --> GeneratedCode
+    GeneratedCode --> PermissionResolver
+    
+    Request --> AuthzMiddleware
+    AuthzMiddleware --> PermissionResolver
+    PermissionResolver --> UserRoles
+    PermissionResolver --> RolePermissions
+    UserRoles --> PermissionResolver
+    RolePermissions --> PermissionResolver
+    PermissionResolver --> AuthzMiddleware
+    AuthzMiddleware --> Response
+    
+    classDef generation fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    classDef resolution fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    
+    class Manifest,Generator,GeneratedCode generation
+    class PermissionResolver resolution
+```
+
+## Next Steps
+
+- [Module Requirements](./module-requirements.md) - Detailed requirements for each module
+- [Component Relationships](./component-relationships.md) - How components interact
+- [System Architecture](./architecture.md) - Overall system architecture
+

docs/content/architecture.md

@@ -0,0 +1,590 @@
+# System Architecture
+
+This document provides a comprehensive overview of the Go Platform architecture, including system components, their relationships, and how modules integrate with the core platform.
+
+## Table of Contents
+
+- [High-Level Architecture](#high-level-architecture)
+- [Layered Architecture](#layered-architecture)
+- [Module System Architecture](#module-system-architecture)
+- [Component Relationships](#component-relationships)
+- [Data Flow](#data-flow)
+- [Deployment Architecture](#deployment-architecture)
+
+## High-Level Architecture
+
+The Go Platform follows a **modular monolith** architecture that can evolve into microservices. The platform consists of a core kernel and pluggable feature modules.
+
+```mermaid
+graph TB
+    subgraph "Go Platform"
+        Core[Core Kernel]
+        Module1[Module 1<br/>Blog]
+        Module2[Module 2<br/>Billing]
+        Module3[Module N<br/>Custom]
+    end
+    
+    subgraph "Infrastructure"
+        DB[(PostgreSQL)]
+        Cache[(Redis)]
+        Queue[Kafka/Event Bus]
+        Storage[S3/Blob Storage]
+    end
+    
+    subgraph "External Services"
+        OIDC[OIDC Provider]
+        Email[Email Service]
+        Sentry[Sentry]
+    end
+    
+    Core --> DB
+    Core --> Cache
+    Core --> Queue
+    Core --> Storage
+    Core --> OIDC
+    Core --> Email
+    Core --> Sentry
+    
+    Module1 --> Core
+    Module2 --> Core
+    Module3 --> Core
+    
+    Module1 --> DB
+    Module2 --> DB
+    Module3 --> DB
+    
+    Module1 --> Queue
+    Module2 --> Queue
+    
+    style Core fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Module1 fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style Module2 fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style Module3 fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+## Layered Architecture
+
+The platform follows a **clean/hexagonal architecture** with clear separation of concerns across layers.
+
+```mermaid
+graph TD
+    subgraph "Presentation Layer"
+        HTTP[HTTP/REST API]
+        GraphQL[GraphQL API]
+        CLI[CLI Interface]
+    end
+    
+    subgraph "Application Layer"
+        AuthMiddleware[Auth Middleware]
+        AuthzMiddleware[Authorization Middleware]
+        RateLimit[Rate Limiting]
+        Handlers[Request Handlers]
+    end
+    
+    subgraph "Domain Layer"
+        Services[Domain Services]
+        Entities[Domain Entities]
+        Policies[Business Policies]
+    end
+    
+    subgraph "Infrastructure Layer"
+        Repos[Repositories]
+        CacheAdapter[Cache Adapter]
+        EventBus[Event Bus]
+        Jobs[Scheduler/Jobs]
+    end
+    
+    subgraph "Core Kernel"
+        DI[DI Container]
+        Config[Config Manager]
+        Logger[Logger]
+        Metrics[Metrics]
+        Health[Health Checks]
+    end
+    
+    HTTP --> AuthMiddleware
+    GraphQL --> AuthMiddleware
+    CLI --> AuthMiddleware
+    
+    AuthMiddleware --> AuthzMiddleware
+    AuthzMiddleware --> RateLimit
+    RateLimit --> Handlers
+    
+    Handlers --> Services
+    Services --> Entities
+    Services --> Policies
+    
+    Services --> Repos
+    Services --> CacheAdapter
+    Services --> EventBus
+    Services --> Jobs
+    
+    Repos --> DB[(Database)]
+    CacheAdapter --> Cache[(Redis)]
+    EventBus --> Queue[(Kafka)]
+    
+    Services --> DI
+    Repos --> DI
+    Handlers --> DI
+    
+    DI --> Config
+    DI --> Logger
+    DI --> Metrics
+    DI --> Health
+    
+    style Core fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Services fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style Repos fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+```
+
+## Module System Architecture
+
+Modules are the building blocks of the platform. Each module can register services, routes, permissions, and background jobs.
+
+```mermaid
+graph TB
+    subgraph Lifecycle["Module Lifecycle"]
+        Discover["1. Discover Modules"]
+        Load["2. Load Module"]
+        Validate["3. Validate Dependencies"]
+        Init["4. Initialize Module"]
+        Start["5. Start Module"]
+    end
+    
+    subgraph Registration["Module Registration"]
+        Static["Static Registration<br/>via init()"]
+        Dynamic["Dynamic Loading<br/>via .so files"]
+    end
+    
+    subgraph Components["Module Components"]
+        Routes["HTTP Routes"]
+        Services["Services"]
+        Repos["Repositories"]
+        Perms["Permissions"]
+        Jobs["Background Jobs"]
+        Migrations["Database Migrations"]
+    end
+    
+    Discover --> Load
+    Load --> Static
+    Load --> Dynamic
+    Static --> Validate
+    Dynamic --> Validate
+    Validate --> Init
+    Init --> Routes
+    Init --> Services
+    Init --> Repos
+    Init --> Perms
+    Init --> Jobs
+    Init --> Migrations
+    Routes --> Start
+    Services --> Start
+    Repos --> Start
+    Perms --> Start
+    Jobs --> Start
+    Migrations --> Start
+    
+    classDef lifecycle fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    classDef registration fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    classDef components fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    classDef start fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+    
+    class Discover,Load,Validate,Init lifecycle
+    class Static,Dynamic registration
+    class Routes,Services,Repos,Perms,Jobs,Migrations components
+    class Start start
+```
+
+### Module Initialization Sequence
+
+```mermaid
+sequenceDiagram
+    participant Main
+    participant Loader
+    participant Registry
+    participant Module
+    participant DI
+    participant Router
+    participant DB
+    
+    Main->>Loader: LoadModules()
+    Loader->>Registry: Discover modules
+    Registry-->>Loader: List of modules
+    
+    loop For each module
+        Loader->>Module: Load module
+        Module->>Registry: Register(module)
+        Registry->>Registry: Validate dependencies
+    end
+    
+    Main->>Registry: GetAllModules()
+    Registry-->>Main: Ordered module list
+    
+    Main->>DI: Create container
+    
+    loop For each module
+        Main->>Module: Init()
+        Module->>DI: Provide services
+        Module->>Router: Register routes
+        Module->>DB: Register migrations
+    end
+    
+    Main->>DB: Run migrations
+    Main->>Router: Start HTTP server
+```
+
+## Component Relationships
+
+This diagram shows how core components interact with each other and with modules.
+
+```mermaid
+graph TB
+    subgraph "Core Kernel Components"
+        ConfigMgr[Config Manager]
+        LoggerService[Logger Service]
+        DI[DI Container]
+        ModuleLoader[Module Loader]
+        HealthRegistry[Health Registry]
+        MetricsRegistry[Metrics Registry]
+        ErrorBus[Error Bus]
+        EventBus[Event Bus]
+    end
+    
+    subgraph "Security Components"
+        AuthService[Auth Service]
+        AuthzService[Authorization Service]
+        TokenProvider[Token Provider]
+        PermissionResolver[Permission Resolver]
+        AuditService[Audit Service]
+    end
+    
+    subgraph "Infrastructure Components"
+        DBClient[Database Client]
+        CacheClient[Cache Client]
+        Scheduler[Scheduler]
+        Notifier[Notifier]
+    end
+    
+    subgraph "Module Components"
+        ModuleRoutes[Module Routes]
+        ModuleServices[Module Services]
+        ModuleRepos[Module Repositories]
+    end
+    
+    DI --> ConfigMgr
+    DI --> LoggerService
+    DI --> ModuleLoader
+    DI --> HealthRegistry
+    DI --> MetricsRegistry
+    DI --> ErrorBus
+    DI --> EventBus
+    DI --> AuthService
+    DI --> AuthzService
+    DI --> DBClient
+    DI --> CacheClient
+    DI --> Scheduler
+    DI --> Notifier
+    
+    AuthService --> TokenProvider
+    AuthzService --> PermissionResolver
+    AuthzService --> AuditService
+    
+    ModuleServices --> DBClient
+    ModuleServices --> CacheClient
+    ModuleServices --> EventBus
+    ModuleServices --> AuthzService
+    
+    ModuleRepos --> DBClient
+    ModuleRoutes --> AuthzService
+    
+    Scheduler --> CacheClient
+    Notifier --> EventBus
+    
+    ErrorBus --> LoggerService
+    ErrorBus --> Sentry
+    
+    style DI fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style AuthService fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style ModuleServices fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+## Data Flow
+
+### Request Processing Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Router
+    participant AuthMW[Auth Middleware]
+    participant AuthzMW[Authz Middleware]
+    participant RateLimit[Rate Limiter]
+    participant Handler
+    participant Service
+    participant Repo
+    participant DB
+    participant Cache
+    participant EventBus
+    participant Audit
+    
+    Client->>Router: HTTP Request
+    Router->>AuthMW: Extract JWT
+    AuthMW->>AuthMW: Validate token
+    AuthMW->>Router: Add user to context
+    
+    Router->>AuthzMW: Check permissions
+    AuthzMW->>AuthzMW: Resolve permissions
+    AuthzMW->>Router: Authorized
+    
+    Router->>RateLimit: Check rate limits
+    RateLimit->>Cache: Get rate limit state
+    Cache-->>RateLimit: Rate limit status
+    RateLimit->>Router: Within limits
+    
+    Router->>Handler: Process request
+    Handler->>Service: Business logic
+    Service->>Cache: Check cache
+    Cache-->>Service: Cache miss
+    
+    Service->>Repo: Query data
+    Repo->>DB: Execute query
+    DB-->>Repo: Return data
+    Repo-->>Service: Domain entity
+    Service->>Cache: Store in cache
+    
+    Service->>EventBus: Publish event
+    Service->>Audit: Record action
+    
+    Service-->>Handler: Response data
+    Handler-->>Router: HTTP response
+    Router-->>Client: JSON response
+```
+
+### Module Event Flow
+
+```mermaid
+graph LR
+    subgraph "Module A"
+        AService[Service A]
+        AHandler[Handler A]
+    end
+    
+    subgraph "Event Bus"
+        Bus[Event Bus]
+    end
+    
+    subgraph "Module B"
+        BService[Service B]
+        BHandler[Handler B]
+    end
+    
+    subgraph "Module C"
+        CService[Service C]
+    end
+    
+    AHandler --> AService
+    AService -->|Publish Event| Bus
+    Bus -->|Subscribe| BService
+    Bus -->|Subscribe| CService
+    BService --> BHandler
+    CService --> CService
+```
+
+## Deployment Architecture
+
+### Development Deployment
+
+```mermaid
+graph TB
+    subgraph "Developer Machine"
+        IDE[IDE/Editor]
+        Go[Go Runtime]
+        Docker[Docker]
+    end
+    
+    subgraph "Local Services"
+        App[Platform App<br/>:8080]
+        DB[(PostgreSQL<br/>:5432)]
+        Redis[(Redis<br/>:6379)]
+        Kafka[Kafka<br/>:9092]
+    end
+    
+    IDE --> Go
+    Go --> App
+    App --> DB
+    App --> Redis
+    App --> Kafka
+    
+    Docker --> DB
+    Docker --> Redis
+    Docker --> Kafka
+```
+
+### Production Deployment
+
+```mermaid
+graph TB
+    subgraph "Load Balancer"
+        LB[Load Balancer<br/>HTTPS]
+    end
+    
+    subgraph "Platform Instances"
+        App1[Platform Instance 1]
+        App2[Platform Instance 2]
+        App3[Platform Instance N]
+    end
+    
+    subgraph "Database Cluster"
+        Primary[(PostgreSQL<br/>Primary)]
+        Replica[(PostgreSQL<br/>Replica)]
+    end
+    
+    subgraph "Cache Cluster"
+        Redis1[(Redis<br/>Master)]
+        Redis2[(Redis<br/>Replica)]
+    end
+    
+    subgraph "Message Queue"
+        Kafka1[Kafka Broker 1]
+        Kafka2[Kafka Broker 2]
+        Kafka3[Kafka Broker 3]
+    end
+    
+    subgraph "Observability"
+        Prometheus[Prometheus]
+        Grafana[Grafana]
+        Jaeger[Jaeger]
+        Loki[Loki]
+    end
+    
+    subgraph "External Services"
+        Sentry[Sentry]
+        S3[S3 Storage]
+    end
+    
+    LB --> App1
+    LB --> App2
+    LB --> App3
+    
+    App1 --> Primary
+    App2 --> Primary
+    App3 --> Primary
+    App1 --> Replica
+    App2 --> Replica
+    App3 --> Replica
+    
+    App1 --> Redis1
+    App2 --> Redis1
+    App3 --> Redis1
+    
+    App1 --> Kafka1
+    App2 --> Kafka2
+    App3 --> Kafka3
+    
+    App1 --> Prometheus
+    App2 --> Prometheus
+    App3 --> Prometheus
+    
+    Prometheus --> Grafana
+    App1 --> Jaeger
+    App2 --> Jaeger
+    App3 --> Jaeger
+    App1 --> Loki
+    App2 --> Loki
+    App3 --> Loki
+    
+    App1 --> Sentry
+    App2 --> Sentry
+    App3 --> Sentry
+    
+    App1 --> S3
+    App2 --> S3
+    App3 --> S3
+    
+    style LB fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style Primary fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style Redis1 fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+```
+
+## Core Kernel Components
+
+The core kernel provides the foundation for all modules. Each component has specific responsibilities:
+
+### Component Responsibilities
+
+```mermaid
+mindmap
+  root((Core Kernel))
+    Configuration
+      Load configs
+      Environment vars
+      Secret management
+    Dependency Injection
+      Service registration
+      Lifecycle management
+      Module wiring
+    Logging
+      Structured logs
+      Request correlation
+      Log levels
+    Observability
+      Metrics
+      Tracing
+      Health checks
+    Security
+      Authentication
+      Authorization
+      Audit logging
+    Module System
+      Module discovery
+      Module loading
+      Dependency resolution
+```
+
+## Module Integration Points
+
+Modules integrate with the core through well-defined interfaces:
+
+```mermaid
+graph TB
+    subgraph "Core Kernel Interfaces"
+        IConfig[ConfigProvider]
+        ILogger[Logger]
+        IAuth[Authenticator]
+        IAuthz[Authorizer]
+        IEventBus[EventBus]
+        ICache[Cache]
+        IBlobStore[BlobStore]
+        IScheduler[Scheduler]
+        INotifier[Notifier]
+    end
+    
+    subgraph "Module Implementation"
+        Module[Feature Module]
+        ModuleServices[Module Services]
+        ModuleRoutes[Module Routes]
+    end
+    
+    Module --> IConfig
+    Module --> ILogger
+    ModuleServices --> IAuth
+    ModuleServices --> IAuthz
+    ModuleServices --> IEventBus
+    ModuleServices --> ICache
+    ModuleServices --> IBlobStore
+    ModuleServices --> IScheduler
+    ModuleServices --> INotifier
+    
+    ModuleRoutes --> IAuthz
+    
+    style IConfig fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style Module fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+## Next Steps
+
+- [Module Architecture](./architecture-modules.md) - Detailed module architecture and design
+- [Module Requirements](./module-requirements.md) - Requirements for each module
+- [Component Relationships](./component-relationships.md) - Detailed component interactions
+- [ADRs](../adr/README.md) - Architecture Decision Records
+

docs/content/assets/css/custom.css

@@ -0,0 +1,23 @@
+/* Full width content */
+.md-content {
+  max-width: 100% !important;
+}
+
+.md-main__inner {
+  max-width: 100% !important;
+}
+
+.md-grid {
+  max-width: 100% !important;
+}
+
+/* Ensure content area uses full width while keeping readable line length */
+.md-content__inner {
+  max-width: 100%;
+}
+
+/* Adjust container padding for better full-width experience */
+.md-container {
+  max-width: 100%;
+}
+

docs/content/component-relationships.md

@@ -0,0 +1,455 @@
+# Component Relationships
+
+This document details how different components of the Go Platform interact with each other, including dependency relationships, data flow, and integration patterns.
+
+## Table of Contents
+
+- [Core Component Dependencies](#core-component-dependencies)
+- [Module to Core Integration](#module-to-core-integration)
+- [Service Interaction Patterns](#service-interaction-patterns)
+- [Data Flow Patterns](#data-flow-patterns)
+- [Dependency Graph](#dependency-graph)
+
+## Core Component Dependencies
+
+The core kernel components have well-defined dependencies that form the foundation of the platform.
+
+```mermaid
+graph TD
+    subgraph "Foundation Layer"
+        Config[Config Manager]
+        Logger[Logger Service]
+    end
+    
+    subgraph "DI Layer"
+        DI[DI Container]
+    end
+    
+    subgraph "Infrastructure Layer"
+        DB[Database Client]
+        Cache[Cache Client]
+        EventBus[Event Bus]
+        Scheduler[Scheduler]
+    end
+    
+    subgraph "Security Layer"
+        Auth[Auth Service]
+        Authz[Authz Service]
+        Audit[Audit Service]
+    end
+    
+    subgraph "Observability Layer"
+        Metrics[Metrics Registry]
+        Health[Health Registry]
+        Tracer[OpenTelemetry Tracer]
+    end
+    
+    Config --> Logger
+    Config --> DI
+    Logger --> DI
+    
+    DI --> DB
+    DI --> Cache
+    DI --> EventBus
+    DI --> Scheduler
+    DI --> Auth
+    DI --> Authz
+    DI --> Audit
+    DI --> Metrics
+    DI --> Health
+    DI --> Tracer
+    
+    Auth --> DB
+    Authz --> DB
+    Authz --> Cache
+    Audit --> DB
+    
+    DB --> Tracer
+    Cache --> Tracer
+    EventBus --> Tracer
+    
+    style Config fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style DI fill:#50c878,stroke:#2e7d4e,stroke-width:3px,color:#fff
+    style Auth fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+```
+
+## Module to Core Integration
+
+Modules integrate with core services through well-defined interfaces and dependency injection.
+
+```mermaid
+graph LR
+    subgraph "Feature Module"
+        ModuleHandler[Module Handler]
+        ModuleService[Module Service]
+        ModuleRepo[Module Repository]
+    end
+    
+    subgraph "Core Services"
+        AuthService[Auth Service]
+        AuthzService[Authz Service]
+        EventBusService[Event Bus]
+        CacheService[Cache Service]
+        AuditService[Audit Service]
+        LoggerService[Logger Service]
+    end
+    
+    subgraph "Infrastructure"
+        DBClient[Database Client]
+        CacheClient[Cache Client]
+        QueueClient[Message Queue]
+    end
+    
+    ModuleHandler --> AuthService
+    ModuleHandler --> AuthzService
+    ModuleHandler --> ModuleService
+    
+    ModuleService --> ModuleRepo
+    ModuleService --> EventBusService
+    ModuleService --> CacheService
+    ModuleService --> AuditService
+    ModuleService --> LoggerService
+    
+    ModuleRepo --> DBClient
+    CacheService --> CacheClient
+    EventBusService --> QueueClient
+    
+    style ModuleService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style AuthService fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style DBClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+```
+
+## Service Interaction Patterns
+
+### Authentication Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Router
+    participant AuthMiddleware
+    participant AuthService
+    participant TokenProvider
+    participant UserRepo
+    participant DB
+    
+    Client->>Router: POST /api/v1/auth/login
+    Router->>AuthMiddleware: Extract credentials
+    AuthMiddleware->>AuthService: Authenticate(email, password)
+    AuthService->>UserRepo: FindByEmail(email)
+    UserRepo->>DB: Query user
+    DB-->>UserRepo: User data
+    UserRepo-->>AuthService: User entity
+    AuthService->>AuthService: Verify password
+    AuthService->>TokenProvider: GenerateAccessToken(user)
+    AuthService->>TokenProvider: GenerateRefreshToken(user)
+    TokenProvider-->>AuthService: Tokens
+    AuthService->>DB: Store refresh token
+    AuthService-->>AuthMiddleware: Auth response
+    AuthMiddleware-->>Router: Tokens
+    Router-->>Client: JSON response with tokens
+```
+
+### Authorization Flow
+
+```mermaid
+sequenceDiagram
+    participant Request
+    participant AuthzMiddleware
+    participant Authorizer
+    participant PermissionResolver
+    participant Cache
+    participant UserRepo
+    participant RoleRepo
+    participant DB
+    
+    Request->>AuthzMiddleware: HTTP request + 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->>UserRepo: GetUserRoles(userID)
+    UserRepo->>DB: Query user_roles
+    DB-->>UserRepo: Role IDs
+    UserRepo-->>PermissionResolver: Roles
+    
+    PermissionResolver->>RoleRepo: GetRolePermissions(roleIDs)
+    RoleRepo->>DB: Query role_permissions
+    DB-->>RoleRepo: Permissions
+    RoleRepo-->>PermissionResolver: Permission list
+    
+    PermissionResolver->>PermissionResolver: Check if permission in list
+    PermissionResolver->>Cache: Store in cache
+    PermissionResolver-->>Authorizer: Has permission: true/false
+    Authorizer-->>AuthzMiddleware: Authorized or error
+    AuthzMiddleware-->>Request: Continue or 403
+```
+
+### Event Publishing Flow
+
+```mermaid
+sequenceDiagram
+    participant ModuleService
+    participant EventBus
+    participant Kafka
+    participant Subscriber1
+    participant Subscriber2
+    
+    ModuleService->>EventBus: Publish(topic, event)
+    EventBus->>EventBus: Serialize event
+    EventBus->>Kafka: Send to topic
+    Kafka-->>EventBus: Acknowledged
+    
+    Kafka->>Subscriber1: Deliver event
+    Kafka->>Subscriber2: Deliver event
+    
+    Subscriber1->>Subscriber1: Process event
+    Subscriber2->>Subscriber2: Process event
+```
+
+## Data Flow Patterns
+
+### Request to Response Flow
+
+```mermaid
+graph LR
+    Client[Client] -->|HTTP Request| LB[Load Balancer]
+    LB -->|Route| Server1[Instance 1]
+    LB -->|Route| Server2[Instance 2]
+    
+    Server1 --> AuthMW[Auth Middleware]
+    Server1 --> AuthzMW[Authz Middleware]
+    Server1 --> RateLimit[Rate Limiter]
+    Server1 --> Handler[Request Handler]
+    Server1 --> Service[Domain Service]
+    Server1 --> Cache[Cache Check]
+    Server1 --> Repo[Repository]
+    Server1 --> DB[(Database)]
+    
+    Service --> EventBus[Event Bus]
+    Service --> Audit[Audit Log]
+    
+    Handler -->|Response| Server1
+    Server1 -->|HTTP Response| LB
+    LB -->|Response| Client
+    
+    style Server1 fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style Service fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+```
+
+### Caching Flow
+
+```mermaid
+graph TD
+    Request[Service Request] --> CacheCheck{Cache Hit?}
+    CacheCheck -->|Yes| CacheGet[Get from Cache]
+    CacheCheck -->|No| DBQuery[Query Database]
+    DBQuery --> DBResponse[Database Response]
+    DBResponse --> CacheStore[Store in Cache]
+    CacheStore --> Return[Return Data]
+    CacheGet --> Return
+    
+    style CacheCheck fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style CacheGet fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+    style DBQuery fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+```
+
+## Dependency Graph
+
+Complete dependency graph showing all components and their relationships.
+
+```mermaid
+graph TB
+    subgraph "Application Entry"
+        Main[Main Application]
+    end
+    
+    subgraph "Core Kernel"
+        Config[Config]
+        Logger[Logger]
+        DI[DI Container]
+        ModuleLoader[Module Loader]
+    end
+    
+    subgraph "Security"
+        Auth[Auth]
+        Authz[Authz]
+        Identity[Identity]
+        Audit[Audit]
+    end
+    
+    subgraph "Infrastructure"
+        DB[Database]
+        Cache[Cache]
+        EventBus[Event Bus]
+        Scheduler[Scheduler]
+        BlobStore[Blob Store]
+        Notifier[Notifier]
+    end
+    
+    subgraph "Observability"
+        Metrics[Metrics]
+        Health[Health]
+        Tracer[Tracer]
+        ErrorBus[Error Bus]
+    end
+    
+    subgraph "Module"
+        ModuleHandler[Module Handler]
+        ModuleService[Module Service]
+        ModuleRepo[Module Repo]
+    end
+    
+    Main --> Config
+    Main --> Logger
+    Main --> DI
+    Main --> ModuleLoader
+    
+    Config --> Logger
+    Config --> DI
+    
+    DI --> Auth
+    DI --> Authz
+    DI --> Identity
+    DI --> Audit
+    DI --> DB
+    DI --> Cache
+    DI --> EventBus
+    DI --> Scheduler
+    DI --> BlobStore
+    DI --> Notifier
+    DI --> Metrics
+    DI --> Health
+    DI --> Tracer
+    DI --> ErrorBus
+    
+    Auth --> Identity
+    Auth --> DB
+    Authz --> Identity
+    Authz --> Cache
+    Authz --> Audit
+    Audit --> DB
+    Audit --> Logger
+    
+    ModuleLoader --> DI
+    ModuleHandler --> Auth
+    ModuleHandler --> Authz
+    ModuleService --> ModuleRepo
+    ModuleService --> EventBus
+    ModuleService --> Cache
+    ModuleService --> Audit
+    ModuleRepo --> DB
+    
+    Scheduler --> Cache
+    Notifier --> EventBus
+    
+    ErrorBus --> Logger
+    ErrorBus --> Sentry
+    
+    DB --> Tracer
+    Cache --> Tracer
+    EventBus --> Tracer
+    
+    style Main fill:#4a90e2,stroke:#2e5c8a,stroke-width:4px,color:#fff
+    style DI fill:#50c878,stroke:#2e7d4e,stroke-width:3px,color:#fff
+    style ModuleService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+## Component Interaction Matrix
+
+| Component | Depends On | Used By |
+|-----------|-----------|---------|
+| Config | None | All components |
+| Logger | Config | All components |
+| DI Container | Config, Logger | All components |
+| Auth Service | Identity, DB | Auth Middleware, Modules |
+| Authz Service | Identity, Cache, Audit | Authz Middleware, Modules |
+| Identity Service | DB, Cache, Notifier | Auth, Authz, Modules |
+| Database Client | Config, Logger, Tracer | All repositories |
+| Cache Client | Config, Logger | Authz, Scheduler, Modules |
+| Event Bus | Config, Logger, Tracer | Modules, Notifier |
+| Scheduler | Cache, Logger | Modules |
+| Error Bus | Logger | All components (via panic recovery) |
+
+## Integration Patterns
+
+### Module Service Integration
+
+```mermaid
+graph TB
+    subgraph "Module Layer"
+        Handler[HTTP Handler]
+        Service[Domain Service]
+        Repo[Repository]
+    end
+    
+    subgraph "Core Services"
+        Auth[Auth Service]
+        Authz[Authz Service]
+        EventBus[Event Bus]
+        Cache[Cache]
+        Audit[Audit]
+    end
+    
+    subgraph "Infrastructure"
+        DB[(Database)]
+        Redis[(Redis)]
+        Kafka[Kafka]
+    end
+    
+    Handler --> Auth
+    Handler --> Authz
+    Handler --> Service
+    
+    Service --> Repo
+    Service --> EventBus
+    Service --> Cache
+    Service --> Audit
+    
+    Repo --> DB
+    Cache --> Redis
+    EventBus --> Kafka
+    Audit --> DB
+    
+    style Service fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style Auth fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
+    style DB fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
+```
+
+### Cross-Module Communication
+
+```mermaid
+graph LR
+    subgraph "Module A"
+        AService[Service A]
+    end
+    
+    subgraph "Module B"
+        BService[Service B]
+    end
+    
+    subgraph "Core Services"
+        EventBus[Event Bus]
+        Authz[Authz Service]
+        Cache[Cache]
+    end
+    
+    AService -->|Direct Call| Authz
+    AService -->|Publish Event| EventBus
+    EventBus -->|Subscribe| BService
+    AService -->|Cache Access| Cache
+    BService -->|Cache Access| Cache
+    
+    style AService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style BService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+    style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+```
+
+## Next Steps
+
+- [System Architecture](./architecture.md) - Overall system architecture
+- [Module Architecture](./architecture-modules.md) - Module design and integration
+- [Module Requirements](./module-requirements.md) - Detailed module requirements
+

docs/content/index.md

@@ -0,0 +1,74 @@
+# Go Platform Documentation
+
+Welcome to the Go Platform documentation! This is a plugin-friendly SaaS/Enterprise platform built with Go.
+
+## What is Go Platform?
+
+Go Platform is a modular, extensible platform designed to support multiple business domains through a plugin architecture. It provides:
+
+- **Core Kernel**: Foundation services including authentication, authorization, configuration, logging, and observability
+- **Module Framework**: Plugin system for extending functionality
+- **Infrastructure Adapters**: Support for databases, caching, event buses, and job scheduling
+- **Security-by-Design**: Built-in JWT authentication, RBAC/ABAC authorization, and audit logging
+- **Observability**: OpenTelemetry integration for tracing, metrics, and logging
+
+## Documentation Structure
+
+### 📋 Overview
+- **[Requirements](requirements.md)**: High-level architectural principles and requirements
+- **[Implementation Plan](plan.md)**: Phased implementation plan with timelines
+- **[Playbook](playbook.md)**: Detailed implementation guide and best practices
+
+### 🏛️ Architecture
+- **[Architecture Overview](architecture.md)**: System architecture with diagrams
+- **[Module Architecture](architecture-modules.md)**: Module system design and integration
+- **[Module Requirements](module-requirements.md)**: Detailed requirements for each module
+- **[Component Relationships](component-relationships.md)**: Component interactions and dependencies
+
+### 🏗️ Architecture Decision Records (ADRs)
+All architectural decisions are documented in [ADR records](adr/README.md), organized by implementation phase:
+- **Phase 0**: Project Setup & Foundation
+- **Phase 1**: Core Kernel & Infrastructure
+- **Phase 2**: Authentication & Authorization
+- **Phase 3**: Module Framework
+- **Phase 5**: Infrastructure Adapters
+- **Phase 6**: Observability & Production Readiness
+- **Phase 7**: Testing, Documentation & CI/CD
+
+### 📝 Implementation Tasks
+Detailed task definitions for each phase are available in the [Stories section](stories/README.md):
+- Phase 0: Project Setup & Foundation
+- Phase 1: Core Kernel & Infrastructure
+- Phase 2: Authentication & Authorization
+- Phase 3: Module Framework
+- Phase 4: Sample Feature Module (Blog)
+- Phase 5: Infrastructure Adapters
+- Phase 6: Observability & Production Readiness
+- Phase 7: Testing, Documentation & CI/CD
+- Phase 8: Advanced Features & Polish (Optional)
+
+## Quick Start
+
+1. Review the [Requirements](requirements.md) to understand the platform goals
+2. Check the [Implementation Plan](plan.md) for the phased approach
+3. Follow the [Playbook](playbook.md) for implementation details
+4. Refer to [ADRs](adr/README.md) when making architectural decisions
+5. Use the [Task Stories](stories/README.md) as a checklist for implementation
+
+## Key Principles
+
+- **Clean/Hexagonal Architecture**: Clear separation between core and plugins
+- **Modular Monolith**: Start simple, evolve to microservices if needed
+- **Plugin-First Design**: Extensible architecture supporting static and dynamic modules
+- **Security-by-Design**: Built-in authentication, authorization, and audit capabilities
+- **Observability**: Comprehensive logging, metrics, and tracing
+- **API-First**: OpenAPI/GraphQL schema generation
+
+## Contributing
+
+When contributing to the platform:
+1. Review relevant ADRs before making architectural decisions
+2. Follow the task structure defined in the Stories
+3. Update documentation as you implement features
+4. Ensure all tests pass before submitting changes
+

docs/content/module-requirements.md

@@ -0,0 +1,816 @@
+# 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
+

docs/content/requirements.md

@@ -1,6 +1,6 @@
 # Requirements
 
-## 1️⃣ HIGH‑LEVEL ARCHITECTURAL PRINCIPLES
+## HIGH‑LEVEL ARCHITECTURAL PRINCIPLES
 
 | Principle | Why it matters for a modular platform | How to enforce it |
 |-----------|----------------------------------------|-------------------|
@@ -18,7 +18,7 @@
 
 ---
 
-## 2️⃣ LAYERED / HEXAGONAL BLUEPRINT
+## LAYERED / HEXAGONAL BLUEPRINT
 
 ```
 +---------------------------------------------------+
@@ -50,7 +50,7 @@
 
 ---
 
-## 3️⃣ REQUIRED BASE MODULES (THE “CORE KERNEL”)
+## REQUIRED BASE MODULES (THE “CORE KERNEL”)
 
 | Module | Core responsibilities | Public API / Extension points |
 |--------|-----------------------|--------------------------------|
@@ -74,7 +74,7 @@
 
 ---
 
-## 4️⃣ EXTENSION‑POINT DESIGN (HOW PLUG‑INS HOOK IN)
+## EXTENSION‑POINT DESIGN (HOW PLUG‑INS HOOK IN)
 
 1. **Module Manifest** – a tiny JSON/YAML file (`module.yaml`) that declares:
    - Module name, version, dependencies (core ≥ 1.2.0, other modules)
@@ -123,7 +123,7 @@
 
 ---
 
-## 5️⃣ SAMPLE REPOSITORY LAYOUT (language‑agnostic)
+## SAMPLE REPOSITORY LAYOUT (language‑agnostic)
 
 ```
 /platform-root
@@ -206,7 +206,7 @@ bootstrap().catch(err => {
 
 ---
 
-## 6️⃣ KEY DECISIONS YOU MUST TAKE EARLY
+## KEY DECISIONS YOU MUST TAKE EARLY
 
 | Decision | Options | Implications |
 |----------|---------|--------------|
@@ -222,7 +222,7 @@ bootstrap().catch(err => {
 
 ---
 
-## 7️⃣ COMMON PITFALLS & HOW TO AVOID THEM
+## COMMON PITFALLS & HOW TO AVOID THEM
 
 | Pitfall | Symptoms | Fix / Guardrail |
 |---------|----------|-----------------|
@@ -238,7 +238,7 @@ bootstrap().catch(err => {
 
 ---
 
-## 8️⃣ QUICK START GUIDE (What to Build First)
+## QUICK START GUIDE (What to Build First)
 
 1. **Create the Core Kernel**  
    - Set up DI container, config loader, logger, health/metrics endpoint.  
@@ -280,7 +280,7 @@ bootstrap().catch(err => {
 
 ---
 
-## 9️⃣ TOOLS & LIBRARIES (starter suggestions per stack)
+## TOOLS & LIBRARIES (starter suggestions per stack)
 
 | Stack | Core | Auth | DI / Module | Event Bus | ORM | Validation | Testing |
 |-------|------|------|-------------|-----------|-----|------------|---------|
@@ -294,7 +294,7 @@ Pick the stack you’re most comfortable with; the concepts stay identical.
 
 ---
 
-## 🎉 TL;DR – What You Must Deliver
+## TL;DR – What You Must Deliver
 
 | Layer | Must‑have components | Why |
 |-------|----------------------|-----|