Architecture

• 1: High Level Architecture
• 2: LikeC4 Setup Guide

1 - High Level Architecture

This document describes the high-level architecture of our Enterprise Development Platform (EDP) system.

Interactive Architecture Diagram

Architecture Overview

The Enterprise Development Platform consists of several key components working together to provide a comprehensive development and deployment environment.

Key Components

1. OTC Foundry - Central management and orchestration layer
2. Per-Tenant EDP - Isolated development environments for each tenant
3. FaaS Environment - Function-as-a-Service deployment targets on Open Telekom Cloud
4. Cloud Services - Managed services including databases, storage, and monitoring

Deployment Environments

• Development Environment (*.t09.de) - For platform team development and testing
• Production Environment (*.buildth.ing) - For production workloads and tenant services

Component Details

The interactive diagram above shows the relationships between different components and how they interact within the system architecture. You can explore the diagram by clicking on different elements to see more details.

Infrastructure Components

• Kubernetes Clusters - Container orchestration using OTC CCE (Cloud Container Engine)
• ArgoCD - GitOps continuous deployment and application lifecycle management
• Forgejo - Git repository management and CI/CD pipelines
• Observability Stack - Monitoring (Prometheus, Grafana), logging (Loki), and alerting

Security and Management

• Keycloak - Identity and access management (IAM)
• OpenBao - Secrets management (Hashicorp Vault fork)
• External Secrets Operator - Kubernetes secrets integration
• Crossplane - Infrastructure as Code and cloud resource provisioning

Developer Experience

• Backstage - Internal developer portal and service catalog
• Forgejo Actions - CI/CD pipeline execution
• Development Workflows - GitOps-based inner and outer loop workflows

Setup and Maintenance

To update or modify the architecture diagrams:

1. Edit the .c4 files in resources/likec4/

2. Regenerate the webcomponent:

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

3. Commit both the model changes and the regenerated JavaScript file

For more information, see the LikeC4 Integration Guide.

2 - LikeC4 Setup Guide

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.