website-and-documentation/resources/doc-likec4/documentation-platform.c4

specification {
  element person {
    style {
      shape person
    }
  }
  element system {
    style {
      shape rectangle
    }
  }
  element tool {
    style {
      shape rectangle
    }
  }
  element component {
    style {
      shape rectangle
    }
  }
  element process {
    style {
      shape rectangle
    }
  }
  element environment {
    style {
      shape cylinder
    }
  }
  element repository {
    style {
      shape storage
    }
  }
}

model {

// === Personas ===
technicalWriter = person 'Technical Writer' {
  description 'Content creator and maintainer of the developer platform documentation'
  technology 'Hugo, Markdown, LikeC4'
}

// === Documentation Platform System ===
docPlatform = system 'Documentation Platform' {
  description 'Hugo-based documentation system with integrated architecture visualization'
  
  // Core Components
  hugoSite = component 'Hugo Site' {
    description 'Static site generator based on Hugo with Docsy theme'
    technology 'Hugo Extended, Docsy'
  }
  
  contentRepo = repository 'Content Repository' {
    description 'Markdown files, images, and configuration'
    technology 'Git, Markdown'
    
    contentPages = component 'Content Pages' {
      description 'Documentation pages in Markdown format'
      technology 'Markdown'
    }
    
    archModels = component 'Architecture Models' {
      description 'LikeC4 architecture models and views'
      technology 'LikeC4 DSL'
    }
    
    assets = component 'Static Assets' {
      description 'CSS, JavaScript, images, fonts'
      technology 'CSS, JavaScript'
    }
  }
  
  likec4Integration = component 'LikeC4 Integration' {
    description 'Architecture diagram visualization embedded in documentation'
    technology 'LikeC4, Web Components'
  }
  
  // Build & Development Tools
  taskfile = tool 'Taskfile' {
    description 'Task automation for local development, build, and testing'
    technology 'Task (go-task)'
  }
  
  devServer = process 'Development Server' {
    description 'Local Hugo server with hot reload for content development'
    technology 'Hugo Server'
  }
}

// === CI/CD Pipeline ===
cicdPipeline = system 'CI/CD Pipeline' {
  description 'Automated testing and deployment pipeline'
  
  githubActions = process 'GitHub Actions' {
    description 'Automated testing workflow on push/PR'
    technology 'GitHub Actions'
    
    testBuild = component 'Build Test' {
      description 'Hugo build validation'
      technology 'Hugo'
    }
    
    testMarkdown = component 'Markdown Lint' {
      description 'Markdown syntax and style checking'
      technology 'markdownlint'
    }
    
    testHtml = component 'HTML Validation' {
      description 'Generated HTML validation'
      technology 'htmlvalidate'
    }
    
    testLinks = component 'Link Checker' {
      description 'Broken link detection'
      technology 'htmltest'
    }
  }
  
  containerBuild = process 'Container Build' {
    description 'OCI/Docker image creation with Hugo site'
    technology 'Docker'
  }
}

// === Deployment ===
deploymentEnv = system 'Deployment Environment' {
  description 'Edge deployment infrastructure'
  
  edgeConnect = environment 'Edge Connect' {
    description 'Edge deployment orchestration platform'
    technology 'EdgeConnect'
  }
  
  k8sCluster = environment 'Kubernetes Cluster' {
    description 'K8s cluster on edge cloudlet (Munich)'
    technology 'Kubernetes'
    
    docService = component 'Documentation Service' {
      description 'LoadBalancer service exposing docs on port 80'
      technology 'K8s Service'
    }
    
    docDeployment = component 'Documentation Deployment' {
      description 'Pod running Hugo-generated static site'
      technology 'K8s Deployment, Nginx'
    }
  }
}

// === Relationships: Technical Writer Workflow ===
technicalWriter -> contentRepo.contentPages 'writes documentation' {
  description 'Creates and updates Markdown content'
}

technicalWriter -> contentRepo.archModels 'creates architecture models' {
  description 'Defines C4 models with LikeC4 DSL'
}

technicalWriter -> taskfile 'executes local tasks' {
  description 'task serve, task build, task test'
}

// === Relationships: Local Development ===
taskfile -> devServer 'starts' {
  description 'task serve'
}

devServer -> hugoSite 'renders' {
  description 'Live reload on content changes'
}

hugoSite -> contentRepo 'reads content from' {
  description 'Processes Markdown and templates'
}

hugoSite -> likec4Integration 'integrates' {
  description 'Embeds architecture diagrams'
}

likec4Integration -> contentRepo.archModels 'visualizes' {
  description 'Renders C4 models as interactive diagrams'
}

// === Relationships: Testing ===
taskfile -> githubActions.testBuild 'can run locally' {
  description 'task test:build'
}

taskfile -> githubActions.testMarkdown 'can run locally' {
  description 'task test:markdown'
}

taskfile -> githubActions.testHtml 'can run locally' {
  description 'task test:html'
}

taskfile -> githubActions.testLinks 'can run locally' {
  description 'task test:links'
}

// === Relationships: CI/CD ===
contentRepo -> githubActions 'triggers on push/PR' {
  description 'Webhook on main branch'
}

githubActions.testBuild -> hugoSite 'builds' {
  description 'hugo --gc --minify'
}

githubActions.testMarkdown -> contentRepo.contentPages 'validates' {
  description 'Lints Markdown files'
}

githubActions.testHtml -> hugoSite 'validates output' {
  description 'Checks generated HTML'
}

githubActions.testLinks -> hugoSite 'checks links in' {
  description 'Detects broken links'
}

githubActions -> containerBuild 'triggers on success' {
  description 'Builds Docker image with Hugo output'
}

containerBuild -> hugoSite 'packages' {
  description 'public/ directory served by Nginx'
}

// === Relationships: Deployment ===
containerBuild -> deploymentEnv.edgeConnect 'pushes image to' {
  description 'Tagged container image'
}

deploymentEnv.edgeConnect -> deploymentEnv.k8sCluster 'deploys to' {
  description 'Via edgeconnectdeployment.yaml'
}

deploymentEnv.k8sCluster.docDeployment -> deploymentEnv.k8sCluster.docService 'exposed by' {
  description 'Port 80'
}

technicalWriter -> deploymentEnv.k8sCluster.docService 'views published docs' {
  description 'HTTPS access to live documentation'
}

}

// === Views ===

views {

  view overview of docPlatform {
    title 'Documentation Platform Overview'
    description 'High-level overview of the Hugo-based documentation platform for technicalWriters'
    
    include *
    
    style technicalWriter {
      color green
    }
    style docPlatform {
      color blue
    }
  }

  view localDevelopment of docPlatform {
    title 'Local Development Workflow'
    description 'How a technicalWriter works locally with the documentation'
    
    include technicalWriter
    include docPlatform
    include docPlatform.contentRepo -> *
    include docPlatform.hugoSite
    include docPlatform.likec4Integration
    include docPlatform.taskfile
    include docPlatform.devServer
    
    style technicalWriter {
      color green
    }
    style docPlatform.taskfile {
      color amber
    }
    style docPlatform.devServer {
      color amber
    }
  }

  view cicdPipeline of cicdPipeline {
    title 'CI/CD Pipeline'
    description 'Automated testing and container build process'
    
    include cicdPipeline
    include cicdPipeline.githubActions -> *
    include cicdPipeline.containerBuild
    include docPlatform.contentRepo
    include docPlatform.hugoSite
    
    style cicdPipeline.githubActions {
      color blue
    }
    style cicdPipeline.containerBuild {
      color indigo
    }
  }

  view deploymentFlow {
    title 'Deployment to Edge Environment'
    description 'How the documentation is deployed to the edge infrastructure'
    
    include cicdPipeline.containerBuild
    include deploymentEnv
    include deploymentEnv.edgeConnect
    include deploymentEnv.k8sCluster -> *
    include technicalWriter
    
    style deploymentEnv {
      color muted
    }
    style deploymentEnv.k8sCluster {
      color secondary
    }
  }

  view fullWorkflow {
    title 'Complete Technical Writer Workflow'
    description 'End-to-end view from content creation to published documentation'
    
    include technicalWriter
    include docPlatform.contentRepo
    include docPlatform.taskfile
    include cicdPipeline.githubActions
    include cicdPipeline.containerBuild
    include deploymentEnv.edgeConnect
    include deploymentEnv.k8sCluster
    
    style technicalWriter {
      color green
    }
    style docPlatform.taskfile {
      color amber
    }
    style cicdPipeline.githubActions {
      color blue
    }
    style deploymentEnv.k8sCluster {
      color secondary
    }
  }

  view testingCapabilities of cicdPipeline.githubActions {
    title 'Testing Capabilities'
    description 'All automated tests that ensure documentation quality'
    
    include *
    include docPlatform.hugoSite
    include docPlatform.contentRepo.contentPages
    include docPlatform.taskfile
    
    style cicdPipeline.githubActions {
      color blue
    }
  }

}