website-and-documentation/content/en/docs/architecture/setup.md

title	linkTitle	weight	description
LikeC4 Setup Guide	Setup	10	How to set up and use LikeC4 interactive architecture diagrams

This guide explains how to set up and use LikeC4 interactive architecture diagrams in this documentation.

Overview

LikeC4 enables you to create interactive C4 architecture diagrams as code. The diagrams are defined in .c4 files and compiled into a web component that can be embedded in any HTML page.

Prerequisites

• Node.js (v18 or later)
• npm or yarn

Initial Setup

1. Install Dependencies

Navigate to the LikeC4 directory and install dependencies:

cd resources/likec4
npm install

2. Generate the Web Component

Create the web component that Hugo will load:

npx likec4 codegen webcomponent \
  --webcomponent-prefix likec4 \
  --outfile ../../static/js/likec4-webcomponent.js

This command:

• Reads all .c4 files from models/ and views/
• Generates a single JavaScript file with all architecture views
• Outputs to static/js/likec4-webcomponent.js

3. Verify Integration

The integration should already be configured in:

• hugo.toml - Contains params.likec4.enable = true
• layouts/partials/hooks/head-end.html - Loads CSS and loader script
• static/css/likec4-styles.css - Diagram styling
• static/js/likec4-loader.js - Dynamic module loader

Directory Structure

resources/likec4/
├── models/          # C4 model definitions
│   ├── components/  # Component models
│   ├── containers/  # Container models
│   ├── context/     # System context
│   └── code/        # Code-level workflows
├── views/           # View definitions
│   ├── deployment/  # Deployment views
│   ├── edp/         # EDP views
│   ├── high-level-concept/  # Conceptual views
│   └── dynamic/     # Process flows
├── package.json     # Dependencies
└── INTEGRATION.md   # Integration docs

Using in Documentation

Basic Usage

Add this to any Markdown file:

<div class="likec4-container">
    <div class="likec4-header">
        Your Diagram Title
    </div>
    <likec4-view view-id="YOUR-VIEW-ID" browser="true"></likec4-view>
    <div class="likec4-loading" id="likec4-loading">
        Loading architecture diagram...
    </div>
</div>

Available View IDs

To find available view IDs, search the .c4 files:

cd resources/likec4
grep -r "view\s\+\w" views/ models/ --include="*.c4"

Common views:

• otc-faas - OTC FaaS deployment
• edp - EDP overview
• landscape - Developer landscape
• edpbuilderworkflow - Builder workflow
• keycloak - Keycloak component

With Hugo Alert

Combine with Docsy alerts for better UX:

<div class="likec4-container">
    <div class="likec4-header">
        System Architecture
    </div>
    <likec4-view view-id="otc-faas" browser="true"></likec4-view>
    <div class="likec4-loading" id="likec4-loading">
        Loading...
    </div>
</div>

{{</* alert title="Note" */>}}
Click on components in the diagram to explore the architecture.
{{</* /alert */>}}

Workflow for Changes

1. Modify Architecture Models

Edit the .c4 files in resources/likec4/:

# Edit a model
vi resources/likec4/models/containers/argocd.c4

# Or edit a view
vi resources/likec4/views/deployment/otc/otc-faas.c4

2. Preview Changes Locally

Use the LikeC4 CLI to preview:

cd resources/likec4

# Start preview server
npx likec4 start

# Opens browser at http://localhost:5173

3. Regenerate Web Component

After making changes:

cd resources/likec4
npx likec4 codegen webcomponent \
  --webcomponent-prefix likec4 \
  --outfile ../../static/js/likec4-webcomponent.js

4. Test in Hugo

Start the Hugo development server:

# From repository root
hugo server -D

# Open http://localhost:1313

5. Commit Changes

Commit both the model files and the regenerated web component:

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

Advanced Configuration

Custom Styling

Modify static/css/likec4-styles.css to customize appearance:

.likec4-container {
    height: 800px;  /* Adjust height */
    border-radius: 8px;  /* Rounder corners */
}

Multiple Diagrams Per Page

You can include multiple diagrams on a single page:

<!-- First diagram -->
<div class="likec4-container">
    <div class="likec4-header">Deployment View</div>
    <likec4-view view-id="otc-faas" browser="true"></likec4-view>
    <div class="likec4-loading">Loading...</div>
</div>

<!-- Second diagram -->
<div class="likec4-container">
    <div class="likec4-header">Component View</div>
    <likec4-view view-id="edp" browser="true"></likec4-view>
    <div class="likec4-loading">Loading...</div>
</div>

Disable for Specific Pages

Add to page front matter:

---
title: "My Page"
params:
  disable_likec4: true
---

Then update layouts/partials/hooks/head-end.html:

{{ if and .Site.Params.likec4.enable (not .Params.disable_likec4) }}
<!-- LikeC4 scripts -->
{{ end }}

Troubleshooting

Diagram Not Loading

1. Check browser console (F12 → Console)
2. Verify webcomponent exists:

   ls -lh static/js/likec4-webcomponent.js
   

3. Regenerate if missing:

   cd resources/likec4
   npm install
   npx likec4 codegen webcomponent \
     --webcomponent-prefix likec4 \
     --outfile ../../static/js/likec4-webcomponent.js
   

View Not Found

• Check view ID matches exactly (case-sensitive)
• Search for the view in .c4 files:

  grep -r "view otc-faas" resources/likec4/
  

Styling Issues

• Clear browser cache (Ctrl+Shift+R)
• Check static/css/likec4-styles.css is loaded in browser DevTools → Network

Build Errors

If LikeC4 codegen fails:

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

Resources

• LikeC4 Documentation
• C4 Model
• Web Components
• Hugo Documentation

Migration Notes

This LikeC4 integration was migrated from the edp-doc repository. This repository (ipceicis-developerframework) is now the primary source for architecture models.

The edp-doc repository can reference these models via git submodule if needed.