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

---
title: "LikeC4 Setup Guide"
linkTitle: "Setup"
weight: 10
description: >
  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:

```bash
cd resources/likec4
npm install
```

### 2. Generate the Web Component

Create the web component that Hugo will load:

```bash
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:

```html
<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:

```bash
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:

```markdown
<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/`:

```bash
# 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:

```bash
cd resources/likec4

# Start preview server
npx likec4 start

# Opens browser at http://localhost:5173
```

### 3. Regenerate Web Component

After making changes:

```bash
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:

```bash
# From repository root
hugo server -D

# Open http://localhost:1313
```

### 5. Commit Changes

Commit both the model files and the regenerated web component:

```bash
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:

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

### Multiple Diagrams Per Page

You can include multiple diagrams on a single page:

```html
<!-- 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:

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

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

```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:**
   ```bash
   ls -lh static/js/likec4-webcomponent.js
   ```
3. **Regenerate if missing:**
   ```bash
   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:
  ```bash
  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:

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

## Resources

- [LikeC4 Documentation](https://likec4.dev/)
- [C4 Model](https://c4model.com/)
- [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
- [Hugo Documentation](https://gohugo.io/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.