website-and-documentation/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

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

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

```text
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:**

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

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

```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**
   ```bash
   cd resources/edp-likec4  # or doc-likec4
   npm start
   ```
   Opens http://localhost:5173 for real-time preview

3. **Validate Models**
   ```bash
   # From repository root
   task likec4:validate
   ```

4. **Generate Web Components**
   ```bash
   task likec4:generate
   ```

5. **Test in Hugo**
   ```bash
   task serve
   # Open http://localhost:1313
   ```

6. **Commit Changes**
   ```bash
   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

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

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

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

## 📚 LikeC4 Syntax

### Specification Block

Define element and relationship types:

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

### Model Block

Define your architecture:

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

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

```json
{
  "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`:

```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](https://likec4.dev/)
- [LikeC4 GitHub](https://github.com/likec4/likec4)
- [C4 Model](https://c4model.com/)

## 🔧 Troubleshooting

### Web Component Not Rendering

1. Check that view ID exists:
   ```bash
   grep -r "view yourViewId" resources/
   ```

2. Regenerate web component:
   ```bash
   task likec4:generate
   ```

3. Clear browser cache and reload

### Layout Drift Warnings

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

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

### NPM Errors

```bash
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](./README-technicalWriter.md) - Content contributor guide
- [content/en/docs/documentation/local-development.md](./content/en/docs/documentation/local-development.md) - Local development guide