diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..b4dd939
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,14 @@
+# Docker ignore file for MkDocs build
+site/
+.mkdocs_cache/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+venv/
+env/
+ENV/
+.git/
+.gitignore
+
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..a30a249
--- /dev/null
+++ b/.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
+
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..afa4049
--- /dev/null
+++ b/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
+
diff --git a/docs/.dockerignore b/docs/.dockerignore
new file mode 100644
index 0000000..b4dd939
--- /dev/null
+++ b/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
+
diff --git a/docs/Dockerfile b/docs/Dockerfile
new file mode 100644
index 0000000..96ab743
--- /dev/null
+++ b/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"]
+
diff --git a/docs/MKDOCS_README.md b/docs/MKDOCS_README.md
new file mode 100644
index 0000000..37238d7
--- /dev/null
+++ b/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
+
diff --git a/docs/adr/0001-go-module-path.md b/docs/content/adr/0001-go-module-path.md
similarity index 100%
rename from docs/adr/0001-go-module-path.md
rename to docs/content/adr/0001-go-module-path.md
diff --git a/docs/adr/0002-go-version.md b/docs/content/adr/0002-go-version.md
similarity index 100%
rename from docs/adr/0002-go-version.md
rename to docs/content/adr/0002-go-version.md
diff --git a/docs/adr/0003-dependency-injection-framework.md b/docs/content/adr/0003-dependency-injection-framework.md
similarity index 100%
rename from docs/adr/0003-dependency-injection-framework.md
rename to docs/content/adr/0003-dependency-injection-framework.md
diff --git a/docs/adr/0004-configuration-management.md b/docs/content/adr/0004-configuration-management.md
similarity index 100%
rename from docs/adr/0004-configuration-management.md
rename to docs/content/adr/0004-configuration-management.md
diff --git a/docs/adr/0005-logging-framework.md b/docs/content/adr/0005-logging-framework.md
similarity index 100%
rename from docs/adr/0005-logging-framework.md
rename to docs/content/adr/0005-logging-framework.md
diff --git a/docs/adr/0006-http-framework.md b/docs/content/adr/0006-http-framework.md
similarity index 100%
rename from docs/adr/0006-http-framework.md
rename to docs/content/adr/0006-http-framework.md
diff --git a/docs/adr/0007-project-directory-structure.md b/docs/content/adr/0007-project-directory-structure.md
similarity index 100%
rename from docs/adr/0007-project-directory-structure.md
rename to docs/content/adr/0007-project-directory-structure.md
diff --git a/docs/adr/0008-error-handling-strategy.md b/docs/content/adr/0008-error-handling-strategy.md
similarity index 100%
rename from docs/adr/0008-error-handling-strategy.md
rename to docs/content/adr/0008-error-handling-strategy.md
diff --git a/docs/adr/0009-context-key-types.md b/docs/content/adr/0009-context-key-types.md
similarity index 100%
rename from docs/adr/0009-context-key-types.md
rename to docs/content/adr/0009-context-key-types.md
diff --git a/docs/adr/0010-ci-cd-platform.md b/docs/content/adr/0010-ci-cd-platform.md
similarity index 100%
rename from docs/adr/0010-ci-cd-platform.md
rename to docs/content/adr/0010-ci-cd-platform.md
diff --git a/docs/adr/0011-code-generation-tools.md b/docs/content/adr/0011-code-generation-tools.md
similarity index 100%
rename from docs/adr/0011-code-generation-tools.md
rename to docs/content/adr/0011-code-generation-tools.md
diff --git a/docs/adr/0012-logger-interface-design.md b/docs/content/adr/0012-logger-interface-design.md
similarity index 100%
rename from docs/adr/0012-logger-interface-design.md
rename to docs/content/adr/0012-logger-interface-design.md
diff --git a/docs/adr/0013-database-orm.md b/docs/content/adr/0013-database-orm.md
similarity index 100%
rename from docs/adr/0013-database-orm.md
rename to docs/content/adr/0013-database-orm.md
diff --git a/docs/adr/0014-health-check-implementation.md b/docs/content/adr/0014-health-check-implementation.md
similarity index 100%
rename from docs/adr/0014-health-check-implementation.md
rename to docs/content/adr/0014-health-check-implementation.md
diff --git a/docs/adr/0015-error-bus-implementation.md b/docs/content/adr/0015-error-bus-implementation.md
similarity index 100%
rename from docs/adr/0015-error-bus-implementation.md
rename to docs/content/adr/0015-error-bus-implementation.md
diff --git a/docs/adr/0016-opentelemetry-observability.md b/docs/content/adr/0016-opentelemetry-observability.md
similarity index 100%
rename from docs/adr/0016-opentelemetry-observability.md
rename to docs/content/adr/0016-opentelemetry-observability.md
diff --git a/docs/adr/0017-jwt-token-strategy.md b/docs/content/adr/0017-jwt-token-strategy.md
similarity index 100%
rename from docs/adr/0017-jwt-token-strategy.md
rename to docs/content/adr/0017-jwt-token-strategy.md
diff --git a/docs/adr/0018-password-hashing.md b/docs/content/adr/0018-password-hashing.md
similarity index 100%
rename from docs/adr/0018-password-hashing.md
rename to docs/content/adr/0018-password-hashing.md
diff --git a/docs/adr/0019-permission-dsl-format.md b/docs/content/adr/0019-permission-dsl-format.md
similarity index 100%
rename from docs/adr/0019-permission-dsl-format.md
rename to docs/content/adr/0019-permission-dsl-format.md
diff --git a/docs/adr/0020-audit-logging-storage.md b/docs/content/adr/0020-audit-logging-storage.md
similarity index 100%
rename from docs/adr/0020-audit-logging-storage.md
rename to docs/content/adr/0020-audit-logging-storage.md
diff --git a/docs/adr/0021-module-loading-strategy.md b/docs/content/adr/0021-module-loading-strategy.md
similarity index 100%
rename from docs/adr/0021-module-loading-strategy.md
rename to docs/content/adr/0021-module-loading-strategy.md
diff --git a/docs/adr/0022-cache-implementation.md b/docs/content/adr/0022-cache-implementation.md
similarity index 100%
rename from docs/adr/0022-cache-implementation.md
rename to docs/content/adr/0022-cache-implementation.md
diff --git a/docs/adr/0023-event-bus-implementation.md b/docs/content/adr/0023-event-bus-implementation.md
similarity index 100%
rename from docs/adr/0023-event-bus-implementation.md
rename to docs/content/adr/0023-event-bus-implementation.md
diff --git a/docs/adr/0024-job-scheduler.md b/docs/content/adr/0024-job-scheduler.md
similarity index 100%
rename from docs/adr/0024-job-scheduler.md
rename to docs/content/adr/0024-job-scheduler.md
diff --git a/docs/adr/0025-multitenancy-model.md b/docs/content/adr/0025-multitenancy-model.md
similarity index 100%
rename from docs/adr/0025-multitenancy-model.md
rename to docs/content/adr/0025-multitenancy-model.md
diff --git a/docs/adr/0026-error-reporting-service.md b/docs/content/adr/0026-error-reporting-service.md
similarity index 100%
rename from docs/adr/0026-error-reporting-service.md
rename to docs/content/adr/0026-error-reporting-service.md
diff --git a/docs/adr/0027-rate-limiting-strategy.md b/docs/content/adr/0027-rate-limiting-strategy.md
similarity index 100%
rename from docs/adr/0027-rate-limiting-strategy.md
rename to docs/content/adr/0027-rate-limiting-strategy.md
diff --git a/docs/adr/0028-testing-strategy.md b/docs/content/adr/0028-testing-strategy.md
similarity index 100%
rename from docs/adr/0028-testing-strategy.md
rename to docs/content/adr/0028-testing-strategy.md
diff --git a/docs/adr/README.md b/docs/content/adr/README.md
similarity index 100%
rename from docs/adr/README.md
rename to docs/content/adr/README.md
diff --git a/docs/content/architecture-modules.md b/docs/content/architecture-modules.md
new file mode 100644
index 0000000..264f1a1
--- /dev/null
+++ b/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
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 {
+ <>
+ +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
depends on: Core]
+ M2[Module B
depends on: Core, Module A]
+ M3[Module C
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
via DI]
+ Events[Event Bus
Publish/Subscribe]
+ Shared[Shared Interfaces
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
tenant_id]
+ Roles[roles
tenant_id]
+ end
+
+ subgraph "Blog Module Tables"
+ Posts[blog_posts
tenant_id]
+ Comments[blog_comments
tenant_id]
+ end
+
+ subgraph "Billing Module Tables"
+ Subscriptions[billing_subscriptions
tenant_id]
+ Invoices[billing_invoices
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
/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
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
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
+
diff --git a/docs/content/architecture.md b/docs/content/architecture.md
new file mode 100644
index 0000000..2a28e70
--- /dev/null
+++ b/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
Blog]
+ Module2[Module 2
Billing]
+ Module3[Module N
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
via init()"]
+ Dynamic["Dynamic Loading
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
:8080]
+ DB[(PostgreSQL
:5432)]
+ Redis[(Redis
:6379)]
+ Kafka[Kafka
: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
HTTPS]
+ end
+
+ subgraph "Platform Instances"
+ App1[Platform Instance 1]
+ App2[Platform Instance 2]
+ App3[Platform Instance N]
+ end
+
+ subgraph "Database Cluster"
+ Primary[(PostgreSQL
Primary)]
+ Replica[(PostgreSQL
Replica)]
+ end
+
+ subgraph "Cache Cluster"
+ Redis1[(Redis
Master)]
+ Redis2[(Redis
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
+
diff --git a/docs/content/assets/css/custom.css b/docs/content/assets/css/custom.css
new file mode 100644
index 0000000..2194e6a
--- /dev/null
+++ b/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%;
+}
+
diff --git a/docs/content/component-relationships.md b/docs/content/component-relationships.md
new file mode 100644
index 0000000..aff238e
--- /dev/null
+++ b/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
+
diff --git a/docs/content/index.md b/docs/content/index.md
new file mode 100644
index 0000000..934663a
--- /dev/null
+++ b/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
+
diff --git a/docs/content/module-requirements.md b/docs/content/module-requirements.md
new file mode 100644
index 0000000..ad07e18
--- /dev/null
+++ b/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
+
diff --git a/docs/plan.md b/docs/content/plan.md
similarity index 100%
rename from docs/plan.md
rename to docs/content/plan.md
diff --git a/docs/playbook.md b/docs/content/playbook.md
similarity index 100%
rename from docs/playbook.md
rename to docs/content/playbook.md
diff --git a/docs/requirements.md b/docs/content/requirements.md
similarity index 97%
rename from docs/requirements.md
rename to docs/content/requirements.md
index 0c5da65..a804104 100644
--- a/docs/requirements.md
+++ b/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 |
|-------|----------------------|-----|
diff --git a/docs/stories/COMPLETE_TASK_LIST.md b/docs/content/stories/COMPLETE_TASK_LIST.md
similarity index 100%
rename from docs/stories/COMPLETE_TASK_LIST.md
rename to docs/content/stories/COMPLETE_TASK_LIST.md
diff --git a/docs/stories/README.md b/docs/content/stories/README.md
similarity index 100%
rename from docs/stories/README.md
rename to docs/content/stories/README.md
diff --git a/docs/stories/TASK_TEMPLATE.md b/docs/content/stories/TASK_TEMPLATE.md
similarity index 100%
rename from docs/stories/TASK_TEMPLATE.md
rename to docs/content/stories/TASK_TEMPLATE.md
diff --git a/docs/stories/generate_tasks.py b/docs/content/stories/generate_tasks.py
similarity index 100%
rename from docs/stories/generate_tasks.py
rename to docs/content/stories/generate_tasks.py
diff --git a/docs/stories/phase0/0.1.1-initialize-go-module-go-mod-init-githubcomyourorgp.md b/docs/content/stories/phase0/0.1.1-initialize-go-module-go-mod-init-githubcomyourorgp.md
similarity index 100%
rename from docs/stories/phase0/0.1.1-initialize-go-module-go-mod-init-githubcomyourorgp.md
rename to docs/content/stories/phase0/0.1.1-initialize-go-module-go-mod-init-githubcomyourorgp.md
diff --git a/docs/stories/phase0/0.1.1-initialize-go-module.md b/docs/content/stories/phase0/0.1.1-initialize-go-module.md
similarity index 100%
rename from docs/stories/phase0/0.1.1-initialize-go-module.md
rename to docs/content/stories/phase0/0.1.1-initialize-go-module.md
diff --git a/docs/stories/phase0/0.1.2-create-directory-structure.md b/docs/content/stories/phase0/0.1.2-create-directory-structure.md
similarity index 100%
rename from docs/stories/phase0/0.1.2-create-directory-structure.md
rename to docs/content/stories/phase0/0.1.2-create-directory-structure.md
diff --git a/docs/stories/phase0/0.1.3-add-gitignore-for-go-projects.md b/docs/content/stories/phase0/0.1.3-add-gitignore-for-go-projects.md
similarity index 100%
rename from docs/stories/phase0/0.1.3-add-gitignore-for-go-projects.md
rename to docs/content/stories/phase0/0.1.3-add-gitignore-for-go-projects.md
diff --git a/docs/stories/phase0/0.1.3-add-gitignore.md b/docs/content/stories/phase0/0.1.3-add-gitignore.md
similarity index 100%
rename from docs/stories/phase0/0.1.3-add-gitignore.md
rename to docs/content/stories/phase0/0.1.3-add-gitignore.md
diff --git a/docs/stories/phase0/0.1.4-create-initial-readme.md b/docs/content/stories/phase0/0.1.4-create-initial-readme.md
similarity index 100%
rename from docs/stories/phase0/0.1.4-create-initial-readme.md
rename to docs/content/stories/phase0/0.1.4-create-initial-readme.md
diff --git a/docs/stories/phase0/0.1.4-create-initial-readmemd-with-project-overview.md b/docs/content/stories/phase0/0.1.4-create-initial-readmemd-with-project-overview.md
similarity index 100%
rename from docs/stories/phase0/0.1.4-create-initial-readmemd-with-project-overview.md
rename to docs/content/stories/phase0/0.1.4-create-initial-readmemd-with-project-overview.md
diff --git a/docs/stories/phase0/0.2.1-install-config-dependencies.md b/docs/content/stories/phase0/0.2.1-install-config-dependencies.md
similarity index 100%
rename from docs/stories/phase0/0.2.1-install-config-dependencies.md
rename to docs/content/stories/phase0/0.2.1-install-config-dependencies.md
diff --git a/docs/stories/phase0/0.2.1-install-githubcomspf13viper-and-githubcomspf13cobr.md b/docs/content/stories/phase0/0.2.1-install-githubcomspf13viper-and-githubcomspf13cobr.md
similarity index 100%
rename from docs/stories/phase0/0.2.1-install-githubcomspf13viper-and-githubcomspf13cobr.md
rename to docs/content/stories/phase0/0.2.1-install-githubcomspf13viper-and-githubcomspf13cobr.md
diff --git a/docs/stories/phase0/0.2.2-create-config-interface.md b/docs/content/stories/phase0/0.2.2-create-config-interface.md
similarity index 100%
rename from docs/stories/phase0/0.2.2-create-config-interface.md
rename to docs/content/stories/phase0/0.2.2-create-config-interface.md
diff --git a/docs/stories/phase0/0.2.2-create-pkgconfigconfiggo-interface.md b/docs/content/stories/phase0/0.2.2-create-pkgconfigconfiggo-interface.md
similarity index 100%
rename from docs/stories/phase0/0.2.2-create-pkgconfigconfiggo-interface.md
rename to docs/content/stories/phase0/0.2.2-create-pkgconfigconfiggo-interface.md
diff --git a/docs/stories/phase0/0.2.3-implement-config-loader.md b/docs/content/stories/phase0/0.2.3-implement-config-loader.md
similarity index 100%
rename from docs/stories/phase0/0.2.3-implement-config-loader.md
rename to docs/content/stories/phase0/0.2.3-implement-config-loader.md
diff --git a/docs/stories/phase0/0.2.3-implement-internalconfigconfiggo-using-viper.md b/docs/content/stories/phase0/0.2.3-implement-internalconfigconfiggo-using-viper.md
similarity index 100%
rename from docs/stories/phase0/0.2.3-implement-internalconfigconfiggo-using-viper.md
rename to docs/content/stories/phase0/0.2.3-implement-internalconfigconfiggo-using-viper.md
diff --git a/docs/stories/phase0/0.2.4-create-configdefaultyaml-with-basic-structure.md b/docs/content/stories/phase0/0.2.4-create-configdefaultyaml-with-basic-structure.md
similarity index 100%
rename from docs/stories/phase0/0.2.4-create-configdefaultyaml-with-basic-structure.md
rename to docs/content/stories/phase0/0.2.4-create-configdefaultyaml-with-basic-structure.md
diff --git a/docs/stories/phase0/0.2.4-create-configuration-files.md b/docs/content/stories/phase0/0.2.4-create-configuration-files.md
similarity index 100%
rename from docs/stories/phase0/0.2.4-create-configuration-files.md
rename to docs/content/stories/phase0/0.2.4-create-configuration-files.md
diff --git a/docs/stories/phase0/0.2.5-add-internalconfigloadergo-with-loadconfig-functio.md b/docs/content/stories/phase0/0.2.5-add-internalconfigloadergo-with-loadconfig-functio.md
similarity index 100%
rename from docs/stories/phase0/0.2.5-add-internalconfigloadergo-with-loadconfig-functio.md
rename to docs/content/stories/phase0/0.2.5-add-internalconfigloadergo-with-loadconfig-functio.md
diff --git a/docs/stories/phase0/0.3.1-install-gouberorgzap.md b/docs/content/stories/phase0/0.3.1-install-gouberorgzap.md
similarity index 100%
rename from docs/stories/phase0/0.3.1-install-gouberorgzap.md
rename to docs/content/stories/phase0/0.3.1-install-gouberorgzap.md
diff --git a/docs/stories/phase0/0.3.1-install-logging-dependencies.md b/docs/content/stories/phase0/0.3.1-install-logging-dependencies.md
similarity index 100%
rename from docs/stories/phase0/0.3.1-install-logging-dependencies.md
rename to docs/content/stories/phase0/0.3.1-install-logging-dependencies.md
diff --git a/docs/stories/phase0/0.3.2-create-pkgloggerloggergo-interface.md b/docs/content/stories/phase0/0.3.2-create-pkgloggerloggergo-interface.md
similarity index 100%
rename from docs/stories/phase0/0.3.2-create-pkgloggerloggergo-interface.md
rename to docs/content/stories/phase0/0.3.2-create-pkgloggerloggergo-interface.md
diff --git a/docs/stories/phase0/0.3.3-implement-internalloggerzap_loggergo.md b/docs/content/stories/phase0/0.3.3-implement-internalloggerzap_loggergo.md
similarity index 100%
rename from docs/stories/phase0/0.3.3-implement-internalloggerzap_loggergo.md
rename to docs/content/stories/phase0/0.3.3-implement-internalloggerzap_loggergo.md
diff --git a/docs/stories/phase0/0.3.4-add-request-id-middleware-helper-gin-middleware.md b/docs/content/stories/phase0/0.3.4-add-request-id-middleware-helper-gin-middleware.md
similarity index 100%
rename from docs/stories/phase0/0.3.4-add-request-id-middleware-helper-gin-middleware.md
rename to docs/content/stories/phase0/0.3.4-add-request-id-middleware-helper-gin-middleware.md
diff --git a/docs/stories/phase0/0.4.1-create-githubworkflowsciyml.md b/docs/content/stories/phase0/0.4.1-create-githubworkflowsciyml.md
similarity index 100%
rename from docs/stories/phase0/0.4.1-create-githubworkflowsciyml.md
rename to docs/content/stories/phase0/0.4.1-create-githubworkflowsciyml.md
diff --git a/docs/stories/phase0/0.4.2-add-makefile-with-common-commands.md b/docs/content/stories/phase0/0.4.2-add-makefile-with-common-commands.md
similarity index 100%
rename from docs/stories/phase0/0.4.2-add-makefile-with-common-commands.md
rename to docs/content/stories/phase0/0.4.2-add-makefile-with-common-commands.md
diff --git a/docs/stories/phase0/0.5.1-install-gouberorgfx.md b/docs/content/stories/phase0/0.5.1-install-gouberorgfx.md
similarity index 100%
rename from docs/stories/phase0/0.5.1-install-gouberorgfx.md
rename to docs/content/stories/phase0/0.5.1-install-gouberorgfx.md
diff --git a/docs/stories/phase0/0.5.2-create-internaldicontainergo.md b/docs/content/stories/phase0/0.5.2-create-internaldicontainergo.md
similarity index 100%
rename from docs/stories/phase0/0.5.2-create-internaldicontainergo.md
rename to docs/content/stories/phase0/0.5.2-create-internaldicontainergo.md
diff --git a/docs/stories/phase0/0.5.3-create-cmdplatformmaingo-skeleton.md b/docs/content/stories/phase0/0.5.3-create-cmdplatformmaingo-skeleton.md
similarity index 100%
rename from docs/stories/phase0/0.5.3-create-cmdplatformmaingo-skeleton.md
rename to docs/content/stories/phase0/0.5.3-create-cmdplatformmaingo-skeleton.md
diff --git a/docs/stories/phase0/README.md b/docs/content/stories/phase0/README.md
similarity index 100%
rename from docs/stories/phase0/README.md
rename to docs/content/stories/phase0/README.md
diff --git a/docs/stories/phase1/1.1.1-extend-internaldicontainergo.md b/docs/content/stories/phase1/1.1.1-extend-internaldicontainergo.md
similarity index 100%
rename from docs/stories/phase1/1.1.1-extend-internaldicontainergo.md
rename to docs/content/stories/phase1/1.1.1-extend-internaldicontainergo.md
diff --git a/docs/stories/phase1/1.1.2-create-internaldiprovidersgo.md b/docs/content/stories/phase1/1.1.2-create-internaldiprovidersgo.md
similarity index 100%
rename from docs/stories/phase1/1.1.2-create-internaldiprovidersgo.md
rename to docs/content/stories/phase1/1.1.2-create-internaldiprovidersgo.md
diff --git a/docs/stories/phase1/1.1.3-add-internaldicore_modulego.md b/docs/content/stories/phase1/1.1.3-add-internaldicore_modulego.md
similarity index 100%
rename from docs/stories/phase1/1.1.3-add-internaldicore_modulego.md
rename to docs/content/stories/phase1/1.1.3-add-internaldicore_modulego.md
diff --git a/docs/stories/phase1/1.2.1-install-entgoioentcmdent.md b/docs/content/stories/phase1/1.2.1-install-entgoioentcmdent.md
similarity index 100%
rename from docs/stories/phase1/1.2.1-install-entgoioentcmdent.md
rename to docs/content/stories/phase1/1.2.1-install-entgoioentcmdent.md
diff --git a/docs/stories/phase1/1.2.2-initialize-ent-schema.md b/docs/content/stories/phase1/1.2.2-initialize-ent-schema.md
similarity index 100%
rename from docs/stories/phase1/1.2.2-initialize-ent-schema.md
rename to docs/content/stories/phase1/1.2.2-initialize-ent-schema.md
diff --git a/docs/stories/phase1/1.2.3-define-core-entities-in-internalentschema.md b/docs/content/stories/phase1/1.2.3-define-core-entities-in-internalentschema.md
similarity index 100%
rename from docs/stories/phase1/1.2.3-define-core-entities-in-internalentschema.md
rename to docs/content/stories/phase1/1.2.3-define-core-entities-in-internalentschema.md
diff --git a/docs/stories/phase1/1.2.4-generate-ent-code-go-generate-internalent.md b/docs/content/stories/phase1/1.2.4-generate-ent-code-go-generate-internalent.md
similarity index 100%
rename from docs/stories/phase1/1.2.4-generate-ent-code-go-generate-internalent.md
rename to docs/content/stories/phase1/1.2.4-generate-ent-code-go-generate-internalent.md
diff --git a/docs/stories/phase1/1.2.5-create-internalinfradatabaseclientgo.md b/docs/content/stories/phase1/1.2.5-create-internalinfradatabaseclientgo.md
similarity index 100%
rename from docs/stories/phase1/1.2.5-create-internalinfradatabaseclientgo.md
rename to docs/content/stories/phase1/1.2.5-create-internalinfradatabaseclientgo.md
diff --git a/docs/stories/phase1/1.2.6-add-database-config-to-configdefaultyaml.md b/docs/content/stories/phase1/1.2.6-add-database-config-to-configdefaultyaml.md
similarity index 100%
rename from docs/stories/phase1/1.2.6-add-database-config-to-configdefaultyaml.md
rename to docs/content/stories/phase1/1.2.6-add-database-config-to-configdefaultyaml.md
diff --git a/docs/stories/phase1/1.3.1-install-githubcomprometheusclient_golangprometheus.md b/docs/content/stories/phase1/1.3.1-install-githubcomprometheusclient_golangprometheus.md
similarity index 100%
rename from docs/stories/phase1/1.3.1-install-githubcomprometheusclient_golangprometheus.md
rename to docs/content/stories/phase1/1.3.1-install-githubcomprometheusclient_golangprometheus.md
diff --git a/docs/stories/phase1/1.3.2-install-githubcomheptiolabshealthcheck-optional-or.md b/docs/content/stories/phase1/1.3.2-install-githubcomheptiolabshealthcheck-optional-or.md
similarity index 100%
rename from docs/stories/phase1/1.3.2-install-githubcomheptiolabshealthcheck-optional-or.md
rename to docs/content/stories/phase1/1.3.2-install-githubcomheptiolabshealthcheck-optional-or.md
diff --git a/docs/stories/phase1/1.3.3-create-pkghealthhealthgo-interface.md b/docs/content/stories/phase1/1.3.3-create-pkghealthhealthgo-interface.md
similarity index 100%
rename from docs/stories/phase1/1.3.3-create-pkghealthhealthgo-interface.md
rename to docs/content/stories/phase1/1.3.3-create-pkghealthhealthgo-interface.md
diff --git a/docs/stories/phase1/1.3.4-implement-internalhealthregistrygo.md b/docs/content/stories/phase1/1.3.4-implement-internalhealthregistrygo.md
similarity index 100%
rename from docs/stories/phase1/1.3.4-implement-internalhealthregistrygo.md
rename to docs/content/stories/phase1/1.3.4-implement-internalhealthregistrygo.md
diff --git a/docs/stories/phase1/1.3.5-create-internalmetricsmetricsgo.md b/docs/content/stories/phase1/1.3.5-create-internalmetricsmetricsgo.md
similarity index 100%
rename from docs/stories/phase1/1.3.5-create-internalmetricsmetricsgo.md
rename to docs/content/stories/phase1/1.3.5-create-internalmetricsmetricsgo.md
diff --git a/docs/stories/phase1/1.3.6-add-metrics-endpoint-prometheus-format.md b/docs/content/stories/phase1/1.3.6-add-metrics-endpoint-prometheus-format.md
similarity index 100%
rename from docs/stories/phase1/1.3.6-add-metrics-endpoint-prometheus-format.md
rename to docs/content/stories/phase1/1.3.6-add-metrics-endpoint-prometheus-format.md
diff --git a/docs/stories/phase1/1.3.7-register-endpoints-in-main-http-router.md b/docs/content/stories/phase1/1.3.7-register-endpoints-in-main-http-router.md
similarity index 100%
rename from docs/stories/phase1/1.3.7-register-endpoints-in-main-http-router.md
rename to docs/content/stories/phase1/1.3.7-register-endpoints-in-main-http-router.md
diff --git a/docs/stories/phase1/1.4.1-create-pkgerrorbuserrorbusgo-interface.md b/docs/content/stories/phase1/1.4.1-create-pkgerrorbuserrorbusgo-interface.md
similarity index 100%
rename from docs/stories/phase1/1.4.1-create-pkgerrorbuserrorbusgo-interface.md
rename to docs/content/stories/phase1/1.4.1-create-pkgerrorbuserrorbusgo-interface.md
diff --git a/docs/stories/phase1/1.4.2-implement-internalerrorbuschannel_busgo.md b/docs/content/stories/phase1/1.4.2-implement-internalerrorbuschannel_busgo.md
similarity index 100%
rename from docs/stories/phase1/1.4.2-implement-internalerrorbuschannel_busgo.md
rename to docs/content/stories/phase1/1.4.2-implement-internalerrorbuschannel_busgo.md
diff --git a/docs/stories/phase1/1.4.3-add-panic-recovery-middleware-that-publishes-to-er.md b/docs/content/stories/phase1/1.4.3-add-panic-recovery-middleware-that-publishes-to-er.md
similarity index 100%
rename from docs/stories/phase1/1.4.3-add-panic-recovery-middleware-that-publishes-to-er.md
rename to docs/content/stories/phase1/1.4.3-add-panic-recovery-middleware-that-publishes-to-er.md
diff --git a/docs/stories/phase1/1.4.4-register-error-bus-in-di-container.md b/docs/content/stories/phase1/1.4.4-register-error-bus-in-di-container.md
similarity index 100%
rename from docs/stories/phase1/1.4.4-register-error-bus-in-di-container.md
rename to docs/content/stories/phase1/1.4.4-register-error-bus-in-di-container.md
diff --git a/docs/stories/phase1/1.5.1-install-githubcomgin-gonicgin.md b/docs/content/stories/phase1/1.5.1-install-githubcomgin-gonicgin.md
similarity index 100%
rename from docs/stories/phase1/1.5.1-install-githubcomgin-gonicgin.md
rename to docs/content/stories/phase1/1.5.1-install-githubcomgin-gonicgin.md
diff --git a/docs/stories/phase1/1.5.2-create-internalserverservergo.md b/docs/content/stories/phase1/1.5.2-create-internalserverservergo.md
similarity index 100%
rename from docs/stories/phase1/1.5.2-create-internalserverservergo.md
rename to docs/content/stories/phase1/1.5.2-create-internalserverservergo.md
diff --git a/docs/stories/phase1/1.5.3-wire-http-server-into-fx-lifecycle.md b/docs/content/stories/phase1/1.5.3-wire-http-server-into-fx-lifecycle.md
similarity index 100%
rename from docs/stories/phase1/1.5.3-wire-http-server-into-fx-lifecycle.md
rename to docs/content/stories/phase1/1.5.3-wire-http-server-into-fx-lifecycle.md
diff --git a/docs/stories/phase1/1.5.4-update-cmdplatformmaingo-to-use-fx-lifecycle.md b/docs/content/stories/phase1/1.5.4-update-cmdplatformmaingo-to-use-fx-lifecycle.md
similarity index 100%
rename from docs/stories/phase1/1.5.4-update-cmdplatformmaingo-to-use-fx-lifecycle.md
rename to docs/content/stories/phase1/1.5.4-update-cmdplatformmaingo-to-use-fx-lifecycle.md
diff --git a/docs/stories/phase1/1.6.1-install-opentelemetry-packages.md b/docs/content/stories/phase1/1.6.1-install-opentelemetry-packages.md
similarity index 100%
rename from docs/stories/phase1/1.6.1-install-opentelemetry-packages.md
rename to docs/content/stories/phase1/1.6.1-install-opentelemetry-packages.md
diff --git a/docs/stories/phase1/1.6.2-create-internalobservabilitytracergo.md b/docs/content/stories/phase1/1.6.2-create-internalobservabilitytracergo.md
similarity index 100%
rename from docs/stories/phase1/1.6.2-create-internalobservabilitytracergo.md
rename to docs/content/stories/phase1/1.6.2-create-internalobservabilitytracergo.md
diff --git a/docs/stories/phase1/1.6.3-add-http-instrumentation-middleware.md b/docs/content/stories/phase1/1.6.3-add-http-instrumentation-middleware.md
similarity index 100%
rename from docs/stories/phase1/1.6.3-add-http-instrumentation-middleware.md
rename to docs/content/stories/phase1/1.6.3-add-http-instrumentation-middleware.md
diff --git a/docs/stories/phase1/1.6.4-add-trace-context-propagation-to-requests.md b/docs/content/stories/phase1/1.6.4-add-trace-context-propagation-to-requests.md
similarity index 100%
rename from docs/stories/phase1/1.6.4-add-trace-context-propagation-to-requests.md
rename to docs/content/stories/phase1/1.6.4-add-trace-context-propagation-to-requests.md
diff --git a/docs/content/stories/phase1/README.md b/docs/content/stories/phase1/README.md
new file mode 100644
index 0000000..64b8a47
--- /dev/null
+++ b/docs/content/stories/phase1/README.md
@@ -0,0 +1,64 @@
+# Phase 1: Core Kernel & Infrastructure
+
+## Overview
+Implement dependency injection container, set up database (Ent ORM), create health and metrics endpoints, implement error bus, and add basic HTTP server with middleware.
+
+## Tasks
+
+### 1.1 Dependency Injection Container
+- [1.1.1 - Extend DI Container](./1.1.1-extend-internaldicontainergo.md)
+- [1.1.2 - Create DI Providers](./1.1.2-create-internaldiprovidersgo.md)
+- [1.1.3 - Add Core Module](./1.1.3-add-internaldicore_modulego.md)
+
+### 1.2 Database Setup (Ent)
+- [1.2.1 - Install Ent](./1.2.1-install-entgoioentcmdent.md)
+- [1.2.2 - Initialize Ent Schema](./1.2.2-initialize-ent-schema.md)
+- [1.2.3 - Define Core Entities](./1.2.3-define-core-entities-in-internalentschema.md)
+- [1.2.4 - Generate Ent Code](./1.2.4-generate-ent-code-go-generate-internalent.md)
+- [1.2.5 - Create Database Client](./1.2.5-create-internalinfradatabaseclientgo.md)
+- [1.2.6 - Add Database Config](./1.2.6-add-database-config-to-configdefaultyaml.md)
+
+### 1.3 Health & Metrics
+- [1.3.1 - Install Prometheus](./1.3.1-install-githubcomprometheusclient_golangprometheus.md)
+- [1.3.2 - Install Health Check](./1.3.2-install-githubcomheptiolabshealthcheck-optional-or.md)
+- [1.3.3 - Create Health Interface](./1.3.3-create-pkghealthhealthgo-interface.md)
+- [1.3.4 - Implement Health Registry](./1.3.4-implement-internalhealthregistrygo.md)
+- [1.3.5 - Create Metrics](./1.3.5-create-internalmetricsmetricsgo.md)
+- [1.3.6 - Add Metrics Endpoint](./1.3.6-add-metrics-endpoint-prometheus-format.md)
+- [1.3.7 - Register Endpoints](./1.3.7-register-endpoints-in-main-http-router.md)
+
+### 1.4 Error Bus
+- [1.4.1 - Create Error Bus Interface](./1.4.1-create-pkgerrorbuserrorbusgo-interface.md)
+- [1.4.2 - Implement Channel Bus](./1.4.2-implement-internalerrorbuschannel_busgo.md)
+- [1.4.3 - Add Panic Recovery Middleware](./1.4.3-add-panic-recovery-middleware-that-publishes-to-er.md)
+- [1.4.4 - Register Error Bus](./1.4.4-register-error-bus-in-di-container.md)
+
+### 1.5 HTTP Server Foundation
+- [1.5.1 - Install Gin](./1.5.1-install-githubcomgin-gonicgin.md)
+- [1.5.2 - Create Server](./1.5.2-create-internalserverservergo.md)
+- [1.5.3 - Wire HTTP Server](./1.5.3-wire-http-server-into-fx-lifecycle.md)
+- [1.5.4 - Update Main Entry Point](./1.5.4-update-cmdplatformmaingo-to-use-fx-lifecycle.md)
+
+### 1.6 Observability (OpenTelemetry)
+- [1.6.1 - Install OpenTelemetry](./1.6.1-install-opentelemetry-packages.md)
+- [1.6.2 - Create Tracer](./1.6.2-create-internalobservabilitytracergo.md)
+- [1.6.3 - Add HTTP Instrumentation](./1.6.3-add-http-instrumentation-middleware.md)
+- [1.6.4 - Add Trace Context Propagation](./1.6.4-add-trace-context-propagation-to-requests.md)
+
+## Deliverables Checklist
+- [ ] DI container with all core services registered
+- [ ] Database schema defined with Ent
+- [ ] Health check endpoints working
+- [ ] Metrics endpoint exposed
+- [ ] Error bus implemented and integrated
+- [ ] HTTP server with middleware stack
+- [ ] OpenTelemetry tracing integrated
+
+## Acceptance Criteria
+- `GET /healthz` returns 200
+- `GET /ready` checks database connectivity
+- `GET /metrics` returns Prometheus metrics
+- HTTP requests are logged with structured logging
+- Panic recovery middleware catches and reports errors
+- OpenTelemetry traces are generated for HTTP requests
+
diff --git a/docs/stories/phase2/2.1.1-install-githubcomgolang-jwtjwtv5.md b/docs/content/stories/phase2/2.1.1-install-githubcomgolang-jwtjwtv5.md
similarity index 100%
rename from docs/stories/phase2/2.1.1-install-githubcomgolang-jwtjwtv5.md
rename to docs/content/stories/phase2/2.1.1-install-githubcomgolang-jwtjwtv5.md
diff --git a/docs/stories/phase2/2.1.2-create-pkgauthauthgo-interfaces.md b/docs/content/stories/phase2/2.1.2-create-pkgauthauthgo-interfaces.md
similarity index 100%
rename from docs/stories/phase2/2.1.2-create-pkgauthauthgo-interfaces.md
rename to docs/content/stories/phase2/2.1.2-create-pkgauthauthgo-interfaces.md
diff --git a/docs/stories/phase2/2.1.3-implement-internalauthjwt_authgo.md b/docs/content/stories/phase2/2.1.3-implement-internalauthjwt_authgo.md
similarity index 100%
rename from docs/stories/phase2/2.1.3-implement-internalauthjwt_authgo.md
rename to docs/content/stories/phase2/2.1.3-implement-internalauthjwt_authgo.md
diff --git a/docs/stories/phase2/2.1.4-create-internalauthmiddlewarego.md b/docs/content/stories/phase2/2.1.4-create-internalauthmiddlewarego.md
similarity index 100%
rename from docs/stories/phase2/2.1.4-create-internalauthmiddlewarego.md
rename to docs/content/stories/phase2/2.1.4-create-internalauthmiddlewarego.md
diff --git a/docs/stories/phase2/2.1.5-add-login-endpoint-post-apiv1authlogin.md b/docs/content/stories/phase2/2.1.5-add-login-endpoint-post-apiv1authlogin.md
similarity index 100%
rename from docs/stories/phase2/2.1.5-add-login-endpoint-post-apiv1authlogin.md
rename to docs/content/stories/phase2/2.1.5-add-login-endpoint-post-apiv1authlogin.md
diff --git a/docs/stories/phase2/2.1.6-add-refresh-endpoint-post-apiv1authrefresh.md b/docs/content/stories/phase2/2.1.6-add-refresh-endpoint-post-apiv1authrefresh.md
similarity index 100%
rename from docs/stories/phase2/2.1.6-add-refresh-endpoint-post-apiv1authrefresh.md
rename to docs/content/stories/phase2/2.1.6-add-refresh-endpoint-post-apiv1authrefresh.md
diff --git a/docs/stories/phase2/2.2.1-create-pkgidentityidentitygo-interfaces.md b/docs/content/stories/phase2/2.2.1-create-pkgidentityidentitygo-interfaces.md
similarity index 100%
rename from docs/stories/phase2/2.2.1-create-pkgidentityidentitygo-interfaces.md
rename to docs/content/stories/phase2/2.2.1-create-pkgidentityidentitygo-interfaces.md
diff --git a/docs/stories/phase2/2.2.2-implement-internalidentityuser_repogo-using-ent.md b/docs/content/stories/phase2/2.2.2-implement-internalidentityuser_repogo-using-ent.md
similarity index 100%
rename from docs/stories/phase2/2.2.2-implement-internalidentityuser_repogo-using-ent.md
rename to docs/content/stories/phase2/2.2.2-implement-internalidentityuser_repogo-using-ent.md
diff --git a/docs/stories/phase2/2.2.3-implement-internalidentityuser_servicego.md b/docs/content/stories/phase2/2.2.3-implement-internalidentityuser_servicego.md
similarity index 100%
rename from docs/stories/phase2/2.2.3-implement-internalidentityuser_servicego.md
rename to docs/content/stories/phase2/2.2.3-implement-internalidentityuser_servicego.md
diff --git a/docs/stories/phase2/2.2.4-add-endpoints.md b/docs/content/stories/phase2/2.2.4-add-endpoints.md
similarity index 100%
rename from docs/stories/phase2/2.2.4-add-endpoints.md
rename to docs/content/stories/phase2/2.2.4-add-endpoints.md
diff --git a/docs/stories/phase2/2.3.1-create-pkgpermpermgo.md b/docs/content/stories/phase2/2.3.1-create-pkgpermpermgo.md
similarity index 100%
rename from docs/stories/phase2/2.3.1-create-pkgpermpermgo.md
rename to docs/content/stories/phase2/2.3.1-create-pkgpermpermgo.md
diff --git a/docs/stories/phase2/2.3.2-create-pkgpermresolvergo-interface.md b/docs/content/stories/phase2/2.3.2-create-pkgpermresolvergo-interface.md
similarity index 100%
rename from docs/stories/phase2/2.3.2-create-pkgpermresolvergo-interface.md
rename to docs/content/stories/phase2/2.3.2-create-pkgpermresolvergo-interface.md
diff --git a/docs/stories/phase2/2.3.3-implement-internalpermin_memory_resolvergo.md b/docs/content/stories/phase2/2.3.3-implement-internalpermin_memory_resolvergo.md
similarity index 100%
rename from docs/stories/phase2/2.3.3-implement-internalpermin_memory_resolvergo.md
rename to docs/content/stories/phase2/2.3.3-implement-internalpermin_memory_resolvergo.md
diff --git a/docs/stories/phase2/2.3.4-create-pkgauthauthzgo-interface.md b/docs/content/stories/phase2/2.3.4-create-pkgauthauthzgo-interface.md
similarity index 100%
rename from docs/stories/phase2/2.3.4-create-pkgauthauthzgo-interface.md
rename to docs/content/stories/phase2/2.3.4-create-pkgauthauthzgo-interface.md
diff --git a/docs/stories/phase2/2.3.5-implement-internalauthrbac_authorizergo.md b/docs/content/stories/phase2/2.3.5-implement-internalauthrbac_authorizergo.md
similarity index 100%
rename from docs/stories/phase2/2.3.5-implement-internalauthrbac_authorizergo.md
rename to docs/content/stories/phase2/2.3.5-implement-internalauthrbac_authorizergo.md
diff --git a/docs/stories/phase2/2.3.6-create-authorization-middleware.md b/docs/content/stories/phase2/2.3.6-create-authorization-middleware.md
similarity index 100%
rename from docs/stories/phase2/2.3.6-create-authorization-middleware.md
rename to docs/content/stories/phase2/2.3.6-create-authorization-middleware.md
diff --git a/docs/stories/phase2/2.4.1-create-internalidentityrole_repogo.md b/docs/content/stories/phase2/2.4.1-create-internalidentityrole_repogo.md
similarity index 100%
rename from docs/stories/phase2/2.4.1-create-internalidentityrole_repogo.md
rename to docs/content/stories/phase2/2.4.1-create-internalidentityrole_repogo.md
diff --git a/docs/stories/phase2/2.4.2-add-endpoints.md b/docs/content/stories/phase2/2.4.2-add-endpoints.md
similarity index 100%
rename from docs/stories/phase2/2.4.2-add-endpoints.md
rename to docs/content/stories/phase2/2.4.2-add-endpoints.md
diff --git a/docs/stories/phase2/2.5.1-create-pkgauditauditgo-interface.md b/docs/content/stories/phase2/2.5.1-create-pkgauditauditgo-interface.md
similarity index 100%
rename from docs/stories/phase2/2.5.1-create-pkgauditauditgo-interface.md
rename to docs/content/stories/phase2/2.5.1-create-pkgauditauditgo-interface.md
diff --git a/docs/stories/phase2/2.5.2-implement-internalauditent_auditorgo.md b/docs/content/stories/phase2/2.5.2-implement-internalauditent_auditorgo.md
similarity index 100%
rename from docs/stories/phase2/2.5.2-implement-internalauditent_auditorgo.md
rename to docs/content/stories/phase2/2.5.2-implement-internalauditent_auditorgo.md
diff --git a/docs/stories/phase2/2.5.3-add-audit-middleware.md b/docs/content/stories/phase2/2.5.3-add-audit-middleware.md
similarity index 100%
rename from docs/stories/phase2/2.5.3-add-audit-middleware.md
rename to docs/content/stories/phase2/2.5.3-add-audit-middleware.md
diff --git a/docs/stories/phase2/2.5.4-integrate-with-auth-endpoints.md b/docs/content/stories/phase2/2.5.4-integrate-with-auth-endpoints.md
similarity index 100%
rename from docs/stories/phase2/2.5.4-integrate-with-auth-endpoints.md
rename to docs/content/stories/phase2/2.5.4-integrate-with-auth-endpoints.md
diff --git a/docs/stories/phase2/2.6.1-create-internalseedseedgo.md b/docs/content/stories/phase2/2.6.1-create-internalseedseedgo.md
similarity index 100%
rename from docs/stories/phase2/2.6.1-create-internalseedseedgo.md
rename to docs/content/stories/phase2/2.6.1-create-internalseedseedgo.md
diff --git a/docs/content/stories/phase2/README.md b/docs/content/stories/phase2/README.md
new file mode 100644
index 0000000..4feb3f2
--- /dev/null
+++ b/docs/content/stories/phase2/README.md
@@ -0,0 +1,58 @@
+# Phase 2: Authentication & Authorization
+
+## Overview
+Implement JWT authentication, create identity management (User CRUD), build role and permission system, add authorization middleware, and implement audit logging.
+
+## Tasks
+
+### 2.1 Authentication (JWT)
+- [2.1.1 - Install JWT Library](./2.1.1-install-githubcomgolang-jwtjwtv5.md)
+- [2.1.2 - Create Auth Interfaces](./2.1.2-create-pkgauthauthgo-interfaces.md)
+- [2.1.3 - Implement JWT Auth](./2.1.3-implement-internalauthjwt_authgo.md)
+- [2.1.4 - Create Auth Middleware](./2.1.4-create-internalauthmiddlewarego.md)
+- [2.1.5 - Add Login Endpoint](./2.1.5-add-login-endpoint-post-apiv1authlogin.md)
+- [2.1.6 - Add Refresh Endpoint](./2.1.6-add-refresh-endpoint-post-apiv1authrefresh.md)
+
+### 2.2 Identity Management
+- [2.2.1 - Create Identity Interfaces](./2.2.1-create-pkgidentityidentitygo-interfaces.md)
+- [2.2.2 - Implement User Repository](./2.2.2-implement-internalidentityuser_repogo-using-ent.md)
+- [2.2.3 - Implement User Service](./2.2.3-implement-internalidentityuser_servicego.md)
+- [2.2.4 - Add Endpoints](./2.2.4-add-endpoints.md)
+
+### 2.3 Roles & Permissions
+- [2.3.1 - Create Permission Types](./2.3.1-create-pkgpermpermgo.md)
+- [2.3.2 - Create Permission Resolver Interface](./2.3.2-create-pkgpermresolvergo-interface.md)
+- [2.3.3 - Implement In-Memory Resolver](./2.3.3-implement-internalpermin_memory_resolvergo.md)
+- [2.3.4 - Create Authorization Interface](./2.3.4-create-pkgauthauthzgo-interface.md)
+- [2.3.5 - Implement RBAC Authorizer](./2.3.5-implement-internalauthrbac_authorizergo.md)
+- [2.3.6 - Create Authorization Middleware](./2.3.6-create-authorization-middleware.md)
+
+### 2.4 Role Management
+- [2.4.1 - Create Role Repository](./2.4.1-create-internalidentityrole_repogo.md)
+- [2.4.2 - Add Endpoints](./2.4.2-add-endpoints.md)
+
+### 2.5 Audit Logging
+- [2.5.1 - Create Audit Interface](./2.5.1-create-pkgauditauditgo-interface.md)
+- [2.5.2 - Implement Ent Auditor](./2.5.2-implement-internalauditent_auditorgo.md)
+- [2.5.3 - Add Audit Middleware](./2.5.3-add-audit-middleware.md)
+- [2.5.4 - Integrate with Auth Endpoints](./2.5.4-integrate-with-auth-endpoints.md)
+
+### 2.6 Database Seeding
+- [2.6.1 - Create Seed Script](./2.6.1-create-internalseedseedgo.md)
+
+## Deliverables Checklist
+- [ ] JWT authentication working (access + refresh tokens)
+- [ ] User registration and management endpoints
+- [ ] Role and permission system implemented
+- [ ] Authorization middleware protecting endpoints
+- [ ] Audit logging captures all auth actions
+- [ ] Database seeding for initial admin user
+
+## Acceptance Criteria
+- `POST /api/v1/auth/login` returns JWT tokens
+- `POST /api/v1/auth/refresh` issues new access token
+- Protected endpoints require valid JWT
+- Authorization middleware checks permissions
+- All auth actions are logged to audit table
+- Admin user can be created via seed script
+
diff --git a/docs/stories/phase3/3.1.1-create-pkgmodulemodulego.md b/docs/content/stories/phase3/3.1.1-create-pkgmodulemodulego.md
similarity index 100%
rename from docs/stories/phase3/3.1.1-create-pkgmodulemodulego.md
rename to docs/content/stories/phase3/3.1.1-create-pkgmodulemodulego.md
diff --git a/docs/stories/phase3/3.1.2-create-pkgmodulemanifestgo.md b/docs/content/stories/phase3/3.1.2-create-pkgmodulemanifestgo.md
similarity index 100%
rename from docs/stories/phase3/3.1.2-create-pkgmodulemanifestgo.md
rename to docs/content/stories/phase3/3.1.2-create-pkgmodulemanifestgo.md
diff --git a/docs/stories/phase3/3.1.3-define-moduleyaml-schema-used-for-code-generation.md b/docs/content/stories/phase3/3.1.3-define-moduleyaml-schema-used-for-code-generation.md
similarity index 100%
rename from docs/stories/phase3/3.1.3-define-moduleyaml-schema-used-for-code-generation.md
rename to docs/content/stories/phase3/3.1.3-define-moduleyaml-schema-used-for-code-generation.md
diff --git a/docs/stories/phase3/3.2.1-create-internalregistryregistrygo.md b/docs/content/stories/phase3/3.2.1-create-internalregistryregistrygo.md
similarity index 100%
rename from docs/stories/phase3/3.2.1-create-internalregistryregistrygo.md
rename to docs/content/stories/phase3/3.2.1-create-internalregistryregistrygo.md
diff --git a/docs/stories/phase3/3.2.2-add-registration-validation.md b/docs/content/stories/phase3/3.2.2-add-registration-validation.md
similarity index 100%
rename from docs/stories/phase3/3.2.2-add-registration-validation.md
rename to docs/content/stories/phase3/3.2.2-add-registration-validation.md
diff --git a/docs/stories/phase3/3.3.1-create-scriptsgenerate-permissionsgo.md b/docs/content/stories/phase3/3.3.1-create-scriptsgenerate-permissionsgo.md
similarity index 100%
rename from docs/stories/phase3/3.3.1-create-scriptsgenerate-permissionsgo.md
rename to docs/content/stories/phase3/3.3.1-create-scriptsgenerate-permissionsgo.md
diff --git a/docs/stories/phase3/3.3.2-add-gogenerate-directive-to-pkgpermpermgo.md b/docs/content/stories/phase3/3.3.2-add-gogenerate-directive-to-pkgpermpermgo.md
similarity index 100%
rename from docs/stories/phase3/3.3.2-add-gogenerate-directive-to-pkgpermpermgo.md
rename to docs/content/stories/phase3/3.3.2-add-gogenerate-directive-to-pkgpermpermgo.md
diff --git a/docs/stories/phase3/3.3.3-update-makefile-with-make-generate-command.md b/docs/content/stories/phase3/3.3.3-update-makefile-with-make-generate-command.md
similarity index 100%
rename from docs/stories/phase3/3.3.3-update-makefile-with-make-generate-command.md
rename to docs/content/stories/phase3/3.3.3-update-makefile-with-make-generate-command.md
diff --git a/docs/stories/phase3/3.4.1-create-internalpluginloaderloadergo.md b/docs/content/stories/phase3/3.4.1-create-internalpluginloaderloadergo.md
similarity index 100%
rename from docs/stories/phase3/3.4.1-create-internalpluginloaderloadergo.md
rename to docs/content/stories/phase3/3.4.1-create-internalpluginloaderloadergo.md
diff --git a/docs/stories/phase3/3.4.2-implement-internalpluginloaderstatic_loadergo.md b/docs/content/stories/phase3/3.4.2-implement-internalpluginloaderstatic_loadergo.md
similarity index 100%
rename from docs/stories/phase3/3.4.2-implement-internalpluginloaderstatic_loadergo.md
rename to docs/content/stories/phase3/3.4.2-implement-internalpluginloaderstatic_loadergo.md
diff --git a/docs/stories/phase3/3.4.3-implement-internalpluginloaderplugin_loadergo-opti.md b/docs/content/stories/phase3/3.4.3-implement-internalpluginloaderplugin_loadergo-opti.md
similarity index 100%
rename from docs/stories/phase3/3.4.3-implement-internalpluginloaderplugin_loadergo-opti.md
rename to docs/content/stories/phase3/3.4.3-implement-internalpluginloaderplugin_loadergo-opti.md
diff --git a/docs/stories/phase3/3.5.1-create-internalmoduleinitializergo.md b/docs/content/stories/phase3/3.5.1-create-internalmoduleinitializergo.md
similarity index 100%
rename from docs/stories/phase3/3.5.1-create-internalmoduleinitializergo.md
rename to docs/content/stories/phase3/3.5.1-create-internalmoduleinitializergo.md
diff --git a/docs/stories/phase3/3.5.2-run-migrations.md b/docs/content/stories/phase3/3.5.2-run-migrations.md
similarity index 100%
rename from docs/stories/phase3/3.5.2-run-migrations.md
rename to docs/content/stories/phase3/3.5.2-run-migrations.md
diff --git a/docs/stories/phase3/3.6.1-extend-pkgmodulemodulego.md b/docs/content/stories/phase3/3.6.1-extend-pkgmodulemodulego.md
similarity index 100%
rename from docs/stories/phase3/3.6.1-extend-pkgmodulemodulego.md
rename to docs/content/stories/phase3/3.6.1-extend-pkgmodulemodulego.md
diff --git a/docs/stories/phase3/3.6.2-integrate-with-fxlifecycle.md b/docs/content/stories/phase3/3.6.2-integrate-with-fxlifecycle.md
similarity index 100%
rename from docs/stories/phase3/3.6.2-integrate-with-fxlifecycle.md
rename to docs/content/stories/phase3/3.6.2-integrate-with-fxlifecycle.md
diff --git a/docs/stories/phase3/3.7.1-create-cmdplatformctlmaingo.md b/docs/content/stories/phase3/3.7.1-create-cmdplatformctlmaingo.md
similarity index 100%
rename from docs/stories/phase3/3.7.1-create-cmdplatformctlmaingo.md
rename to docs/content/stories/phase3/3.7.1-create-cmdplatformctlmaingo.md
diff --git a/docs/stories/phase3/3.7.2-add-to-makefile-make-install-cli.md b/docs/content/stories/phase3/3.7.2-add-to-makefile-make-install-cli.md
similarity index 100%
rename from docs/stories/phase3/3.7.2-add-to-makefile-make-install-cli.md
rename to docs/content/stories/phase3/3.7.2-add-to-makefile-make-install-cli.md
diff --git a/docs/content/stories/phase3/README.md b/docs/content/stories/phase3/README.md
new file mode 100644
index 0000000..81d8078
--- /dev/null
+++ b/docs/content/stories/phase3/README.md
@@ -0,0 +1,54 @@
+# Phase 3: Module Framework
+
+## Overview
+Define module interface and registration system, implement static module registry, create permission code generation tool, build module loader (support both static and plugin modes), and add module discovery and initialization.
+
+## Tasks
+
+### 3.1 Module Interface
+- [3.1.1 - Create Module Interface](./3.1.1-create-pkgmodulemodulego.md)
+- [3.1.2 - Create Module Manifest](./3.1.2-create-pkgmodulemanifestgo.md)
+- [3.1.3 - Define Module YAML Schema](./3.1.3-define-moduleyaml-schema-used-for-code-generation.md)
+
+### 3.2 Static Module Registry
+- [3.2.1 - Create Registry](./3.2.1-create-internalregistryregistrygo.md)
+- [3.2.2 - Add Registration Validation](./3.2.2-add-registration-validation.md)
+
+### 3.3 Permission Code Generation
+- [3.3.1 - Create Generate Script](./3.3.1-create-scriptsgenerate-permissionsgo.md)
+- [3.3.2 - Add Go Generate Directive](./3.3.2-add-gogenerate-directive-to-pkgpermpermgo.md)
+- [3.3.3 - Update Makefile](./3.3.3-update-makefile-with-make-generate-command.md)
+
+### 3.4 Module Loader
+- [3.4.1 - Create Loader Interface](./3.4.1-create-internalpluginloaderloadergo.md)
+- [3.4.2 - Implement Static Loader](./3.4.2-implement-internalpluginloaderstatic_loadergo.md)
+- [3.4.3 - Implement Plugin Loader](./3.4.3-implement-internalpluginloaderplugin_loadergo-opti.md)
+
+### 3.5 Module Initialization
+- [3.5.1 - Create Initializer](./3.5.1-create-internalmoduleinitializergo.md)
+- [3.5.2 - Run Migrations](./3.5.2-run-migrations.md)
+
+### 3.6 Module Lifecycle
+- [3.6.1 - Extend Module Interface](./3.6.1-extend-pkgmodulemodulego.md)
+- [3.6.2 - Integrate with FX Lifecycle](./3.6.2-integrate-with-fxlifecycle.md)
+
+### 3.7 Platform CLI
+- [3.7.1 - Create CLI Tool](./3.7.1-create-cmdplatformctlmaingo.md)
+- [3.7.2 - Add to Makefile](./3.7.2-add-to-makefile-make-install-cli.md)
+
+## Deliverables Checklist
+- [ ] Module interface defined
+- [ ] Static module registry implemented
+- [ ] Permission code generation working
+- [ ] Module loader supports static and plugin modes
+- [ ] Modules can be discovered and initialized
+- [ ] Module migrations run on startup
+- [ ] Platform CLI tool for module management
+
+## Acceptance Criteria
+- Modules can be registered statically
+- Permission constants are generated from module manifests
+- Modules are initialized with correct dependency order
+- Module migrations run automatically
+- CLI tool can list and manage modules
+
diff --git a/docs/stories/phase4/4.1.1-create-modulesblog-directory.md b/docs/content/stories/phase4/4.1.1-create-modulesblog-directory.md
similarity index 100%
rename from docs/stories/phase4/4.1.1-create-modulesblog-directory.md
rename to docs/content/stories/phase4/4.1.1-create-modulesblog-directory.md
diff --git a/docs/stories/phase4/4.1.2-initialize-gomod.md b/docs/content/stories/phase4/4.1.2-initialize-gomod.md
similarity index 100%
rename from docs/stories/phase4/4.1.2-initialize-gomod.md
rename to docs/content/stories/phase4/4.1.2-initialize-gomod.md
diff --git a/docs/stories/phase4/4.2.1-create-modulesblogmoduleyaml.md b/docs/content/stories/phase4/4.2.1-create-modulesblogmoduleyaml.md
similarity index 100%
rename from docs/stories/phase4/4.2.1-create-modulesblogmoduleyaml.md
rename to docs/content/stories/phase4/4.2.1-create-modulesblogmoduleyaml.md
diff --git a/docs/stories/phase4/4.3.1-create-modulesbloginternaldomainpostgo.md b/docs/content/stories/phase4/4.3.1-create-modulesbloginternaldomainpostgo.md
similarity index 100%
rename from docs/stories/phase4/4.3.1-create-modulesbloginternaldomainpostgo.md
rename to docs/content/stories/phase4/4.3.1-create-modulesbloginternaldomainpostgo.md
diff --git a/docs/stories/phase4/4.3.2-create-ent-schema-modulesbloginternalentschemapost.md b/docs/content/stories/phase4/4.3.2-create-ent-schema-modulesbloginternalentschemapost.md
similarity index 100%
rename from docs/stories/phase4/4.3.2-create-ent-schema-modulesbloginternalentschemapost.md
rename to docs/content/stories/phase4/4.3.2-create-ent-schema-modulesbloginternalentschemapost.md
diff --git a/docs/stories/phase4/4.3.3-generate-ent-code-for-blog-module.md b/docs/content/stories/phase4/4.3.3-generate-ent-code-for-blog-module.md
similarity index 100%
rename from docs/stories/phase4/4.3.3-generate-ent-code-for-blog-module.md
rename to docs/content/stories/phase4/4.3.3-generate-ent-code-for-blog-module.md
diff --git a/docs/stories/phase4/4.4.1-create-modulesbloginternaldomainpost_repogo.md b/docs/content/stories/phase4/4.4.1-create-modulesbloginternaldomainpost_repogo.md
similarity index 100%
rename from docs/stories/phase4/4.4.1-create-modulesbloginternaldomainpost_repogo.md
rename to docs/content/stories/phase4/4.4.1-create-modulesbloginternaldomainpost_repogo.md
diff --git a/docs/stories/phase4/4.4.2-implement-using-ent-client-shared-from-core.md b/docs/content/stories/phase4/4.4.2-implement-using-ent-client-shared-from-core.md
similarity index 100%
rename from docs/stories/phase4/4.4.2-implement-using-ent-client-shared-from-core.md
rename to docs/content/stories/phase4/4.4.2-implement-using-ent-client-shared-from-core.md
diff --git a/docs/stories/phase4/4.5.1-create-modulesbloginternalservicepost_servicego.md b/docs/content/stories/phase4/4.5.1-create-modulesbloginternalservicepost_servicego.md
similarity index 100%
rename from docs/stories/phase4/4.5.1-create-modulesbloginternalservicepost_servicego.md
rename to docs/content/stories/phase4/4.5.1-create-modulesbloginternalservicepost_servicego.md
diff --git a/docs/stories/phase4/4.6.1-create-modulesbloginternalapihandlergo.md b/docs/content/stories/phase4/4.6.1-create-modulesbloginternalapihandlergo.md
similarity index 100%
rename from docs/stories/phase4/4.6.1-create-modulesbloginternalapihandlergo.md
rename to docs/content/stories/phase4/4.6.1-create-modulesbloginternalapihandlergo.md
diff --git a/docs/stories/phase4/4.6.2-use-authorization-middleware.md b/docs/content/stories/phase4/4.6.2-use-authorization-middleware.md
similarity index 100%
rename from docs/stories/phase4/4.6.2-use-authorization-middleware.md
rename to docs/content/stories/phase4/4.6.2-use-authorization-middleware.md
diff --git a/docs/stories/phase4/4.6.3-register-handlers-in-modules-init.md b/docs/content/stories/phase4/4.6.3-register-handlers-in-modules-init.md
similarity index 100%
rename from docs/stories/phase4/4.6.3-register-handlers-in-modules-init.md
rename to docs/content/stories/phase4/4.6.3-register-handlers-in-modules-init.md
diff --git a/docs/stories/phase4/4.7.1-create-modulesblogpkgmodulego.md b/docs/content/stories/phase4/4.7.1-create-modulesblogpkgmodulego.md
similarity index 100%
rename from docs/stories/phase4/4.7.1-create-modulesblogpkgmodulego.md
rename to docs/content/stories/phase4/4.7.1-create-modulesblogpkgmodulego.md
diff --git a/docs/stories/phase4/4.8.1-update-main-gomod-to-include-blog-module.md b/docs/content/stories/phase4/4.8.1-update-main-gomod-to-include-blog-module.md
similarity index 100%
rename from docs/stories/phase4/4.8.1-update-main-gomod-to-include-blog-module.md
rename to docs/content/stories/phase4/4.8.1-update-main-gomod-to-include-blog-module.md
diff --git a/docs/stories/phase4/4.8.2-import-blog-module-in-cmdplatformmaingo.md b/docs/content/stories/phase4/4.8.2-import-blog-module-in-cmdplatformmaingo.md
similarity index 100%
rename from docs/stories/phase4/4.8.2-import-blog-module-in-cmdplatformmaingo.md
rename to docs/content/stories/phase4/4.8.2-import-blog-module-in-cmdplatformmaingo.md
diff --git a/docs/stories/phase4/4.8.3-run-permission-generation-make-generate.md b/docs/content/stories/phase4/4.8.3-run-permission-generation-make-generate.md
similarity index 100%
rename from docs/stories/phase4/4.8.3-run-permission-generation-make-generate.md
rename to docs/content/stories/phase4/4.8.3-run-permission-generation-make-generate.md
diff --git a/docs/stories/phase4/4.8.4-verify-blog-permissions-are-generated.md b/docs/content/stories/phase4/4.8.4-verify-blog-permissions-are-generated.md
similarity index 100%
rename from docs/stories/phase4/4.8.4-verify-blog-permissions-are-generated.md
rename to docs/content/stories/phase4/4.8.4-verify-blog-permissions-are-generated.md
diff --git a/docs/stories/phase4/4.9.1-create-integration-test-modulesbloginternalapihand.md b/docs/content/stories/phase4/4.9.1-create-integration-test-modulesbloginternalapihand.md
similarity index 100%
rename from docs/stories/phase4/4.9.1-create-integration-test-modulesbloginternalapihand.md
rename to docs/content/stories/phase4/4.9.1-create-integration-test-modulesbloginternalapihand.md
diff --git a/docs/stories/phase4/4.9.2-add-unit-tests-for-service-and-repository.md b/docs/content/stories/phase4/4.9.2-add-unit-tests-for-service-and-repository.md
similarity index 100%
rename from docs/stories/phase4/4.9.2-add-unit-tests-for-service-and-repository.md
rename to docs/content/stories/phase4/4.9.2-add-unit-tests-for-service-and-repository.md
diff --git a/docs/content/stories/phase4/README.md b/docs/content/stories/phase4/README.md
new file mode 100644
index 0000000..8f49186
--- /dev/null
+++ b/docs/content/stories/phase4/README.md
@@ -0,0 +1,47 @@
+# Phase 4: Sample Feature Module (Blog)
+
+## Overview
+Create a sample blog module to demonstrate the module framework. This module will implement blog posts with CRUD operations, showing how to build a feature module that integrates with the core platform.
+
+## Tasks
+
+### 4.1 Module Setup
+- [4.1.1 - Create Blog Module Directory](./4.1.1-create-modulesblog-directory.md)
+- [4.1.2 - Initialize Go Module](./4.1.2-initialize-gomod.md)
+
+### 4.2 Module Configuration
+- [4.2.1 - Create Module Manifest](./4.2.1-create-modulesblogmoduleyaml.md)
+
+### 4.3 Domain Layer
+- [4.3.1 - Create Post Domain Model](./4.3.1-create-modulesbloginternaldomainpostgo.md)
+- [4.3.2 - Create Ent Schema](./4.3.2-create-modulesbloginternalentschemapost.md)
+- [4.3.3 - Generate Ent Code](./4.3.3-generate-ent-code-for-blog-module.md)
+
+### 4.4 Repository Layer
+- [4.4.1 - Create Post Repository Interface](./4.4.1-create-modulesbloginternaldomainpost_repogo.md)
+- [4.4.2 - Implement Repository](./4.4.2-implement-using-ent-client-shared-from-core.md)
+
+### 4.5 Service Layer
+- [4.5.1 - Create Post Service](./4.5.1-create-modulesbloginternalservicepost_servicego.md)
+
+### 4.6 API Layer
+- [4.6.1 - Create API Handler](./4.6.1-create-modulesbloginternalapihandlergo.md)
+
+## Deliverables Checklist
+- [ ] Blog module directory structure created
+- [ ] Module manifest defines permissions and routes
+- [ ] Blog post domain model defined
+- [ ] Ent schema for blog posts created
+- [ ] Repository implements CRUD operations
+- [ ] Service layer implements business logic
+- [ ] API endpoints for blog posts working
+- [ ] Module integrated with core platform
+
+## Acceptance Criteria
+- Blog module can be registered with core platform
+- Permissions are generated for blog module
+- CRUD operations work for blog posts
+- API endpoints require proper authentication
+- Module migrations run on startup
+- Blog posts are associated with users
+
diff --git a/docs/stories/phase5/5.1.1-install-githubcomredisgo-redisv9.md b/docs/content/stories/phase5/5.1.1-install-githubcomredisgo-redisv9.md
similarity index 100%
rename from docs/stories/phase5/5.1.1-install-githubcomredisgo-redisv9.md
rename to docs/content/stories/phase5/5.1.1-install-githubcomredisgo-redisv9.md
diff --git a/docs/stories/phase5/5.1.2-create-pkginfracachecachego-interface.md b/docs/content/stories/phase5/5.1.2-create-pkginfracachecachego-interface.md
similarity index 100%
rename from docs/stories/phase5/5.1.2-create-pkginfracachecachego-interface.md
rename to docs/content/stories/phase5/5.1.2-create-pkginfracachecachego-interface.md
diff --git a/docs/stories/phase5/5.1.3-implement-internalinfracacheredis_cachego.md b/docs/content/stories/phase5/5.1.3-implement-internalinfracacheredis_cachego.md
similarity index 100%
rename from docs/stories/phase5/5.1.3-implement-internalinfracacheredis_cachego.md
rename to docs/content/stories/phase5/5.1.3-implement-internalinfracacheredis_cachego.md
diff --git a/docs/stories/phase5/5.1.4-add-redis-config-to-configdefaultyaml.md b/docs/content/stories/phase5/5.1.4-add-redis-config-to-configdefaultyaml.md
similarity index 100%
rename from docs/stories/phase5/5.1.4-add-redis-config-to-configdefaultyaml.md
rename to docs/content/stories/phase5/5.1.4-add-redis-config-to-configdefaultyaml.md
diff --git a/docs/stories/phase5/5.1.5-register-in-di-container.md b/docs/content/stories/phase5/5.1.5-register-in-di-container.md
similarity index 100%
rename from docs/stories/phase5/5.1.5-register-in-di-container.md
rename to docs/content/stories/phase5/5.1.5-register-in-di-container.md
diff --git a/docs/stories/phase5/5.1.6-add-cache-middleware-for-selected-routes-optional.md b/docs/content/stories/phase5/5.1.6-add-cache-middleware-for-selected-routes-optional.md
similarity index 100%
rename from docs/stories/phase5/5.1.6-add-cache-middleware-for-selected-routes-optional.md
rename to docs/content/stories/phase5/5.1.6-add-cache-middleware-for-selected-routes-optional.md
diff --git a/docs/stories/phase5/5.2.1-create-pkgeventbuseventbusgo-interface.md b/docs/content/stories/phase5/5.2.1-create-pkgeventbuseventbusgo-interface.md
similarity index 100%
rename from docs/stories/phase5/5.2.1-create-pkgeventbuseventbusgo-interface.md
rename to docs/content/stories/phase5/5.2.1-create-pkgeventbuseventbusgo-interface.md
diff --git a/docs/stories/phase5/5.2.2-implement-internalinfrabusinprocess_busgo.md b/docs/content/stories/phase5/5.2.2-implement-internalinfrabusinprocess_busgo.md
similarity index 100%
rename from docs/stories/phase5/5.2.2-implement-internalinfrabusinprocess_busgo.md
rename to docs/content/stories/phase5/5.2.2-implement-internalinfrabusinprocess_busgo.md
diff --git a/docs/stories/phase5/5.2.3-implement-internalinfrabuskafka_busgo.md b/docs/content/stories/phase5/5.2.3-implement-internalinfrabuskafka_busgo.md
similarity index 100%
rename from docs/stories/phase5/5.2.3-implement-internalinfrabuskafka_busgo.md
rename to docs/content/stories/phase5/5.2.3-implement-internalinfrabuskafka_busgo.md
diff --git a/docs/stories/phase5/5.2.4-add-kafka-config-to-configdefaultyaml.md b/docs/content/stories/phase5/5.2.4-add-kafka-config-to-configdefaultyaml.md
similarity index 100%
rename from docs/stories/phase5/5.2.4-add-kafka-config-to-configdefaultyaml.md
rename to docs/content/stories/phase5/5.2.4-add-kafka-config-to-configdefaultyaml.md
diff --git a/docs/stories/phase5/5.2.5-register-bus-in-di-container-switchable-via-config.md b/docs/content/stories/phase5/5.2.5-register-bus-in-di-container-switchable-via-config.md
similarity index 100%
rename from docs/stories/phase5/5.2.5-register-bus-in-di-container-switchable-via-config.md
rename to docs/content/stories/phase5/5.2.5-register-bus-in-di-container-switchable-via-config.md
diff --git a/docs/stories/phase5/5.2.6-add-core-events.md b/docs/content/stories/phase5/5.2.6-add-core-events.md
similarity index 100%
rename from docs/stories/phase5/5.2.6-add-core-events.md
rename to docs/content/stories/phase5/5.2.6-add-core-events.md
diff --git a/docs/stories/phase5/5.3.1-install-githubcomawsaws-sdk-go-v2services3.md b/docs/content/stories/phase5/5.3.1-install-githubcomawsaws-sdk-go-v2services3.md
similarity index 100%
rename from docs/stories/phase5/5.3.1-install-githubcomawsaws-sdk-go-v2services3.md
rename to docs/content/stories/phase5/5.3.1-install-githubcomawsaws-sdk-go-v2services3.md
diff --git a/docs/stories/phase5/5.3.2-create-pkginfrablobblobgo-interface.md b/docs/content/stories/phase5/5.3.2-create-pkginfrablobblobgo-interface.md
similarity index 100%
rename from docs/stories/phase5/5.3.2-create-pkginfrablobblobgo-interface.md
rename to docs/content/stories/phase5/5.3.2-create-pkginfrablobblobgo-interface.md
diff --git a/docs/stories/phase5/5.3.3-implement-internalinfrablobs3_storego.md b/docs/content/stories/phase5/5.3.3-implement-internalinfrablobs3_storego.md
similarity index 100%
rename from docs/stories/phase5/5.3.3-implement-internalinfrablobs3_storego.md
rename to docs/content/stories/phase5/5.3.3-implement-internalinfrablobs3_storego.md
diff --git a/docs/stories/phase5/5.3.4-add-s3-config-to-configdefaultyaml.md b/docs/content/stories/phase5/5.3.4-add-s3-config-to-configdefaultyaml.md
similarity index 100%
rename from docs/stories/phase5/5.3.4-add-s3-config-to-configdefaultyaml.md
rename to docs/content/stories/phase5/5.3.4-add-s3-config-to-configdefaultyaml.md
diff --git a/docs/stories/phase5/5.3.5-register-in-di-container.md b/docs/content/stories/phase5/5.3.5-register-in-di-container.md
similarity index 100%
rename from docs/stories/phase5/5.3.5-register-in-di-container.md
rename to docs/content/stories/phase5/5.3.5-register-in-di-container.md
diff --git a/docs/stories/phase5/5.3.6-add-file-upload-endpoint-post-apiv1filesupload.md b/docs/content/stories/phase5/5.3.6-add-file-upload-endpoint-post-apiv1filesupload.md
similarity index 100%
rename from docs/stories/phase5/5.3.6-add-file-upload-endpoint-post-apiv1filesupload.md
rename to docs/content/stories/phase5/5.3.6-add-file-upload-endpoint-post-apiv1filesupload.md
diff --git a/docs/stories/phase5/5.4.1-install-githubcomgo-mailmail.md b/docs/content/stories/phase5/5.4.1-install-githubcomgo-mailmail.md
similarity index 100%
rename from docs/stories/phase5/5.4.1-install-githubcomgo-mailmail.md
rename to docs/content/stories/phase5/5.4.1-install-githubcomgo-mailmail.md
diff --git a/docs/stories/phase5/5.4.2-create-pkgnotificationnotificationgo-interface.md b/docs/content/stories/phase5/5.4.2-create-pkgnotificationnotificationgo-interface.md
similarity index 100%
rename from docs/stories/phase5/5.4.2-create-pkgnotificationnotificationgo-interface.md
rename to docs/content/stories/phase5/5.4.2-create-pkgnotificationnotificationgo-interface.md
diff --git a/docs/stories/phase5/5.4.3-implement-internalinfraemailsmtp_notifiergo.md b/docs/content/stories/phase5/5.4.3-implement-internalinfraemailsmtp_notifiergo.md
similarity index 100%
rename from docs/stories/phase5/5.4.3-implement-internalinfraemailsmtp_notifiergo.md
rename to docs/content/stories/phase5/5.4.3-implement-internalinfraemailsmtp_notifiergo.md
diff --git a/docs/stories/phase5/5.4.4-add-email-config-to-configdefaultyaml.md b/docs/content/stories/phase5/5.4.4-add-email-config-to-configdefaultyaml.md
similarity index 100%
rename from docs/stories/phase5/5.4.4-add-email-config-to-configdefaultyaml.md
rename to docs/content/stories/phase5/5.4.4-add-email-config-to-configdefaultyaml.md
diff --git a/docs/stories/phase5/5.4.5-integrate-with-identity-service.md b/docs/content/stories/phase5/5.4.5-integrate-with-identity-service.md
similarity index 100%
rename from docs/stories/phase5/5.4.5-integrate-with-identity-service.md
rename to docs/content/stories/phase5/5.4.5-integrate-with-identity-service.md
diff --git a/docs/stories/phase5/5.4.6-register-in-di-container.md b/docs/content/stories/phase5/5.4.6-register-in-di-container.md
similarity index 100%
rename from docs/stories/phase5/5.4.6-register-in-di-container.md
rename to docs/content/stories/phase5/5.4.6-register-in-di-container.md
diff --git a/docs/stories/phase5/5.5.1-install-githubcomrobfigcronv3-and-githubcomhibiken.md b/docs/content/stories/phase5/5.5.1-install-githubcomrobfigcronv3-and-githubcomhibiken.md
similarity index 100%
rename from docs/stories/phase5/5.5.1-install-githubcomrobfigcronv3-and-githubcomhibiken.md
rename to docs/content/stories/phase5/5.5.1-install-githubcomrobfigcronv3-and-githubcomhibiken.md
diff --git a/docs/stories/phase5/5.5.2-create-pkgschedulerschedulergo-interface.md b/docs/content/stories/phase5/5.5.2-create-pkgschedulerschedulergo-interface.md
similarity index 100%
rename from docs/stories/phase5/5.5.2-create-pkgschedulerschedulergo-interface.md
rename to docs/content/stories/phase5/5.5.2-create-pkgschedulerschedulergo-interface.md
diff --git a/docs/stories/phase5/5.5.3-implement-internalinfraschedulerasynq_schedulergo.md b/docs/content/stories/phase5/5.5.3-implement-internalinfraschedulerasynq_schedulergo.md
similarity index 100%
rename from docs/stories/phase5/5.5.3-implement-internalinfraschedulerasynq_schedulergo.md
rename to docs/content/stories/phase5/5.5.3-implement-internalinfraschedulerasynq_schedulergo.md
diff --git a/docs/stories/phase5/5.5.4-create-internalinfraschedulerjob_registrygo.md b/docs/content/stories/phase5/5.5.4-create-internalinfraschedulerjob_registrygo.md
similarity index 100%
rename from docs/stories/phase5/5.5.4-create-internalinfraschedulerjob_registrygo.md
rename to docs/content/stories/phase5/5.5.4-create-internalinfraschedulerjob_registrygo.md
diff --git a/docs/stories/phase5/5.5.5-add-example-jobs.md b/docs/content/stories/phase5/5.5.5-add-example-jobs.md
similarity index 100%
rename from docs/stories/phase5/5.5.5-add-example-jobs.md
rename to docs/content/stories/phase5/5.5.5-add-example-jobs.md
diff --git a/docs/stories/phase5/5.5.6-add-job-monitoring-endpoint-get-apiv1jobsstatus.md b/docs/content/stories/phase5/5.5.6-add-job-monitoring-endpoint-get-apiv1jobsstatus.md
similarity index 100%
rename from docs/stories/phase5/5.5.6-add-job-monitoring-endpoint-get-apiv1jobsstatus.md
rename to docs/content/stories/phase5/5.5.6-add-job-monitoring-endpoint-get-apiv1jobsstatus.md
diff --git a/docs/stories/phase5/5.6.1-create-pkginfrasecretsecretgo-interface.md b/docs/content/stories/phase5/5.6.1-create-pkginfrasecretsecretgo-interface.md
similarity index 100%
rename from docs/stories/phase5/5.6.1-create-pkginfrasecretsecretgo-interface.md
rename to docs/content/stories/phase5/5.6.1-create-pkginfrasecretsecretgo-interface.md
diff --git a/docs/stories/phase5/5.6.2-implement-internalinfrasecretvault_storego-hashico.md b/docs/content/stories/phase5/5.6.2-implement-internalinfrasecretvault_storego-hashico.md
similarity index 100%
rename from docs/stories/phase5/5.6.2-implement-internalinfrasecretvault_storego-hashico.md
rename to docs/content/stories/phase5/5.6.2-implement-internalinfrasecretvault_storego-hashico.md
diff --git a/docs/stories/phase5/5.6.3-implement-internalinfrasecretaws_secretsgo-aws-sec.md b/docs/content/stories/phase5/5.6.3-implement-internalinfrasecretaws_secretsgo-aws-sec.md
similarity index 100%
rename from docs/stories/phase5/5.6.3-implement-internalinfrasecretaws_secretsgo-aws-sec.md
rename to docs/content/stories/phase5/5.6.3-implement-internalinfrasecretaws_secretsgo-aws-sec.md
diff --git a/docs/stories/phase5/5.6.4-integrate-with-config-loader.md b/docs/content/stories/phase5/5.6.4-integrate-with-config-loader.md
similarity index 100%
rename from docs/stories/phase5/5.6.4-integrate-with-config-loader.md
rename to docs/content/stories/phase5/5.6.4-integrate-with-config-loader.md
diff --git a/docs/stories/phase5/5.6.5-register-in-di-container-optional-via-config.md b/docs/content/stories/phase5/5.6.5-register-in-di-container-optional-via-config.md
similarity index 100%
rename from docs/stories/phase5/5.6.5-register-in-di-container-optional-via-config.md
rename to docs/content/stories/phase5/5.6.5-register-in-di-container-optional-via-config.md
diff --git a/docs/stories/phase5/5.7.1-create-pkgtenanttenantgo-interface.md b/docs/content/stories/phase5/5.7.1-create-pkgtenanttenantgo-interface.md
similarity index 100%
rename from docs/stories/phase5/5.7.1-create-pkgtenanttenantgo-interface.md
rename to docs/content/stories/phase5/5.7.1-create-pkgtenanttenantgo-interface.md
diff --git a/docs/stories/phase5/5.7.2-implement-internaltenantresolvergo.md b/docs/content/stories/phase5/5.7.2-implement-internaltenantresolvergo.md
similarity index 100%
rename from docs/stories/phase5/5.7.2-implement-internaltenantresolvergo.md
rename to docs/content/stories/phase5/5.7.2-implement-internaltenantresolvergo.md
diff --git a/docs/stories/phase5/5.7.3-add-tenant-middleware.md b/docs/content/stories/phase5/5.7.3-add-tenant-middleware.md
similarity index 100%
rename from docs/stories/phase5/5.7.3-add-tenant-middleware.md
rename to docs/content/stories/phase5/5.7.3-add-tenant-middleware.md
diff --git a/docs/stories/phase5/5.7.4-update-ent-queries-to-filter-by-tenant_id.md b/docs/content/stories/phase5/5.7.4-update-ent-queries-to-filter-by-tenant_id.md
similarity index 100%
rename from docs/stories/phase5/5.7.4-update-ent-queries-to-filter-by-tenant_id.md
rename to docs/content/stories/phase5/5.7.4-update-ent-queries-to-filter-by-tenant_id.md
diff --git a/docs/stories/phase5/5.7.5-update-user-entity-to-include-tenant_id.md b/docs/content/stories/phase5/5.7.5-update-user-entity-to-include-tenant_id.md
similarity index 100%
rename from docs/stories/phase5/5.7.5-update-user-entity-to-include-tenant_id.md
rename to docs/content/stories/phase5/5.7.5-update-user-entity-to-include-tenant_id.md
diff --git a/docs/content/stories/phase5/README.md b/docs/content/stories/phase5/README.md
new file mode 100644
index 0000000..19c72f7
--- /dev/null
+++ b/docs/content/stories/phase5/README.md
@@ -0,0 +1,49 @@
+# Phase 5: Infrastructure Adapters
+
+## Overview
+Implement infrastructure adapters for caching (Redis), event bus (Kafka), background job scheduling (asynq), and multi-tenancy support.
+
+## Tasks
+
+### 5.1 Cache Implementation
+- [5.1.1 - Install Redis Client](./5.1.1-install-githubcomredisgo-redisv9.md)
+- [5.1.2 - Create Cache Interface](./5.1.2-create-pkginfracachecachego-interface.md)
+- [5.1.3 - Implement Redis Cache](./5.1.3-implement-internalinfracacheredis_cachego.md)
+- [5.1.4 - Add Redis Config](./5.1.4-add-redis-config-to-configdefaultyaml.md)
+- [5.1.5 - Register in DI Container](./5.1.5-register-in-di-container.md)
+- [5.1.6 - Add Cache Middleware](./5.1.6-add-cache-middleware-for-selected-routes-optional.md)
+
+### 5.2 Event Bus Implementation
+- [5.2.1 - Create Event Bus Interface](./5.2.1-create-pkgeventbuseventbusgo-interface.md)
+- [5.2.2 - Implement In-Process Bus](./5.2.2-implement-internalinfrabusinprocess_busgo.md)
+- [5.2.3 - Implement Kafka Bus](./5.2.3-implement-internalinfrabuskafka_busgo.md)
+- [5.2.4 - Add Kafka Config](./5.2.4-add-kafka-config-to-configdefaultyaml.md)
+
+### 5.3 Background Job Scheduler
+- [5.3.1 - Install Asynq](./5.3.1-install-githubcomhibikenasynq.md)
+- [5.3.2 - Create Scheduler Interface](./5.3.2-create-pkgschedulerschedulergo-interface.md)
+- [5.3.3 - Implement Asynq Scheduler](./5.3.3-implement-internalinfraschedulerasynq_schedulergo.md)
+- [5.3.4 - Add Cron Support](./5.3.4-add-cron-support.md)
+
+### 5.4 Multi-tenancy Support
+- [5.4.1 - Create Tenant Resolver Interface](./5.4.1-create-pkgtenanttenantgo-interface.md)
+- [5.4.2 - Implement Tenant Resolver](./5.4.2-implement-internaltenantresolvergo.md)
+- [5.4.3 - Add Tenant Middleware](./5.4.3-add-tenant-middleware.md)
+- [5.4.4 - Update Ent Queries](./5.4.4-update-ent-queries-with-tenant-scoping.md)
+
+## Deliverables Checklist
+- [ ] Redis cache adapter implemented
+- [ ] Event bus supports in-process and Kafka
+- [ ] Background job scheduler with asynq
+- [ ] Cron job support
+- [ ] Multi-tenancy resolver and middleware
+- [ ] Database queries scoped by tenant
+
+## Acceptance Criteria
+- Cache operations work with Redis fallback
+- Events can be published to Kafka
+- Background jobs can be scheduled
+- Cron jobs run on schedule
+- Tenant isolation works for database queries
+- Middleware extracts tenant from request
+
diff --git a/docs/stories/phase6/6.1.1-complete-opentelemetry-setup.md b/docs/content/stories/phase6/6.1.1-complete-opentelemetry-setup.md
similarity index 100%
rename from docs/stories/phase6/6.1.1-complete-opentelemetry-setup.md
rename to docs/content/stories/phase6/6.1.1-complete-opentelemetry-setup.md
diff --git a/docs/stories/phase6/6.1.2-create-custom-spans.md b/docs/content/stories/phase6/6.1.2-create-custom-spans.md
similarity index 100%
rename from docs/stories/phase6/6.1.2-create-custom-spans.md
rename to docs/content/stories/phase6/6.1.2-create-custom-spans.md
diff --git a/docs/stories/phase6/6.1.3-add-trace-context-propagation.md b/docs/content/stories/phase6/6.1.3-add-trace-context-propagation.md
similarity index 100%
rename from docs/stories/phase6/6.1.3-add-trace-context-propagation.md
rename to docs/content/stories/phase6/6.1.3-add-trace-context-propagation.md
diff --git a/docs/stories/phase6/6.2.1-install-githubcomgetsentrysentry-go.md b/docs/content/stories/phase6/6.2.1-install-githubcomgetsentrysentry-go.md
similarity index 100%
rename from docs/stories/phase6/6.2.1-install-githubcomgetsentrysentry-go.md
rename to docs/content/stories/phase6/6.2.1-install-githubcomgetsentrysentry-go.md
diff --git a/docs/stories/phase6/6.2.2-integrate-with-error-bus.md b/docs/content/stories/phase6/6.2.2-integrate-with-error-bus.md
similarity index 100%
rename from docs/stories/phase6/6.2.2-integrate-with-error-bus.md
rename to docs/content/stories/phase6/6.2.2-integrate-with-error-bus.md
diff --git a/docs/stories/phase6/6.2.3-add-sentry-middleware.md b/docs/content/stories/phase6/6.2.3-add-sentry-middleware.md
similarity index 100%
rename from docs/stories/phase6/6.2.3-add-sentry-middleware.md
rename to docs/content/stories/phase6/6.2.3-add-sentry-middleware.md
diff --git a/docs/stories/phase6/6.2.4-configure-sentry-dsn-via-config.md b/docs/content/stories/phase6/6.2.4-configure-sentry-dsn-via-config.md
similarity index 100%
rename from docs/stories/phase6/6.2.4-configure-sentry-dsn-via-config.md
rename to docs/content/stories/phase6/6.2.4-configure-sentry-dsn-via-config.md
diff --git a/docs/stories/phase6/6.3.1-add-request-correlation.md b/docs/content/stories/phase6/6.3.1-add-request-correlation.md
similarity index 100%
rename from docs/stories/phase6/6.3.1-add-request-correlation.md
rename to docs/content/stories/phase6/6.3.1-add-request-correlation.md
diff --git a/docs/stories/phase6/6.3.2-add-structured-fields.md b/docs/content/stories/phase6/6.3.2-add-structured-fields.md
similarity index 100%
rename from docs/stories/phase6/6.3.2-add-structured-fields.md
rename to docs/content/stories/phase6/6.3.2-add-structured-fields.md
diff --git a/docs/stories/phase6/6.3.3-create-log-aggregation-config.md b/docs/content/stories/phase6/6.3.3-create-log-aggregation-config.md
similarity index 100%
rename from docs/stories/phase6/6.3.3-create-log-aggregation-config.md
rename to docs/content/stories/phase6/6.3.3-create-log-aggregation-config.md
diff --git a/docs/stories/phase6/6.4.1-add-more-metrics.md b/docs/content/stories/phase6/6.4.1-add-more-metrics.md
similarity index 100%
rename from docs/stories/phase6/6.4.1-add-more-metrics.md
rename to docs/content/stories/phase6/6.4.1-add-more-metrics.md
diff --git a/docs/stories/phase6/6.4.2-create-metric-labels.md b/docs/content/stories/phase6/6.4.2-create-metric-labels.md
similarity index 100%
rename from docs/stories/phase6/6.4.2-create-metric-labels.md
rename to docs/content/stories/phase6/6.4.2-create-metric-labels.md
diff --git a/docs/stories/phase6/6.5.1-create-opsgrafanadashboards.md b/docs/content/stories/phase6/6.5.1-create-opsgrafanadashboards.md
similarity index 100%
rename from docs/stories/phase6/6.5.1-create-opsgrafanadashboards.md
rename to docs/content/stories/phase6/6.5.1-create-opsgrafanadashboards.md
diff --git a/docs/stories/phase6/6.5.2-document-dashboard-setup-in-docsoperationsmd.md b/docs/content/stories/phase6/6.5.2-document-dashboard-setup-in-docsoperationsmd.md
similarity index 100%
rename from docs/stories/phase6/6.5.2-document-dashboard-setup-in-docsoperationsmd.md
rename to docs/content/stories/phase6/6.5.2-document-dashboard-setup-in-docsoperationsmd.md
diff --git a/docs/stories/phase6/6.6.1-install-githubcomululelimiterv3.md b/docs/content/stories/phase6/6.6.1-install-githubcomululelimiterv3.md
similarity index 100%
rename from docs/stories/phase6/6.6.1-install-githubcomululelimiterv3.md
rename to docs/content/stories/phase6/6.6.1-install-githubcomululelimiterv3.md
diff --git a/docs/stories/phase6/6.6.2-create-rate-limit-middleware.md b/docs/content/stories/phase6/6.6.2-create-rate-limit-middleware.md
similarity index 100%
rename from docs/stories/phase6/6.6.2-create-rate-limit-middleware.md
rename to docs/content/stories/phase6/6.6.2-create-rate-limit-middleware.md
diff --git a/docs/stories/phase6/6.6.3-add-rate-limit-config.md b/docs/content/stories/phase6/6.6.3-add-rate-limit-config.md
similarity index 100%
rename from docs/stories/phase6/6.6.3-add-rate-limit-config.md
rename to docs/content/stories/phase6/6.6.3-add-rate-limit-config.md
diff --git a/docs/stories/phase6/6.6.4-return-x-ratelimit--headers.md b/docs/content/stories/phase6/6.6.4-return-x-ratelimit--headers.md
similarity index 100%
rename from docs/stories/phase6/6.6.4-return-x-ratelimit--headers.md
rename to docs/content/stories/phase6/6.6.4-return-x-ratelimit--headers.md
diff --git a/docs/stories/phase6/6.7.1-add-security-headers-middleware.md b/docs/content/stories/phase6/6.7.1-add-security-headers-middleware.md
similarity index 100%
rename from docs/stories/phase6/6.7.1-add-security-headers-middleware.md
rename to docs/content/stories/phase6/6.7.1-add-security-headers-middleware.md
diff --git a/docs/stories/phase6/6.7.2-add-request-size-limits.md b/docs/content/stories/phase6/6.7.2-add-request-size-limits.md
similarity index 100%
rename from docs/stories/phase6/6.7.2-add-request-size-limits.md
rename to docs/content/stories/phase6/6.7.2-add-request-size-limits.md
diff --git a/docs/stories/phase6/6.7.3-add-input-validation.md b/docs/content/stories/phase6/6.7.3-add-input-validation.md
similarity index 100%
rename from docs/stories/phase6/6.7.3-add-input-validation.md
rename to docs/content/stories/phase6/6.7.3-add-input-validation.md
diff --git a/docs/stories/phase6/6.7.4-add-sql-injection-protection.md b/docs/content/stories/phase6/6.7.4-add-sql-injection-protection.md
similarity index 100%
rename from docs/stories/phase6/6.7.4-add-sql-injection-protection.md
rename to docs/content/stories/phase6/6.7.4-add-sql-injection-protection.md
diff --git a/docs/stories/phase6/6.8.1-add-database-connection-pooling.md b/docs/content/stories/phase6/6.8.1-add-database-connection-pooling.md
similarity index 100%
rename from docs/stories/phase6/6.8.1-add-database-connection-pooling.md
rename to docs/content/stories/phase6/6.8.1-add-database-connection-pooling.md
diff --git a/docs/stories/phase6/6.8.2-add-query-optimization.md b/docs/content/stories/phase6/6.8.2-add-query-optimization.md
similarity index 100%
rename from docs/stories/phase6/6.8.2-add-query-optimization.md
rename to docs/content/stories/phase6/6.8.2-add-query-optimization.md
diff --git a/docs/stories/phase6/6.8.3-add-response-compression.md b/docs/content/stories/phase6/6.8.3-add-response-compression.md
similarity index 100%
rename from docs/stories/phase6/6.8.3-add-response-compression.md
rename to docs/content/stories/phase6/6.8.3-add-response-compression.md
diff --git a/docs/stories/phase6/6.8.4-add-caching-strategy.md b/docs/content/stories/phase6/6.8.4-add-caching-strategy.md
similarity index 100%
rename from docs/stories/phase6/6.8.4-add-caching-strategy.md
rename to docs/content/stories/phase6/6.8.4-add-caching-strategy.md
diff --git a/docs/content/stories/phase6/README.md b/docs/content/stories/phase6/README.md
new file mode 100644
index 0000000..cc98773
--- /dev/null
+++ b/docs/content/stories/phase6/README.md
@@ -0,0 +1,48 @@
+# Phase 6: Observability & Production Readiness
+
+## Overview
+Complete observability setup with OpenTelemetry, integrate error reporting with Sentry, enhance logging with correlation IDs, and add rate limiting.
+
+## Tasks
+
+### 6.1 OpenTelemetry Completion
+- [6.1.1 - Complete OpenTelemetry Setup](./6.1.1-complete-opentelemetry-setup.md)
+- [6.1.2 - Create Custom Spans](./6.1.2-create-custom-spans.md)
+- [6.1.3 - Add Trace Context Propagation](./6.1.3-add-trace-context-propagation.md)
+
+### 6.2 Error Reporting (Sentry)
+- [6.2.1 - Install Sentry](./6.2.1-install-githubcomgetsentrysentry-go.md)
+- [6.2.2 - Integrate with Error Bus](./6.2.2-integrate-with-error-bus.md)
+- [6.2.3 - Add Sentry Middleware](./6.2.3-add-sentry-middleware.md)
+- [6.2.4 - Configure Sentry DSN](./6.2.4-configure-sentry-dsn-via-config.md)
+
+### 6.3 Enhanced Logging
+- [6.3.1 - Add Request Correlation](./6.3.1-add-request-correlation.md)
+- [6.3.2 - Add Structured Fields](./6.3.2-add-structured-fields.md)
+- [6.3.3 - Create Log Aggregation Config](./6.3.3-create-log-aggregation-config.md)
+
+### 6.4 Rate Limiting
+- [6.4.1 - Create Rate Limiter Interface](./6.4.1-create-pkgratelimitratelimitergo-interface.md)
+- [6.4.2 - Implement Redis Rate Limiter](./6.4.2-implement-internalratelimitredis_limitergo.md)
+- [6.4.3 - Add Rate Limit Middleware](./6.4.3-add-rate-limit-middleware.md)
+
+### 6.5 Production Configuration
+- [6.5.1 - Create Production Config Template](./6.5.1-create-production-config-template.md)
+- [6.5.2 - Add Environment-Specific Settings](./6.5.2-add-environment-specific-settings.md)
+
+## Deliverables Checklist
+- [ ] OpenTelemetry fully integrated with custom spans
+- [ ] Sentry error reporting working
+- [ ] Enhanced logging with correlation IDs
+- [ ] Rate limiting middleware implemented
+- [ ] Production configuration templates ready
+- [ ] All observability data flowing to external systems
+
+## Acceptance Criteria
+- Traces are exported to OTLP endpoint
+- Errors are reported to Sentry
+- Logs include correlation IDs
+- Rate limiting prevents abuse
+- Production configs are validated
+- All metrics are exposed via Prometheus
+
diff --git a/docs/stories/phase7/7.1.1-achieve-80-code-coverage-for-core-modules.md b/docs/content/stories/phase7/7.1.1-achieve-80-code-coverage-for-core-modules.md
similarity index 100%
rename from docs/stories/phase7/7.1.1-achieve-80-code-coverage-for-core-modules.md
rename to docs/content/stories/phase7/7.1.1-achieve-80-code-coverage-for-core-modules.md
diff --git a/docs/stories/phase7/7.1.2-use-githubcomstretchrtestify-for-assertions.md b/docs/content/stories/phase7/7.1.2-use-githubcomstretchrtestify-for-assertions.md
similarity index 100%
rename from docs/stories/phase7/7.1.2-use-githubcomstretchrtestify-for-assertions.md
rename to docs/content/stories/phase7/7.1.2-use-githubcomstretchrtestify-for-assertions.md
diff --git a/docs/stories/phase7/7.1.3-use-githubcomgolangmock-or-mockery-for-mocks.md b/docs/content/stories/phase7/7.1.3-use-githubcomgolangmock-or-mockery-for-mocks.md
similarity index 100%
rename from docs/stories/phase7/7.1.3-use-githubcomgolangmock-or-mockery-for-mocks.md
rename to docs/content/stories/phase7/7.1.3-use-githubcomgolangmock-or-mockery-for-mocks.md
diff --git a/docs/stories/phase7/7.1.4-add-test-helpers.md b/docs/content/stories/phase7/7.1.4-add-test-helpers.md
similarity index 100%
rename from docs/stories/phase7/7.1.4-add-test-helpers.md
rename to docs/content/stories/phase7/7.1.4-add-test-helpers.md
diff --git a/docs/stories/phase7/7.2.1-install-githubcomtestcontainerstestcontainers-go.md b/docs/content/stories/phase7/7.2.1-install-githubcomtestcontainerstestcontainers-go.md
similarity index 100%
rename from docs/stories/phase7/7.2.1-install-githubcomtestcontainerstestcontainers-go.md
rename to docs/content/stories/phase7/7.2.1-install-githubcomtestcontainerstestcontainers-go.md
diff --git a/docs/stories/phase7/7.2.2-create-integration-test-suite.md b/docs/content/stories/phase7/7.2.2-create-integration-test-suite.md
similarity index 100%
rename from docs/stories/phase7/7.2.2-create-integration-test-suite.md
rename to docs/content/stories/phase7/7.2.2-create-integration-test-suite.md
diff --git a/docs/stories/phase7/7.2.3-test-scenarios.md b/docs/content/stories/phase7/7.2.3-test-scenarios.md
similarity index 100%
rename from docs/stories/phase7/7.2.3-test-scenarios.md
rename to docs/content/stories/phase7/7.2.3-test-scenarios.md
diff --git a/docs/stories/phase7/7.2.4-create-docker-composetestyml.md b/docs/content/stories/phase7/7.2.4-create-docker-composetestyml.md
similarity index 100%
rename from docs/stories/phase7/7.2.4-create-docker-composetestyml.md
rename to docs/content/stories/phase7/7.2.4-create-docker-composetestyml.md
diff --git a/docs/stories/phase7/7.2.5-add-test-tags-gobuild-integration.md b/docs/content/stories/phase7/7.2.5-add-test-tags-gobuild-integration.md
similarity index 100%
rename from docs/stories/phase7/7.2.5-add-test-tags-gobuild-integration.md
rename to docs/content/stories/phase7/7.2.5-add-test-tags-gobuild-integration.md
diff --git a/docs/stories/phase7/7.3.1-install-githubcompact-foundationpact-go-optional.md b/docs/content/stories/phase7/7.3.1-install-githubcompact-foundationpact-go-optional.md
similarity index 100%
rename from docs/stories/phase7/7.3.1-install-githubcompact-foundationpact-go-optional.md
rename to docs/content/stories/phase7/7.3.1-install-githubcompact-foundationpact-go-optional.md
diff --git a/docs/stories/phase7/7.3.2-create-api-contract-tests.md b/docs/content/stories/phase7/7.3.2-create-api-contract-tests.md
similarity index 100%
rename from docs/stories/phase7/7.3.2-create-api-contract-tests.md
rename to docs/content/stories/phase7/7.3.2-create-api-contract-tests.md
diff --git a/docs/stories/phase7/7.3.3-use-openapi-validator.md b/docs/content/stories/phase7/7.3.3-use-openapi-validator.md
similarity index 100%
rename from docs/stories/phase7/7.3.3-use-openapi-validator.md
rename to docs/content/stories/phase7/7.3.3-use-openapi-validator.md
diff --git a/docs/stories/phase7/7.4.1-create-perf-directory-with-k6-scripts.md b/docs/content/stories/phase7/7.4.1-create-perf-directory-with-k6-scripts.md
similarity index 100%
rename from docs/stories/phase7/7.4.1-create-perf-directory-with-k6-scripts.md
rename to docs/content/stories/phase7/7.4.1-create-perf-directory-with-k6-scripts.md
diff --git a/docs/stories/phase7/7.4.2-document-performance-benchmarks.md b/docs/content/stories/phase7/7.4.2-document-performance-benchmarks.md
similarity index 100%
rename from docs/stories/phase7/7.4.2-document-performance-benchmarks.md
rename to docs/content/stories/phase7/7.4.2-document-performance-benchmarks.md
diff --git a/docs/stories/phase7/7.5.1-create-readmemd.md b/docs/content/stories/phase7/7.5.1-create-readmemd.md
similarity index 100%
rename from docs/stories/phase7/7.5.1-create-readmemd.md
rename to docs/content/stories/phase7/7.5.1-create-readmemd.md
diff --git a/docs/stories/phase7/7.5.2-create-docsarchitecturemd.md b/docs/content/stories/phase7/7.5.2-create-docsarchitecturemd.md
similarity index 100%
rename from docs/stories/phase7/7.5.2-create-docsarchitecturemd.md
rename to docs/content/stories/phase7/7.5.2-create-docsarchitecturemd.md
diff --git a/docs/stories/phase7/7.5.3-create-docsextension-pointsmd.md b/docs/content/stories/phase7/7.5.3-create-docsextension-pointsmd.md
similarity index 100%
rename from docs/stories/phase7/7.5.3-create-docsextension-pointsmd.md
rename to docs/content/stories/phase7/7.5.3-create-docsextension-pointsmd.md
diff --git a/docs/stories/phase7/7.5.4-create-docsapimd.md b/docs/content/stories/phase7/7.5.4-create-docsapimd.md
similarity index 100%
rename from docs/stories/phase7/7.5.4-create-docsapimd.md
rename to docs/content/stories/phase7/7.5.4-create-docsapimd.md
diff --git a/docs/stories/phase7/7.5.5-create-docsoperationsmd.md b/docs/content/stories/phase7/7.5.5-create-docsoperationsmd.md
similarity index 100%
rename from docs/stories/phase7/7.5.5-create-docsoperationsmd.md
rename to docs/content/stories/phase7/7.5.5-create-docsoperationsmd.md
diff --git a/docs/stories/phase7/7.5.6-add-code-examples.md b/docs/content/stories/phase7/7.5.6-add-code-examples.md
similarity index 100%
rename from docs/stories/phase7/7.5.6-add-code-examples.md
rename to docs/content/stories/phase7/7.5.6-add-code-examples.md
diff --git a/docs/stories/phase7/7.6.1-update-githubworkflowsciyml.md b/docs/content/stories/phase7/7.6.1-update-githubworkflowsciyml.md
similarity index 100%
rename from docs/stories/phase7/7.6.1-update-githubworkflowsciyml.md
rename to docs/content/stories/phase7/7.6.1-update-githubworkflowsciyml.md
diff --git a/docs/stories/phase7/7.6.2-add-release-workflow.md b/docs/content/stories/phase7/7.6.2-add-release-workflow.md
similarity index 100%
rename from docs/stories/phase7/7.6.2-add-release-workflow.md
rename to docs/content/stories/phase7/7.6.2-add-release-workflow.md
diff --git a/docs/stories/phase7/7.6.3-add-security-scanning.md b/docs/content/stories/phase7/7.6.3-add-security-scanning.md
similarity index 100%
rename from docs/stories/phase7/7.6.3-add-security-scanning.md
rename to docs/content/stories/phase7/7.6.3-add-security-scanning.md
diff --git a/docs/stories/phase7/7.7.1-create-multi-stage-dockerfile.md b/docs/content/stories/phase7/7.7.1-create-multi-stage-dockerfile.md
similarity index 100%
rename from docs/stories/phase7/7.7.1-create-multi-stage-dockerfile.md
rename to docs/content/stories/phase7/7.7.1-create-multi-stage-dockerfile.md
diff --git a/docs/stories/phase7/7.7.2-create-docker-composeyml-for-development.md b/docs/content/stories/phase7/7.7.2-create-docker-composeyml-for-development.md
similarity index 100%
rename from docs/stories/phase7/7.7.2-create-docker-composeyml-for-development.md
rename to docs/content/stories/phase7/7.7.2-create-docker-composeyml-for-development.md
diff --git a/docs/stories/phase7/7.7.3-create-docker-composeprodyml-for-production.md b/docs/content/stories/phase7/7.7.3-create-docker-composeprodyml-for-production.md
similarity index 100%
rename from docs/stories/phase7/7.7.3-create-docker-composeprodyml-for-production.md
rename to docs/content/stories/phase7/7.7.3-create-docker-composeprodyml-for-production.md
diff --git a/docs/stories/phase7/7.7.4-add-health-checks-to-dockerfile.md b/docs/content/stories/phase7/7.7.4-add-health-checks-to-dockerfile.md
similarity index 100%
rename from docs/stories/phase7/7.7.4-add-health-checks-to-dockerfile.md
rename to docs/content/stories/phase7/7.7.4-add-health-checks-to-dockerfile.md
diff --git a/docs/stories/phase7/7.7.5-document-docker-usage-in-docsdeploymentmd.md b/docs/content/stories/phase7/7.7.5-document-docker-usage-in-docsdeploymentmd.md
similarity index 100%
rename from docs/stories/phase7/7.7.5-document-docker-usage-in-docsdeploymentmd.md
rename to docs/content/stories/phase7/7.7.5-document-docker-usage-in-docsdeploymentmd.md
diff --git a/docs/stories/phase7/7.8.1-create-docsdeploymentkubernetesmd.md b/docs/content/stories/phase7/7.8.1-create-docsdeploymentkubernetesmd.md
similarity index 100%
rename from docs/stories/phase7/7.8.1-create-docsdeploymentkubernetesmd.md
rename to docs/content/stories/phase7/7.8.1-create-docsdeploymentkubernetesmd.md
diff --git a/docs/stories/phase7/7.8.2-create-docsdeploymentdockermd.md b/docs/content/stories/phase7/7.8.2-create-docsdeploymentdockermd.md
similarity index 100%
rename from docs/stories/phase7/7.8.2-create-docsdeploymentdockermd.md
rename to docs/content/stories/phase7/7.8.2-create-docsdeploymentdockermd.md
diff --git a/docs/stories/phase7/7.8.3-create-docsdeploymentcloudmd.md b/docs/content/stories/phase7/7.8.3-create-docsdeploymentcloudmd.md
similarity index 100%
rename from docs/stories/phase7/7.8.3-create-docsdeploymentcloudmd.md
rename to docs/content/stories/phase7/7.8.3-create-docsdeploymentcloudmd.md
diff --git a/docs/stories/phase7/7.9.1-create-makefile-with-common-tasks.md b/docs/content/stories/phase7/7.9.1-create-makefile-with-common-tasks.md
similarity index 100%
rename from docs/stories/phase7/7.9.1-create-makefile-with-common-tasks.md
rename to docs/content/stories/phase7/7.9.1-create-makefile-with-common-tasks.md
diff --git a/docs/stories/phase7/7.9.2-add-development-scripts.md b/docs/content/stories/phase7/7.9.2-add-development-scripts.md
similarity index 100%
rename from docs/stories/phase7/7.9.2-add-development-scripts.md
rename to docs/content/stories/phase7/7.9.2-add-development-scripts.md
diff --git a/docs/stories/phase7/7.9.3-create-envexample-with-all-config-variables.md b/docs/content/stories/phase7/7.9.3-create-envexample-with-all-config-variables.md
similarity index 100%
rename from docs/stories/phase7/7.9.3-create-envexample-with-all-config-variables.md
rename to docs/content/stories/phase7/7.9.3-create-envexample-with-all-config-variables.md
diff --git a/docs/stories/phase7/7.9.4-add-pre-commit-hooks-optional.md b/docs/content/stories/phase7/7.9.4-add-pre-commit-hooks-optional.md
similarity index 100%
rename from docs/stories/phase7/7.9.4-add-pre-commit-hooks-optional.md
rename to docs/content/stories/phase7/7.9.4-add-pre-commit-hooks-optional.md
diff --git a/docs/content/stories/phase7/README.md b/docs/content/stories/phase7/README.md
new file mode 100644
index 0000000..fa0939d
--- /dev/null
+++ b/docs/content/stories/phase7/README.md
@@ -0,0 +1,56 @@
+# Phase 7: Testing, Documentation & CI/CD
+
+## Overview
+Establish comprehensive testing strategy with unit, integration, and contract tests. Complete CI/CD pipeline, generate API documentation, and create deployment guides.
+
+## Tasks
+
+### 7.1 Unit Testing
+- [7.1.1 - Achieve 80% Code Coverage](./7.1.1-achieve-80-code-coverage-for-core-modules.md)
+- [7.1.2 - Use Testify for Assertions](./7.1.2-use-githubcomstretchrtestify-for-assertions.md)
+- [7.1.3 - Use Mockery for Mocks](./7.1.3-use-githubcomgolangmock-or-mockery-for-mocks.md)
+- [7.1.4 - Add Test Helpers](./7.1.4-add-test-helpers.md)
+
+### 7.2 Integration Testing
+- [7.2.1 - Install Testcontainers](./7.2.1-install-githubcomtestcontainerstestcontainers-go.md)
+- [7.2.2 - Create Integration Test Suite](./7.2.2-create-integration-test-suite.md)
+- [7.2.3 - Test Scenarios](./7.2.3-test-scenarios.md)
+- [7.2.4 - Create Docker Compose Test](./7.2.4-create-docker-composetestyml.md)
+- [7.2.5 - Add Test Tags](./7.2.5-add-test-tags-gobuild-integration.md)
+
+### 7.3 Contract Testing
+- [7.3.1 - Install Pact Go](./7.3.1-install-githubcompact-foundationpact-go-optional.md)
+- [7.3.2 - Create Contract Tests](./7.3.2-create-contract-tests.md)
+
+### 7.4 API Documentation
+- [7.4.1 - Generate OpenAPI Spec](./7.4.1-generate-openapi-spec.md)
+- [7.4.2 - Add Swagger UI](./7.4.2-add-swagger-ui.md)
+- [7.4.3 - Document API Endpoints](./7.4.3-document-api-endpoints.md)
+
+### 7.5 CI/CD Pipeline
+- [7.5.1 - Enhance GitHub Actions](./7.5.1-enhance-github-actions-workflow.md)
+- [7.5.2 - Add Test Coverage Reporting](./7.5.2-add-test-coverage-reporting.md)
+- [7.5.3 - Add Docker Image Building](./7.5.3-add-docker-image-building.md)
+- [7.5.4 - Add Deployment Workflows](./7.5.4-add-deployment-workflows.md)
+
+### 7.6 Documentation
+- [7.6.1 - Create Developer Guide](./7.6.1-create-developer-guide.md)
+- [7.6.2 - Create Deployment Guide](./7.6.2-create-deployment-guide.md)
+- [7.6.3 - Create Module Development Guide](./7.6.3-create-module-development-guide.md)
+
+## Deliverables Checklist
+- [ ] Unit tests achieve 80% coverage
+- [ ] Integration tests with testcontainers
+- [ ] Contract tests for API
+- [ ] OpenAPI documentation generated
+- [ ] CI/CD pipeline complete
+- [ ] Comprehensive documentation
+
+## Acceptance Criteria
+- `make test` runs all tests
+- `make test-integration` runs integration tests
+- CI pipeline passes on all PRs
+- API documentation is up-to-date
+- Deployment guides are complete
+- Code coverage reports are generated
+
diff --git a/docs/stories/phase8/8.1.1-install-githubcomcoreosgo-oidc.md b/docs/content/stories/phase8/8.1.1-install-githubcomcoreosgo-oidc.md
similarity index 100%
rename from docs/stories/phase8/8.1.1-install-githubcomcoreosgo-oidc.md
rename to docs/content/stories/phase8/8.1.1-install-githubcomcoreosgo-oidc.md
diff --git a/docs/stories/phase8/8.1.2-implement-oidc-provider.md b/docs/content/stories/phase8/8.1.2-implement-oidc-provider.md
similarity index 100%
rename from docs/stories/phase8/8.1.2-implement-oidc-provider.md
rename to docs/content/stories/phase8/8.1.2-implement-oidc-provider.md
diff --git a/docs/stories/phase8/8.1.3-add-oidc-client-support.md b/docs/content/stories/phase8/8.1.3-add-oidc-client-support.md
similarity index 100%
rename from docs/stories/phase8/8.1.3-add-oidc-client-support.md
rename to docs/content/stories/phase8/8.1.3-add-oidc-client-support.md
diff --git a/docs/stories/phase8/8.1.4-document-oidc-setup-in-docsauthmd.md b/docs/content/stories/phase8/8.1.4-document-oidc-setup-in-docsauthmd.md
similarity index 100%
rename from docs/stories/phase8/8.1.4-document-oidc-setup-in-docsauthmd.md
rename to docs/content/stories/phase8/8.1.4-document-oidc-setup-in-docsauthmd.md
diff --git a/docs/stories/phase8/8.2.1-install-githubcom99designsgqlgen.md b/docs/content/stories/phase8/8.2.1-install-githubcom99designsgqlgen.md
similarity index 100%
rename from docs/stories/phase8/8.2.1-install-githubcom99designsgqlgen.md
rename to docs/content/stories/phase8/8.2.1-install-githubcom99designsgqlgen.md
diff --git a/docs/stories/phase8/8.2.2-create-graphql-schema.md b/docs/content/stories/phase8/8.2.2-create-graphql-schema.md
similarity index 100%
rename from docs/stories/phase8/8.2.2-create-graphql-schema.md
rename to docs/content/stories/phase8/8.2.2-create-graphql-schema.md
diff --git a/docs/stories/phase8/8.2.3-implement-resolvers.md b/docs/content/stories/phase8/8.2.3-implement-resolvers.md
similarity index 100%
rename from docs/stories/phase8/8.2.3-implement-resolvers.md
rename to docs/content/stories/phase8/8.2.3-implement-resolvers.md
diff --git a/docs/stories/phase8/8.2.4-add-graphql-endpoint-post-graphql.md b/docs/content/stories/phase8/8.2.4-add-graphql-endpoint-post-graphql.md
similarity index 100%
rename from docs/stories/phase8/8.2.4-add-graphql-endpoint-post-graphql.md
rename to docs/content/stories/phase8/8.2.4-add-graphql-endpoint-post-graphql.md
diff --git a/docs/stories/phase8/8.3.1-add-requestresponse-transformation.md b/docs/content/stories/phase8/8.3.1-add-requestresponse-transformation.md
similarity index 100%
rename from docs/stories/phase8/8.3.1-add-requestresponse-transformation.md
rename to docs/content/stories/phase8/8.3.1-add-requestresponse-transformation.md
diff --git a/docs/stories/phase8/8.3.2-add-api-key-authentication.md b/docs/content/stories/phase8/8.3.2-add-api-key-authentication.md
similarity index 100%
rename from docs/stories/phase8/8.3.2-add-api-key-authentication.md
rename to docs/content/stories/phase8/8.3.2-add-api-key-authentication.md
diff --git a/docs/stories/phase8/8.3.3-add-request-routing-rules.md b/docs/content/stories/phase8/8.3.3-add-request-routing-rules.md
similarity index 100%
rename from docs/stories/phase8/8.3.3-add-request-routing-rules.md
rename to docs/content/stories/phase8/8.3.3-add-request-routing-rules.md
diff --git a/docs/stories/phase8/8.3.4-add-api-versioning-support.md b/docs/content/stories/phase8/8.3.4-add-api-versioning-support.md
similarity index 100%
rename from docs/stories/phase8/8.3.4-add-api-versioning-support.md
rename to docs/content/stories/phase8/8.3.4-add-api-versioning-support.md
diff --git a/docs/stories/phase8/8.4.1-create-modulesnotification.md b/docs/content/stories/phase8/8.4.1-create-modulesnotification.md
similarity index 100%
rename from docs/stories/phase8/8.4.1-create-modulesnotification.md
rename to docs/content/stories/phase8/8.4.1-create-modulesnotification.md
diff --git a/docs/stories/phase8/8.4.2-create-modulesanalytics.md b/docs/content/stories/phase8/8.4.2-create-modulesanalytics.md
similarity index 100%
rename from docs/stories/phase8/8.4.2-create-modulesanalytics.md
rename to docs/content/stories/phase8/8.4.2-create-modulesanalytics.md
diff --git a/docs/stories/phase8/8.5.1-add-database-query-caching.md b/docs/content/stories/phase8/8.5.1-add-database-query-caching.md
similarity index 100%
rename from docs/stories/phase8/8.5.1-add-database-query-caching.md
rename to docs/content/stories/phase8/8.5.1-add-database-query-caching.md
diff --git a/docs/stories/phase8/8.5.2-optimize-n1-queries.md b/docs/content/stories/phase8/8.5.2-optimize-n1-queries.md
similarity index 100%
rename from docs/stories/phase8/8.5.2-optimize-n1-queries.md
rename to docs/content/stories/phase8/8.5.2-optimize-n1-queries.md
diff --git a/docs/stories/phase8/8.5.3-add-response-caching-redis.md b/docs/content/stories/phase8/8.5.3-add-response-caching-redis.md
similarity index 100%
rename from docs/stories/phase8/8.5.3-add-response-caching-redis.md
rename to docs/content/stories/phase8/8.5.3-add-response-caching-redis.md
diff --git a/docs/stories/phase8/8.5.4-implement-connection-pooling-optimizations.md b/docs/content/stories/phase8/8.5.4-implement-connection-pooling-optimizations.md
similarity index 100%
rename from docs/stories/phase8/8.5.4-implement-connection-pooling-optimizations.md
rename to docs/content/stories/phase8/8.5.4-implement-connection-pooling-optimizations.md
diff --git a/docs/stories/phase8/8.5.5-add-database-read-replicas-support.md b/docs/content/stories/phase8/8.5.5-add-database-read-replicas-support.md
similarity index 100%
rename from docs/stories/phase8/8.5.5-add-database-read-replicas-support.md
rename to docs/content/stories/phase8/8.5.5-add-database-read-replicas-support.md
diff --git a/docs/stories/phase8/8.6.1-install-i18n-library.md b/docs/content/stories/phase8/8.6.1-install-i18n-library.md
similarity index 100%
rename from docs/stories/phase8/8.6.1-install-i18n-library.md
rename to docs/content/stories/phase8/8.6.1-install-i18n-library.md
diff --git a/docs/stories/phase8/8.6.2-add-locale-detection.md b/docs/content/stories/phase8/8.6.2-add-locale-detection.md
similarity index 100%
rename from docs/stories/phase8/8.6.2-add-locale-detection.md
rename to docs/content/stories/phase8/8.6.2-add-locale-detection.md
diff --git a/docs/stories/phase8/8.6.3-create-message-catalogs.md b/docs/content/stories/phase8/8.6.3-create-message-catalogs.md
similarity index 100%
rename from docs/stories/phase8/8.6.3-create-message-catalogs.md
rename to docs/content/stories/phase8/8.6.3-create-message-catalogs.md
diff --git a/docs/stories/phase8/8.6.4-add-translation-support-for-error-messages.md b/docs/content/stories/phase8/8.6.4-add-translation-support-for-error-messages.md
similarity index 100%
rename from docs/stories/phase8/8.6.4-add-translation-support-for-error-messages.md
rename to docs/content/stories/phase8/8.6.4-add-translation-support-for-error-messages.md
diff --git a/docs/stories/phase8/8.7.1-code-review-and-refactoring.md b/docs/content/stories/phase8/8.7.1-code-review-and-refactoring.md
similarity index 100%
rename from docs/stories/phase8/8.7.1-code-review-and-refactoring.md
rename to docs/content/stories/phase8/8.7.1-code-review-and-refactoring.md
diff --git a/docs/stories/phase8/8.7.10-di-setup.md b/docs/content/stories/phase8/8.7.10-di-setup.md
similarity index 100%
rename from docs/stories/phase8/8.7.10-di-setup.md
rename to docs/content/stories/phase8/8.7.10-di-setup.md
diff --git a/docs/stories/phase8/8.7.11-di-container.md b/docs/content/stories/phase8/8.7.11-di-container.md
similarity index 100%
rename from docs/stories/phase8/8.7.11-di-container.md
rename to docs/content/stories/phase8/8.7.11-di-container.md
diff --git a/docs/stories/phase8/8.7.12-database-ent.md b/docs/content/stories/phase8/8.7.12-database-ent.md
similarity index 100%
rename from docs/stories/phase8/8.7.12-database-ent.md
rename to docs/content/stories/phase8/8.7.12-database-ent.md
diff --git a/docs/stories/phase8/8.7.13-health--metrics.md b/docs/content/stories/phase8/8.7.13-health--metrics.md
similarity index 100%
rename from docs/stories/phase8/8.7.13-health--metrics.md
rename to docs/content/stories/phase8/8.7.13-health--metrics.md
diff --git a/docs/stories/phase8/8.7.14-error-bus.md b/docs/content/stories/phase8/8.7.14-error-bus.md
similarity index 100%
rename from docs/stories/phase8/8.7.14-error-bus.md
rename to docs/content/stories/phase8/8.7.14-error-bus.md
diff --git a/docs/stories/phase8/8.7.15-http-server.md b/docs/content/stories/phase8/8.7.15-http-server.md
similarity index 100%
rename from docs/stories/phase8/8.7.15-http-server.md
rename to docs/content/stories/phase8/8.7.15-http-server.md
diff --git a/docs/stories/phase8/8.7.16-opentelemetry.md b/docs/content/stories/phase8/8.7.16-opentelemetry.md
similarity index 100%
rename from docs/stories/phase8/8.7.16-opentelemetry.md
rename to docs/content/stories/phase8/8.7.16-opentelemetry.md
diff --git a/docs/stories/phase8/8.7.17-jwt-authentication.md b/docs/content/stories/phase8/8.7.17-jwt-authentication.md
similarity index 100%
rename from docs/stories/phase8/8.7.17-jwt-authentication.md
rename to docs/content/stories/phase8/8.7.17-jwt-authentication.md
diff --git a/docs/stories/phase8/8.7.18-identity-management.md b/docs/content/stories/phase8/8.7.18-identity-management.md
similarity index 100%
rename from docs/stories/phase8/8.7.18-identity-management.md
rename to docs/content/stories/phase8/8.7.18-identity-management.md
diff --git a/docs/stories/phase8/8.7.19-roles--permissions.md b/docs/content/stories/phase8/8.7.19-roles--permissions.md
similarity index 100%
rename from docs/stories/phase8/8.7.19-roles--permissions.md
rename to docs/content/stories/phase8/8.7.19-roles--permissions.md
diff --git a/docs/stories/phase8/8.7.2-bug-fixes.md b/docs/content/stories/phase8/8.7.2-bug-fixes.md
similarity index 100%
rename from docs/stories/phase8/8.7.2-bug-fixes.md
rename to docs/content/stories/phase8/8.7.2-bug-fixes.md
diff --git a/docs/stories/phase8/8.7.20-authorization-middleware.md b/docs/content/stories/phase8/8.7.20-authorization-middleware.md
similarity index 100%
rename from docs/stories/phase8/8.7.20-authorization-middleware.md
rename to docs/content/stories/phase8/8.7.20-authorization-middleware.md
diff --git a/docs/stories/phase8/8.7.21-audit-logging.md b/docs/content/stories/phase8/8.7.21-audit-logging.md
similarity index 100%
rename from docs/stories/phase8/8.7.21-audit-logging.md
rename to docs/content/stories/phase8/8.7.21-audit-logging.md
diff --git a/docs/stories/phase8/8.7.22-module-interface.md b/docs/content/stories/phase8/8.7.22-module-interface.md
similarity index 100%
rename from docs/stories/phase8/8.7.22-module-interface.md
rename to docs/content/stories/phase8/8.7.22-module-interface.md
diff --git a/docs/stories/phase8/8.7.23-static-registry.md b/docs/content/stories/phase8/8.7.23-static-registry.md
similarity index 100%
rename from docs/stories/phase8/8.7.23-static-registry.md
rename to docs/content/stories/phase8/8.7.23-static-registry.md
diff --git a/docs/stories/phase8/8.7.24-permission-generation.md b/docs/content/stories/phase8/8.7.24-permission-generation.md
similarity index 100%
rename from docs/stories/phase8/8.7.24-permission-generation.md
rename to docs/content/stories/phase8/8.7.24-permission-generation.md
diff --git a/docs/stories/phase8/8.7.25-module-loader.md b/docs/content/stories/phase8/8.7.25-module-loader.md
similarity index 100%
rename from docs/stories/phase8/8.7.25-module-loader.md
rename to docs/content/stories/phase8/8.7.25-module-loader.md
diff --git a/docs/stories/phase8/8.7.26-module-initialization.md b/docs/content/stories/phase8/8.7.26-module-initialization.md
similarity index 100%
rename from docs/stories/phase8/8.7.26-module-initialization.md
rename to docs/content/stories/phase8/8.7.26-module-initialization.md
diff --git a/docs/stories/phase8/8.7.27-blog-module-structure.md b/docs/content/stories/phase8/8.7.27-blog-module-structure.md
similarity index 100%
rename from docs/stories/phase8/8.7.27-blog-module-structure.md
rename to docs/content/stories/phase8/8.7.27-blog-module-structure.md
diff --git a/docs/stories/phase8/8.7.28-domain-model.md b/docs/content/stories/phase8/8.7.28-domain-model.md
similarity index 100%
rename from docs/stories/phase8/8.7.28-domain-model.md
rename to docs/content/stories/phase8/8.7.28-domain-model.md
diff --git a/docs/stories/phase8/8.7.29-repository--service.md b/docs/content/stories/phase8/8.7.29-repository--service.md
similarity index 100%
rename from docs/stories/phase8/8.7.29-repository--service.md
rename to docs/content/stories/phase8/8.7.29-repository--service.md
diff --git a/docs/stories/phase8/8.7.3-performance-profiling.md b/docs/content/stories/phase8/8.7.3-performance-profiling.md
similarity index 100%
rename from docs/stories/phase8/8.7.3-performance-profiling.md
rename to docs/content/stories/phase8/8.7.3-performance-profiling.md
diff --git a/docs/stories/phase8/8.7.30-api-handlers.md b/docs/content/stories/phase8/8.7.30-api-handlers.md
similarity index 100%
rename from docs/stories/phase8/8.7.30-api-handlers.md
rename to docs/content/stories/phase8/8.7.30-api-handlers.md
diff --git a/docs/stories/phase8/8.7.31-integration-tests.md b/docs/content/stories/phase8/8.7.31-integration-tests.md
similarity index 100%
rename from docs/stories/phase8/8.7.31-integration-tests.md
rename to docs/content/stories/phase8/8.7.31-integration-tests.md
diff --git a/docs/stories/phase8/8.7.32-cache-redis.md b/docs/content/stories/phase8/8.7.32-cache-redis.md
similarity index 100%
rename from docs/stories/phase8/8.7.32-cache-redis.md
rename to docs/content/stories/phase8/8.7.32-cache-redis.md
diff --git a/docs/stories/phase8/8.7.33-event-bus.md b/docs/content/stories/phase8/8.7.33-event-bus.md
similarity index 100%
rename from docs/stories/phase8/8.7.33-event-bus.md
rename to docs/content/stories/phase8/8.7.33-event-bus.md
diff --git a/docs/stories/phase8/8.7.34-blob-storage.md b/docs/content/stories/phase8/8.7.34-blob-storage.md
similarity index 100%
rename from docs/stories/phase8/8.7.34-blob-storage.md
rename to docs/content/stories/phase8/8.7.34-blob-storage.md
diff --git a/docs/stories/phase8/8.7.35-email-notification.md b/docs/content/stories/phase8/8.7.35-email-notification.md
similarity index 100%
rename from docs/stories/phase8/8.7.35-email-notification.md
rename to docs/content/stories/phase8/8.7.35-email-notification.md
diff --git a/docs/stories/phase8/8.7.36-schedulerjobs.md b/docs/content/stories/phase8/8.7.36-schedulerjobs.md
similarity index 100%
rename from docs/stories/phase8/8.7.36-schedulerjobs.md
rename to docs/content/stories/phase8/8.7.36-schedulerjobs.md
diff --git a/docs/stories/phase8/8.7.37-multi-tenancy-optional.md b/docs/content/stories/phase8/8.7.37-multi-tenancy-optional.md
similarity index 100%
rename from docs/stories/phase8/8.7.37-multi-tenancy-optional.md
rename to docs/content/stories/phase8/8.7.37-multi-tenancy-optional.md
diff --git a/docs/stories/phase8/8.7.38-opentelemetry.md b/docs/content/stories/phase8/8.7.38-opentelemetry.md
similarity index 100%
rename from docs/stories/phase8/8.7.38-opentelemetry.md
rename to docs/content/stories/phase8/8.7.38-opentelemetry.md
diff --git a/docs/stories/phase8/8.7.39-sentry-integration.md b/docs/content/stories/phase8/8.7.39-sentry-integration.md
similarity index 100%
rename from docs/stories/phase8/8.7.39-sentry-integration.md
rename to docs/content/stories/phase8/8.7.39-sentry-integration.md
diff --git a/docs/stories/phase8/8.7.4-security-audit.md b/docs/content/stories/phase8/8.7.4-security-audit.md
similarity index 100%
rename from docs/stories/phase8/8.7.4-security-audit.md
rename to docs/content/stories/phase8/8.7.4-security-audit.md
diff --git a/docs/stories/phase8/8.7.40-enhanced-logging.md b/docs/content/stories/phase8/8.7.40-enhanced-logging.md
similarity index 100%
rename from docs/stories/phase8/8.7.40-enhanced-logging.md
rename to docs/content/stories/phase8/8.7.40-enhanced-logging.md
diff --git a/docs/stories/phase8/8.7.41-prometheus-metrics.md b/docs/content/stories/phase8/8.7.41-prometheus-metrics.md
similarity index 100%
rename from docs/stories/phase8/8.7.41-prometheus-metrics.md
rename to docs/content/stories/phase8/8.7.41-prometheus-metrics.md
diff --git a/docs/stories/phase8/8.7.42-grafana-dashboards.md b/docs/content/stories/phase8/8.7.42-grafana-dashboards.md
similarity index 100%
rename from docs/stories/phase8/8.7.42-grafana-dashboards.md
rename to docs/content/stories/phase8/8.7.42-grafana-dashboards.md
diff --git a/docs/stories/phase8/8.7.43-rate-limiting.md b/docs/content/stories/phase8/8.7.43-rate-limiting.md
similarity index 100%
rename from docs/stories/phase8/8.7.43-rate-limiting.md
rename to docs/content/stories/phase8/8.7.43-rate-limiting.md
diff --git a/docs/stories/phase8/8.7.44-security-hardening.md b/docs/content/stories/phase8/8.7.44-security-hardening.md
similarity index 100%
rename from docs/stories/phase8/8.7.44-security-hardening.md
rename to docs/content/stories/phase8/8.7.44-security-hardening.md
diff --git a/docs/stories/phase8/8.7.45-unit-tests-80-coverage.md b/docs/content/stories/phase8/8.7.45-unit-tests-80-coverage.md
similarity index 100%
rename from docs/stories/phase8/8.7.45-unit-tests-80-coverage.md
rename to docs/content/stories/phase8/8.7.45-unit-tests-80-coverage.md
diff --git a/docs/stories/phase8/8.7.46-integration-tests.md b/docs/content/stories/phase8/8.7.46-integration-tests.md
similarity index 100%
rename from docs/stories/phase8/8.7.46-integration-tests.md
rename to docs/content/stories/phase8/8.7.46-integration-tests.md
diff --git a/docs/stories/phase8/8.7.47-documentation.md b/docs/content/stories/phase8/8.7.47-documentation.md
similarity index 100%
rename from docs/stories/phase8/8.7.47-documentation.md
rename to docs/content/stories/phase8/8.7.47-documentation.md
diff --git a/docs/stories/phase8/8.7.48-cicd-pipeline.md b/docs/content/stories/phase8/8.7.48-cicd-pipeline.md
similarity index 100%
rename from docs/stories/phase8/8.7.48-cicd-pipeline.md
rename to docs/content/stories/phase8/8.7.48-cicd-pipeline.md
diff --git a/docs/stories/phase8/8.7.49-docker-images.md b/docs/content/stories/phase8/8.7.49-docker-images.md
similarity index 100%
rename from docs/stories/phase8/8.7.49-docker-images.md
rename to docs/content/stories/phase8/8.7.49-docker-images.md
diff --git a/docs/stories/phase8/8.7.5-documentation-review.md b/docs/content/stories/phase8/8.7.5-documentation-review.md
similarity index 100%
rename from docs/stories/phase8/8.7.5-documentation-review.md
rename to docs/content/stories/phase8/8.7.5-documentation-review.md
diff --git a/docs/stories/phase8/8.7.50-deployment-guides.md b/docs/content/stories/phase8/8.7.50-deployment-guides.md
similarity index 100%
rename from docs/stories/phase8/8.7.50-deployment-guides.md
rename to docs/content/stories/phase8/8.7.50-deployment-guides.md
diff --git a/docs/stories/phase8/8.7.51-oidc-support.md b/docs/content/stories/phase8/8.7.51-oidc-support.md
similarity index 100%
rename from docs/stories/phase8/8.7.51-oidc-support.md
rename to docs/content/stories/phase8/8.7.51-oidc-support.md
diff --git a/docs/stories/phase8/8.7.52-graphql-api.md b/docs/content/stories/phase8/8.7.52-graphql-api.md
similarity index 100%
rename from docs/stories/phase8/8.7.52-graphql-api.md
rename to docs/content/stories/phase8/8.7.52-graphql-api.md
diff --git a/docs/stories/phase8/8.7.53-additional-modules.md b/docs/content/stories/phase8/8.7.53-additional-modules.md
similarity index 100%
rename from docs/stories/phase8/8.7.53-additional-modules.md
rename to docs/content/stories/phase8/8.7.53-additional-modules.md
diff --git a/docs/stories/phase8/8.7.54-performance-optimization.md b/docs/content/stories/phase8/8.7.54-performance-optimization.md
similarity index 100%
rename from docs/stories/phase8/8.7.54-performance-optimization.md
rename to docs/content/stories/phase8/8.7.54-performance-optimization.md
diff --git a/docs/stories/phase8/8.7.6-repository-structure.md b/docs/content/stories/phase8/8.7.6-repository-structure.md
similarity index 100%
rename from docs/stories/phase8/8.7.6-repository-structure.md
rename to docs/content/stories/phase8/8.7.6-repository-structure.md
diff --git a/docs/stories/phase8/8.7.7-configuration-system.md b/docs/content/stories/phase8/8.7.7-configuration-system.md
similarity index 100%
rename from docs/stories/phase8/8.7.7-configuration-system.md
rename to docs/content/stories/phase8/8.7.7-configuration-system.md
diff --git a/docs/stories/phase8/8.7.8-logging-foundation.md b/docs/content/stories/phase8/8.7.8-logging-foundation.md
similarity index 100%
rename from docs/stories/phase8/8.7.8-logging-foundation.md
rename to docs/content/stories/phase8/8.7.8-logging-foundation.md
diff --git a/docs/stories/phase8/8.7.9-basic-cicd.md b/docs/content/stories/phase8/8.7.9-basic-cicd.md
similarity index 100%
rename from docs/stories/phase8/8.7.9-basic-cicd.md
rename to docs/content/stories/phase8/8.7.9-basic-cicd.md
diff --git a/docs/content/stories/phase8/README.md b/docs/content/stories/phase8/README.md
new file mode 100644
index 0000000..192a892
--- /dev/null
+++ b/docs/content/stories/phase8/README.md
@@ -0,0 +1,54 @@
+# Phase 8: Advanced Features & Polish (Optional)
+
+## Overview
+Implement advanced optional features including OIDC support, GraphQL API, API versioning, request/response transformation, and additional polish features.
+
+## Tasks
+
+### 8.1 OIDC Support
+- [8.1.1 - Install OIDC Library](./8.1.1-install-githubcomcoreosgo-oidc.md)
+- [8.1.2 - Implement OIDC Provider](./8.1.2-implement-oidc-provider.md)
+- [8.1.3 - Add OIDC Client Support](./8.1.3-add-oidc-client-support.md)
+- [8.1.4 - Document OIDC Setup](./8.1.4-document-oidc-setup-in-docsauthmd.md)
+
+### 8.2 GraphQL API
+- [8.2.1 - Install gqlgen](./8.2.1-install-githubcom99designsgqlgen.md)
+- [8.2.2 - Create GraphQL Schema](./8.2.2-create-graphql-schema.md)
+- [8.2.3 - Implement Resolvers](./8.2.3-implement-resolvers.md)
+- [8.2.4 - Add GraphQL Endpoint](./8.2.4-add-graphql-endpoint-post-graphql.md)
+
+### 8.3 API Enhancements
+- [8.3.1 - Add Request/Response Transformation](./8.3.1-add-requestresponse-transformation.md)
+- [8.3.2 - Add API Key Authentication](./8.3.2-add-api-key-authentication.md)
+
+### 8.4 Advanced Features
+- [8.4.1 - Implement Webhooks](./8.4.1-implement-webhooks.md)
+- [8.4.2 - Add API Versioning](./8.4.2-add-api-versioning.md)
+- [8.4.3 - Create Admin Dashboard](./8.4.3-create-admin-dashboard.md)
+
+### 8.5 Performance Optimization
+- [8.5.1 - Add Database Query Optimization](./8.5.1-add-database-query-optimization.md)
+- [8.5.2 - Implement Response Caching](./8.5.2-implement-response-caching.md)
+- [8.5.3 - Add Connection Pooling](./8.5.3-add-connection-pooling.md)
+
+### 8.6 Security Enhancements
+- [8.6.1 - Add CSRF Protection](./8.6.1-add-csrf-protection.md)
+- [8.6.2 - Implement Content Security Policy](./8.6.2-implement-content-security-policy.md)
+- [8.6.3 - Add Security Headers](./8.6.3-add-security-headers.md)
+
+## Deliverables Checklist
+- [ ] OIDC authentication working
+- [ ] GraphQL API implemented
+- [ ] API versioning in place
+- [ ] Webhooks support
+- [ ] Performance optimizations applied
+- [ ] Security enhancements complete
+
+## Acceptance Criteria
+- OIDC login flow works
+- GraphQL queries and mutations work
+- API versions are properly handled
+- Webhooks are triggered on events
+- Performance meets benchmarks
+- Security headers are properly set
+
diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml
new file mode 100644
index 0000000..4f0035a
--- /dev/null
+++ b/docs/docker-compose.yml
@@ -0,0 +1,18 @@
+version: '3.8'
+
+services:
+ docs:
+ build:
+ context: .
+ dockerfile: Dockerfile
+ container_name: goplt-docs
+ ports:
+ - "8000:8000"
+ volumes:
+ # Mount current directory for live reload during development
+ - .:/docs:ro
+ environment:
+ - MKDOCS_WATCH_MEDIA=true
+ command: mkdocs serve --dev-addr=0.0.0.0:8000
+ restart: unless-stopped
+
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
new file mode 100644
index 0000000..5c55a82
--- /dev/null
+++ b/docs/mkdocs.yml
@@ -0,0 +1,152 @@
+site_name: Go Platform Documentation
+site_description: Documentation for the Go Platform - A SaaS/Enterprise framework
+site_author: Go Platform Team
+site_url: https://yourorg.github.io/platform
+
+# Repository
+repo_name: platform
+repo_url: https://github.com/yourorg/platform
+edit_uri: edit/main/docs/
+
+# Documentation directory (relative to mkdocs.yml location)
+# Markdown files are in the content/ subdirectory
+docs_dir: content
+
+# Theme
+theme:
+ name: material
+ palette:
+ - scheme: default
+ primary: indigo
+ accent: indigo
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ - scheme: slate
+ primary: indigo
+ accent: indigo
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+ features:
+ - navigation.tabs
+ - navigation.sections
+ - navigation.expand
+ - navigation.top
+ - search.suggest
+ - search.highlight
+ - content.code.annotate
+ - content.code.copy
+ icon:
+ logo: material/book-open-variant
+
+# Plugins
+plugins:
+ - search
+ - git-revision-date-localized:
+ enable_creation_date: true
+ fallback_to_build_date: true
+
+# Markdown extensions
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ line_spans: __span
+ pygments_lang_class: true
+ - pymdownx.inlinehilite
+ - pymdownx.snippets
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
+ - pymdownx.tabbed:
+ alternate_style: true
+ - admonition
+ - pymdownx.details
+ - attr_list
+ - md_in_html
+ - toc:
+ permalink: true
+ baselevel: 2
+ - tables
+ - footnotes
+
+# Navigation
+nav:
+ - Home: index.md
+ - Overview:
+ - Requirements: requirements.md
+ - Implementation Plan: plan.md
+ - Playbook: playbook.md
+ - Architecture:
+ - Architecture Overview: architecture.md
+ - Module Architecture: architecture-modules.md
+ - Module Requirements: module-requirements.md
+ - Component Relationships: component-relationships.md
+ - Architecture Decision Records:
+ - ADR Overview: adr/README.md
+ - "Phase 0: Project Setup & Foundation":
+ - "ADR-0001: Go Module Path": adr/0001-go-module-path.md
+ - "ADR-0002: Go Version": adr/0002-go-version.md
+ - "ADR-0003: Dependency Injection Framework": adr/0003-dependency-injection-framework.md
+ - "ADR-0004: Configuration Management": adr/0004-configuration-management.md
+ - "ADR-0005: Logging Framework": adr/0005-logging-framework.md
+ - "ADR-0006: HTTP Framework": adr/0006-http-framework.md
+ - "ADR-0007: Project Directory Structure": adr/0007-project-directory-structure.md
+ - "ADR-0008: Error Handling Strategy": adr/0008-error-handling-strategy.md
+ - "ADR-0009: Context Key Types": adr/0009-context-key-types.md
+ - "ADR-0010: CI/CD Platform": adr/0010-ci-cd-platform.md
+ - "ADR-0011: Code Generation Tools": adr/0011-code-generation-tools.md
+ - "ADR-0012: Logger Interface Design": adr/0012-logger-interface-design.md
+ - "Phase 1: Core Kernel & Infrastructure":
+ - "ADR-0013: Database ORM Selection": adr/0013-database-orm.md
+ - "ADR-0014: Health Check Implementation": adr/0014-health-check-implementation.md
+ - "ADR-0015: Error Bus Implementation": adr/0015-error-bus-implementation.md
+ - "ADR-0016: OpenTelemetry Observability Strategy": adr/0016-opentelemetry-observability.md
+ - "Phase 2: Authentication & Authorization":
+ - "ADR-0017: JWT Token Strategy": adr/0017-jwt-token-strategy.md
+ - "ADR-0018: Password Hashing Algorithm": adr/0018-password-hashing.md
+ - "ADR-0019: Permission DSL Format": adr/0019-permission-dsl-format.md
+ - "ADR-0020: Audit Logging Storage": adr/0020-audit-logging-storage.md
+ - "Phase 3: Module Framework":
+ - "ADR-0021: Module Loading Strategy": adr/0021-module-loading-strategy.md
+ - "Phase 5: Infrastructure Adapters":
+ - "ADR-0022: Cache Implementation": adr/0022-cache-implementation.md
+ - "ADR-0023: Event Bus Implementation": adr/0023-event-bus-implementation.md
+ - "ADR-0024: Background Job Scheduler": adr/0024-job-scheduler.md
+ - "ADR-0025: Multi-tenancy Model": adr/0025-multitenancy-model.md
+ - "Phase 6: Observability & Production Readiness":
+ - "ADR-0026: Error Reporting Service": adr/0026-error-reporting-service.md
+ - "ADR-0027: Rate Limiting Strategy": adr/0027-rate-limiting-strategy.md
+ - "Phase 7: Testing, Documentation & CI/CD":
+ - "ADR-0028: Testing Strategy": adr/0028-testing-strategy.md
+ - Implementation Tasks:
+ - Tasks Overview: stories/README.md
+ - "Phase 0: Project Setup & Foundation": stories/phase0/README.md
+ - "Phase 1: Core Kernel & Infrastructure": stories/phase1/README.md
+ - "Phase 2: Authentication & Authorization": stories/phase2/README.md
+ - "Phase 3: Module Framework": stories/phase3/README.md
+ - "Phase 4: Sample Feature Module (Blog)": stories/phase4/README.md
+ - "Phase 5: Infrastructure Adapters": stories/phase5/README.md
+ - "Phase 6: Observability & Production Readiness": stories/phase6/README.md
+ - "Phase 7: Testing, Documentation & CI/CD": stories/phase7/README.md
+ - "Phase 8: Advanced Features & Polish": stories/phase8/README.md
+ - Task Template: stories/TASK_TEMPLATE.md
+ - Complete Task List: stories/COMPLETE_TASK_LIST.md
+
+# Extra CSS (paths relative to docs_dir)
+extra_css:
+ - assets/css/custom.css
+
+# Extra
+extra:
+ social:
+ - icon: fontawesome/brands/github
+ link: https://github.com/yourorg/platform
+ version:
+ provider: mike
+
+# Copyright
+copyright: Copyright © 2024 Go Platform Team
+
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..08db7ea
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,6 @@
+# MkDocs and dependencies
+mkdocs>=1.5.0
+mkdocs-material>=9.4.0
+mkdocs-git-revision-date-localized-plugin>=1.2.0
+pymdown-extensions>=10.0.0
+