Skip to content

docs: update architecture to c4#174

Open
GroenteLepel wants to merge 17 commits intomainfrom
docs/update-architecture-to-c4
Open

docs: update architecture to c4#174
GroenteLepel wants to merge 17 commits intomainfrom
docs/update-architecture-to-c4

Conversation

@GroenteLepel
Copy link
Contributor

@GroenteLepel GroenteLepel commented Jan 30, 2026

Description

The goal was to update the architecture to reflect the new features added in the past. Also, since we want to use the C4 method now, it was the right time to rewrite this page.

Generated example

When I run poetry run mkdocs serve, I get the following now:

image image image image

What I ran into

  • The diagram that we sketched beforehand was too big to use with Mermaid, so I decided to split them up. This means that the intended Transformer Componentdiagram is not added, because that is a level to deep.
  • I also opted to include a "generic" cyclic optimiser, to also show another possible implementation and further differentiate between the use of a person and another program. This can be removed if deemed necessary.
  • That would mean it would be a "C4: Code" level now, and we need to look into generating that diagram automatically. I think that is a good decision, since that level does seem quite easily mutated and changed, and we do not want to struggle with Mermaid of keeping up with that level of code.
  • Mermaid is quite in its infancy with C4 diagrams, resulting in some unreadable and strangely formatted text. I would argue that this is not really that big of a deal for now, but should this not change in the next couple of months I would suggesting moving to a different method. The reason I'd still want to use Mermaid is 1) we have a system in place now, and 2) you can still read it from code, which is my most important reason.
  • I do not have time to perfect this in the coming week. So if this is "good enough", I'd argue let's ship it, or we'd have to wait for a bit until I return from holidays.
  • I added an ignore for line length, because I could not find a method to break the lines in the editor.

Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Mermaid does not offer any way to break up long lines, so I need to work with lines longer that 120 characters for now. The C4 functionality is in active development, so I hope to see some changes for this in the future.

Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
The System() seems to be broken with formatting. Since we need a simple diagram for now I will swap to System() instead.

Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Signed-off-by: Daniël Kok <daniel.kok@alliander.com>
Copilot AI review requested due to automatic review settings January 30, 2026 13:21
@GroenteLepel GroenteLepel requested a review from a team as a code owner January 30, 2026 13:21
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the architecture documentation to use the C4 model methodology, replacing the outdated state diagram with comprehensive Container and Component diagrams that better represent the current system structure.

Changes:

  • Replaced state diagram with C4 Container diagram showing system boundaries and relationships
  • Added three Component diagrams (Thermal Modeling, Toolbox, Docs) detailing internal structures
  • Removed outdated warning message about documentation status

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

title C2: Containers of the Transformer Thermal Model

Person_Ext(scientist, "Scientist", "Someone that reports on or analyses thermals of transformers.")
System_Ext(cyclops, "Cyclic Optimiser", "Finds a thermal limit of a transformer by repeatedly calculating<br/> the thermals and scaling a load profile.")
Copy link

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected spelling of 'Optimiser' to 'Optimizer'.

Suggested change
System_Ext(cyclops, "Cyclic Optimiser", "Finds a thermal limit of a transformer by repeatedly calculating<br/> the thermals and scaling a load profile.")
System_Ext(cyclops, "Cyclic Optimizer", "Finds a thermal limit of a transformer by repeatedly calculating<br/> the thermals and scaling a load profile.")

Copilot uses AI. Check for mistakes.
title C3: Thermal Modeling

Person_Ext(scientist, "Scientist", "Someone that reports on or analyses thermals of transformers.")
System_Ext(cyclops, "Cyclic Optimiser", "Finds a thermal limit of a transformer by repeatedly calculating<br/> the thermals and scaling a load profile.")
Copy link

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected spelling of 'Optimiser' to 'Optimizer'.

Copilot uses AI. Check for mistakes.
Copy link
Contributor

@LunaJansma LunaJansma left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

De branch moet nog bijgewerkt worden. Verder goedgekeurd, ziet er duidelijk uit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants