website-and-documentation/doc/README-likec4.md

LikeC4 Architecture Modeling

This repository contains two distinct LikeC4 architecture projects for C4 model-based architecture visualization.

📁 Project Structure

resources/edp-likec4/

Enterprise Developer Platform (EDP) Architecture

Contains architecture models for the platform itself - the systems, services, and infrastructure that make up the EDP.

• Purpose: Document what we build
• Models: Platform components, services, deployment environments
• Views: System overviews, component details, deployment diagrams

resources/doc-likec4/

Documentation Platform Architecture

Contains architecture models that explain how this documentation system works - the Hugo/Docsy setup, CI/CD pipeline, and deployment process.

• Purpose: Document how we document (meta-documentation)
• Models: Hugo, LikeC4, Taskfile, GitHub Actions, Edge deployment
• Views: Documentation workflow, CI/CD pipeline, testing capabilities

🚀 Quick Start

1. Install Dependencies

# In the LikeC4 project directory
cd resources/edp-likec4
# or
cd resources/doc-likec4

# Install dependencies (only once)
npm install

2. Start LikeC4 Preview

Preview your architecture models in the browser:

npm start
# Opens http://localhost:5173

This launches the interactive LikeC4 viewer where you can:

• Navigate through all views
• Explore relationships
• Test changes in real-time

3. Edit Models

Edit .c4 files in your project:

Example structure:

resources/edp-likec4/
├── models/
│   ├── systems.c4       # System definitions
│   ├── services.c4      # Service components
│   └── infrastructure.c4 # Infrastructure elements
├── views/
│   ├── overview.c4      # High-level views
│   ├── deployment/      # Deployment views
│   └── components/      # Component details
├── deployment/
│   └── environments.c4  # Deployment configurations
└── likec4.config.json   # LikeC4 configuration

Example C4 model:

specification {
  element system
  element service
  element database
}

model {
  mySystem = system 'My System' {
    description 'System description'
    
    backend = service 'Backend API' {
      description 'REST API service'
    }
    
    db = database 'Database' {
      description 'PostgreSQL database'
    }
    
    backend -> db 'reads/writes'
  }
}

views {
  view systemOverview {
    title "System Overview"
    
    include mySystem
    
    autoLayout TopBottom
  }
}

4. Generate Web Components

After editing models, generate the web component for Hugo:

# From repository root
task likec4:generate

This creates static/js/likec4-webcomponent.js (~2-3 MB) with all views.

5. Embed in Hugo

Use the likec4-view shortcode in Markdown:

{{</* likec4-view view="systemOverview" project="architecture" title="System Overview" */>}}

Parameters:

• view - View ID from your C4 model (required)
• project - "architecture" (edp-likec4) or "documentation-platform" (doc-likec4)
• title - Optional custom title

🔄 Development Workflow

Architecture Changes Workflow

1. Edit Models

   • Modify .c4 files in models/ or views/

2. Preview Changes

   cd resources/edp-likec4  # or doc-likec4
   npm start
   

   Opens http://localhost:5173 for real-time preview

3. Validate Models

   # From repository root
   task likec4:validate
   

4. Generate Web Components

   task likec4:generate
   

5. Test in Hugo

   task serve
   # Open http://localhost:1313
   

6. Commit Changes

   git add resources/edp-likec4/
   git add resources/doc-likec4/
   git add static/js/likec4-webcomponent.js
   git commit -m "feat: update architecture diagrams"
   

Available Tasks

task likec4:generate    # Generate web components from all projects
task likec4:validate    # Validate C4 models (ignore layout drift)
task likec4:update      # Update LikeC4 to latest version

🔍 Finding View IDs

To find available view IDs for embedding:

# In the project directory
cd resources/edp-likec4
grep -r "^view " views/ models/ --include="*.c4"

# Or search all C4 files
grep -r "view\s\+\w" . --include="*.c4"

View IDs are defined in your C4 files:

views {
  view myViewId {        # ← This is the view ID
    title "My View"
    // ...
  }
}

📚 LikeC4 Syntax

Specification Block

Define element and relationship types:

specification {
  element person
  element system
  element container
  element component
  
  relationship async
  relationship sync
}

Model Block

Define your architecture:

model {
  customer = person 'Customer' {
    description 'End user'
  }
  
  system = system 'My System' {
    frontend = container 'Frontend' {
      description 'React application'
    }
    
    backend = container 'Backend' {
      description 'Node.js API'
    }
    
    frontend -> backend 'API calls'
  }
  
  customer -> system.frontend 'uses'
}

Views Block

Create diagrams:

views {
  view overview {
    title "System Overview"
    
    include *
    
    autoLayout TopBottom
  }
  
  view systemDetail {
    title "System Details"
    
    include system.*
    
    autoLayout LeftRight
  }
}

🎯 Common View IDs

EDP Platform (resources/edp-likec4/)

• edp - EDP overview
• landscape - Developer landscape
• otc-faas - OTC FaaS deployment
• edpbuilderworkflow - Builder workflow
• Component views: keycloak, forgejo, argoCD, etc.

Documentation Platform (resources/doc-likec4/)

• overview - Complete system overview
• localDevelopment - Technical Writer workflow
• cicdPipeline - CI/CD pipeline
• deploymentFlow - Edge deployment
• fullWorkflow - End-to-end workflow
• testingCapabilities - Testing overview

🛠️ Configuration

likec4.config.json

Each project has a configuration file:

{
  "sources": [
    "models/**/*.c4",
    "views/**/*.c4",
    "deployment/**/*.c4"
  ]
}

This tells LikeC4 where to find your model files.

🔗 Integration with Hugo

How It Works

1. Source: .c4 files contain your architecture models
2. Codegen: task likec4:generate creates a self-contained web component
3. Static Asset: static/js/likec4-webcomponent.js bundled with Hugo site
4. Custom Element: Web Components standard enables <likec4-view> tag
5. Rendering: Shadow DOM renders interactive diagrams

Web Component Registration

The web component is automatically loaded via layouts/partials/hooks/head-end.html:

<script type="module" src="/js/likec4-loader.js"></script>

This loader dynamically loads the LikeC4 web component only on pages that use it.

Styling

Custom styles in static/css/likec4-styles.css:

• Dark mode support
• Telekom magenta color scheme
• Responsive sizing
• Loading indicators

📖 Resources

• LikeC4 Documentation
• LikeC4 GitHub
• C4 Model

🔧 Troubleshooting

Web Component Not Rendering

1. Check that view ID exists:

   grep -r "view yourViewId" resources/
   

2. Regenerate web component:

   task likec4:generate
   

3. Clear browser cache and reload

Layout Drift Warnings

Layout drift warnings during validation are expected and can be ignored:

task likec4:validate        # Ignores layout drift
task likec4:validate:layout # Full validation including layout

NPM Errors

cd resources/edp-likec4
rm -rf node_modules package-lock.json
npm install

🎓 Learn More

For detailed usage in content creation, see:

• README-technicalWriter.md - Content contributor guide
• content/en/docs/documentation/local-development.md - Local development guide