Skip to content

📊 Architecture Diagramming

At Apollyon, we adhere to a strict Docs-as-Code philosophy. We do not use external visual diagramming tools with proprietary save formats. All system architectures, flowcharts, and state diagrams are written using Mermaid JS syntax.

This ensures that our diagrams are version-controlled, easily reviewable in GitLab Merge Requests, and natively rendered in this handbook.

1. The Mermaid Live Editor

To make drafting complex diagrams easier, we self-host an isolated instance of the Mermaid Live Editor. This provides a side-by-side visual preview as you write your syntax.

  • URL: https://mermaid.apollyon.lat
  • Access Control: This tool is secured via HTTP Basic Authentication to prevent public exposure.
    • Username: admin
    • Password: Request the current shared password via the Mattermost #engineering channel.

Stateless Application

Our Mermaid Live Editor is stateless. It does not save your work to a database. If you clear your browser cache or close the tab without copying your code, your diagram will be lost.

2. The Diagramming Workflow

When designing a new Korvy backend service or mapping an ESP32 hardware flow, follow this sequence:

  1. Draft: Log into the Mermaid Live Editor and write your diagram syntax.
  2. Copy: Once the visual preview looks correct, copy the raw markdown text from the "Code" panel.
  3. Commit: Paste the text directly into your target Markdown file within the GitLab repository (e.g., inside an Architecture Decision Record or a feature README).

3. Rendering in the Wiki

To render your diagram within the Apollyon GitLab repository or this MkDocs handbook, you must wrap the raw syntax in a standard markdown code block and tag it with mermaid.

Example Markdown Input: 

```mermaid
graph TD;
    A[ESP32 Node] -->|Telemetry| B(Korvy API);
    B --> C{Database};
    C -->|Store| D[PostgreSQL];

```

Resulting Output: (When pushed to GitLab or viewed in this wiki, the block above will automatically render as a visual flowchart).

4. Common Diagram Types

Mermaid supports various syntaxes tailored for different engineering needs. Reference the official documentation for advanced use cases.

  • Flowcharts: For logic paths and decision trees.
  • Sequence Diagrams: For mapping API interactions (e.g., WhatsApp Webhook -> FastAPI -> PostgreSQL).
  • State Diagrams: For hardware status flows on our physical nodes.