Kroki

1. Application

2. Introduction

2.1 Document purpose

This document is a low level design - LLD which aims to describe how the architecture evoked in high level design - HLD will be implemented. This document will describe the protocols used in the target architecture, how to implement them and any modifications made to their default behavior. Once validated by Thales, this document will then serve as a basis for the implementation of configurations on equipment.

2.2 Document scope

This document is not a manual and is not intended to replace the reference literature describing with great precision all network protocols.

The protocols used will be briefly described as well as the modifications made to their default behavior.

2.3 Referenced documentation

3. Component general description

This component is part of Software Factory as a Product (SWaaP), and it is visible in the TASD .

This component permits to expose Kroki services to any Software engineer (end user of SWaaP). It is mainly based on Kroki. Kroki service is exposed using:

• Kroki API(s)

4. Functional & Business Requirements

No formal list of requirements has been expressed by clients. It is designed and developed based on business use cases.

4.1 Feature summary

• Render diagram-as-code images from code for the following diagram-as-code types:

  • ActDiag
  • BPMN
  • BlockDiag
  • Bytefield
  • C4withPlantUML
  • D2
  • DBML
  • Ditaa
  • Dot
  • Erd
  • Excalidraw
  • GraphViz
  • Mermaid
  • Nomnoml
  • NwDiag
  • PacketDiag
  • Pikchr
  • PlantUML
  • RackDiag
  • SeqDiag
  • Structurizr
  • Svgbob
  • Symbolator
  • TikZ
  • UMlet
  • Vega
  • Vega-Lite
  • WaveDrom
  • WireViz

• Rendering diagrams as code directly in GitLab using multiple markup languages:

  • AsciiDoc
  • Markdown
  • reStructuredText
  • Textile

4.2 Prerequisites

Every prerequisites of the product are applicable to this component. See the TASD .

4.3 Variability

No variability is supported.

5. Architecture decision record

Here is a list of decisions:

Table 3 - List of architecture decision record.

5.1 ADR-Kroki-001: Add Kroki as a component of the product

5.1.1 Status: Accepted

• Creation of sf-package in September 2022
• Recorded in SF organization in April 2023

5.1.2 Context

• See ADR007 in TASD .

5.1.3 Decision

• Introduce Kroki in the product.

5.1.4 Consequences

• Update documents: TASD
• Add associated LLD & SCOM

6. Architecture description

6.1 Business architecture and allocation to services

You will find in Figure 1 business architecture for software code and CI/CD engineering allocated to services:

Figure 1 - Business architecture allocated to services.

Note: in dash, external items.

6.2 Application architecture

Physical architecture is described in Figure 2 :

Figure 2 - Physical architecture

Once GitLab integration is enabled, here is the flow.

sequenceDiagram
    participant Browser
    participant GitLab
    participant Kroki
    Browser->>GitLab: GET [one GitLab page with embedded Kroki diagrams as DATA]
    GitLab-->>Browser: return page with kroki url inc data
    Browser->>Kroki: GET https://kroki.SF-DOMAIN/[diagram-type]/svg/[DATA]
    Kroki->>Browser: return svg

Figure 3 - Sequence diagram

Kroki is using these external services:

• A Software Factory or mirror for deployment (PRE_001)
• Kubernetes with Flux (PRE_002, PRE_003)

[!NOTE] Starting with SWaaP 7.2, which includes Kroki 1.3.0 helmchart, Kroki is no longer exposed externally to the cluster via an ingress by default, thus the communication between GitLab and Kroki happens internally. If you deployed Kroki with the recommended parameters, GitLab should point to Kroki’s internal Kubernetes service name ; Kroki URL parameter should be set to http://kroki.kroki.svc.cluster.local:8000

6.2.1 Components

6.2.1.1 Authentication

This component is the entry point of Kroki. The server is using Vert.x and will route the request to different services.

6.2.1.2 Mermaid

A companion web server written in JavaScript (powered by micro) that provides Mermaid diagram library.

6.2.1.3 BPMN

A companion web server written in JavaScript (powered by micro) that provides bpmn-js to render BPMN diagrams.

6.2.1.4 Excalidraw

A companion web server written in JavaScript (powered by micro) that provides Excalidraw to render diagrams.

6.2.1.4 Diagrams.net (experimental) - disabled by default

A companion web server written in JavaScript (powered by micro) that provides diagrams.net to render diagrams.

6.2.2 User management

Kroki doesn’t require authentication, allowing users to access its features without needing to log in or create an account.

6.3 Delivery

Component is part of the Software Factory as a Product (SWaaP) delivery. See TASD for more details.

6.3.1 Latest Version

• Latest version editor
  • Component registry: TBC on main branch
  • Helm chart repository
• Reference Component repository
• SWaaP integration part

6.3.2 Version 1.3.0

• Component registry:
  • kroki-bpmn
  • kroki-excalidraw
  • kroki
  • kroki-mermaid
• Helm chart registry: in SF delivery
• SWaaP integration part
• Component Merge Request in Reference
• K6 Test report: pipeline
  • light_load
  • heavy_load
• Security Report:
  • SCA Report

6.4 Infrastructure architecture

6.4.1 Software Factory API

Here is a list of services that can be integrated with the Kroki.

7. Operational and maintenance

In this chapter you will find strategy and policy. Detail implementation will be described in the SCOM.

7.1 Life cycle policy

Cadence of version is described in the Product Lifecycle .

7.2 License

Kroki is an open source project licensed under the MIT license.

7.3 Deployment

The component is deployed as a standard component using Flux and SWaaP packaging. See TASD for more details.

7.4 IAM

No IAM on this stateless component.

7.5 Scaling

Kroki is not a heavy consumption app. Our stress tests didn’t reveal the need for extra resource allocation for a production deployment, thus it can safely be deployed with the default sizing.

7.6 Backup / restore

Kroki doesn’t store persistent data, thus no backup required.

7.7 Monitoring

For more on monitoring options for Kroki, please refer to the SCOM guide

7.8 Logging

SWaaP package enforces Kroki to set the loglevel to WARN, as INFO is considered to be too verbose and unsecure for production deployments. For more on how to set and consume logs in Kroki, please reffer to the SCOM guide