{{PROJECT_NAME}}

{{PROJECT_DESCRIPTION}}

Quick Start

🐳 Docker Compose (Recommended)

Development Server with Live Reload:

# Start development server
docker-compose up mkdocs-dev

# Or run in background
docker-compose up -d mkdocs-dev

# View at http://localhost:8000

Production Build:

# Build and start production server
docker-compose build {{PROJECT_SLUG}}-docs
docker-compose up -d {{PROJECT_SLUG}}-docs

# View at http://localhost:8080

Using Makefile (Linux/macOS/WSL):

# Show all available commands
make help

# Start development server
make dev

# Start production server
make quick-prod

# View logs
make logs-dev

Prerequisites

• Python 3.8 or higher (Python 3.11+ recommended)
• Git
• Docker & Docker Compose

Setup

1. Clone and setup:

   cd {{PROJECT_REPO_NAME}}
   python setup.py

2. Start development server:

   python setup.py serve

3. Open browser to http://127.0.0.1:8000

Manual Setup

If you prefer manual setup:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Serve documentation
mkdocs serve

Documentation Structure

docs/
├── index.md                    # Homepage
├── executive_summary.md        # Executive Summary
├── scope_objectives.md         # Scope & Objectives
├── principles.md               # Architecture Principles
├── togaf_adm.md               # TOGAF ADM Overview
├── as_is.md                   # Current State Analysis
├── to_be_architecture.md      # Target Architecture
├── business_architecture.md   # Business Architecture
├── application_architecture.md # Application Architecture
├── data_architecture.md       # Data Architecture
├── technology_architecture.md # Technology Architecture
├── security_compliance.md     # Security & Compliance
├── observability_operations.md # Observability & Operations
├── opportunities_roadmap.md   # Opportunities & Roadmap
├── migration_checklists.md    # Migration & Checklists
├── risks_mitigations.md       # Risks & Mitigations
├── governance_kpis.md         # Governance & KPIs
├── change_management.md       # Change Management
├── appendices.md              # Appendices
├── glossary.md                # Glossary
└── adr/                       # Architecture Decision Records
    ├── README.md              # ADR Overview
    ├── template.md            # ADR Template
    └── 001-example.md         # Example ADR

Customization

Step 1: Configure Variables

Replace the placeholder variables in all files:

Variable	Description	Example
{{PROJECT_NAME}}	Full project name	"Identity Platform Migration"
{{PROJECT_SLUG}}	URL-safe project name	"identity-platform"
{{PROJECT_DESCRIPTION}}	Brief description	"Migration to cloud-native identity..."
{{REPO_URL}}	GitHub repository URL	"https://github.com/org/repo"
{{REPO_NAME}}	Repository name	"org/repo"
{{COMPANY_URL}}	Company website	"https://itlusions.nl"

Step 2: Customize Content

1. Update mkdocs.yml: Replace placeholders with actual values
2. Customize navigation: Modify the nav section based on your needs
3. Update templates: Fill in the template content in each .md file
4. Add project-specific sections: Create additional pages as needed

Step 3: Configure Build Pipeline

1. Update .github/workflows/build-deploy.yml: Replace project-specific values
2. Configure Helm chart: Update charts/ directory with your project details
3. Setup ArgoCD: Configure argocd/ files for deployment

Building and Deployment

Local Development

# Start development server with live reload
mkdocs serve

# Build static site
mkdocs build

PowerShell Build Script (Windows)

Use the provided PowerShell script for common tasks:

# Show available commands
.\build.ps1 help

# Install dependencies
.\build.ps1 install

# Build and serve locally
.\build.ps1 serve

# Build documentation
.\build.ps1 build

# Test documentation
.\build.ps1 test

# Generate Kubernetes manifests
.\build.ps1 helm-template

# Lint Helm chart
.\build.ps1 helm-lint

# Run all CI tests locally
.\build.ps1 ci-test

Makefile (Linux/macOS)

# Show available targets
make help

# Install dependencies
make install

# Build and test
make all

# Generate manifests
make helm-template

# Validate Kubernetes manifests
make helm-validate

CI/CD Pipeline

The GitHub Actions pipeline includes:

• Validation: Documentation build, Helm chart linting
• Security: Docker image vulnerability scanning with Trivy
• Deployment: Automated deployment to staging/production environments
• Kubernetes: Manifest generation and validation

Features

• 📖 Rich Documentation: Comprehensive TOGAF-based architecture documentation
• 🎨 Material Design: Modern, responsive theme with dark/light mode
• 🔍 Full-text Search: Built-in search functionality
• 📊 Mermaid Diagrams: Interactive architecture diagrams
• 📱 Mobile Friendly: Responsive design for all devices
• 🔗 Cross-references: Easy navigation between sections
• 💻 Code Highlighting: Syntax highlighting for multiple languages
• 🏗️ GitOps Ready: Complete CI/CD and deployment automation

TOGAF ADM Compliance

This template follows the TOGAF Architecture Development Method (ADM) structure:

• Preliminary Phase: Foundation and principles
• Phase A: Architecture Vision
• Phase B: Business Architecture
• Phase C: Information Systems Architecture
• Phase D: Technology Architecture
• Phase E: Opportunities and Solutions
• Phase F: Migration Planning
• Phase G: Implementation Governance
• Phase H: Architecture Change Management

Each phase includes proper deliverables and documentation templates.

License

{{LICENSE_INFO}}

---

For questions or contributions, please refer to the project repository or contact {{CONTACT_INFO}}.