From afedc8ba809803e6f6b14a58f37a6813faf134c6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?=
 <signebroedbaek@gmail.com>
Date: Mon, 13 Oct 2025 13:01:35 +0200
Subject: [PATCH 1/3] docs: :memo: update text in c4 models and system context
 sections

---
 docs/design/architecture.qmd | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd
index 1207ff8a..19c43517 100644
--- a/docs/design/architecture.qmd
+++ b/docs/design/architecture.qmd
@@ -34,20 +34,25 @@ This section describes the different users we expect and design for:
 This section contains the [C4 Models](https://c4model.com/) for
 `check-datapackage`. The C4 Model is an established visualisation
 approach to describe the architecture of a software system. It breaks
-the system down into four levels of architectural abstraction: Context,
-Containers, Components, and Code. For our case, the **Context** and
-**Containers** diagrams are the most useful.
+the system down into four levels of architectural abstraction: System
+context, containers, components, and code.
 
-### Context
+### System context
 
-The Context diagram shows the users and any external systems that
-interact with `check-datapackage`. This includes the user types
-described in the [User types](#user-types) section.
+The system context diagram shows the users and any external systems that
+interact with `check-datapackage`. This includes the user types and the
+Data Package standard.
 
-::: callout-caution
-For some reason, these diagrams don't display well on some browsers like
-Firefox. To see them, try using a different browser like Chrome or Edge.
-:::
+`check-datapackage` receives the definitions of the Data Package
+descriptor's structure---including required properties, their formats,
+and recommended fields---from the Data Package standard (version 2). The
+standard provides this information through versioned JSON Schema
+profiles that define required properties and textual descriptions that
+outline recommendations.
+
+The users, described in the [User types](#user-types) section, provide
+`check-datapackage` with their Data Package's descriptor to check its
+compliance with the standard.
 
 ```{mermaid}
 %%| label: fig-c4-context

From 518af9d02f193eb81ce59312654651f020525e10 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?=
 <signebroedbaek@gmail.com>
Date: Mon, 13 Oct 2025 13:01:46 +0200
Subject: [PATCH 2/3] docs: :memo: update mermaid diagram

---
 docs/design/architecture.qmd | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd
index 19c43517..c12e9f89 100644
--- a/docs/design/architecture.qmd
+++ b/docs/design/architecture.qmd
@@ -56,20 +56,32 @@ compliance with the standard.
 
 ```{mermaid}
 %%| label: fig-c4-context
-%%| fig-cap: "C4 Context diagram showing a very basic overview of `check-datapackage` and its anticipated users."
+%%| fig-cap: "C4 system context diagram showing the anticipated users and the external system (the Data Package standard) `check-datapackage` interacts with."
 flowchart LR
-    user_owner(["Owner<br>[person]"])
-    user_manager(["Manager<br>[person]"])
-    user_developer(["Developer<br>[person]"])
-    ext_dp_schema(["Data Package standard<br>[standard]"])
-    check
 
-    ext_dp_schema --> check
-    user_owner --> check
-    user_manager --> check
-    user_developer --> check
+    subgraph "Users"
+        user_owner("Owner<br>[person]")
+        user_manager("Manager<br>[person]")
+        user_developer("Developer<br>[person]")
+    end
+
+    dp_standard("Data Package V2<br>[standard]")
+    check("check-datapackage<br>[Python package]")
+
+
+    dp_standard --"Definition of the standard<br>and its recommendations"--> check
+    Users --"Checks the compliance of<br>their Data Package's<br>descriptor"--> check
+
+    %% Styling
+    style Users fill:#FFFFFF, color:#000000
 ```
 
+::: callout-caution
+For some reason, these diagrams don't display well on some browsers, for
+example Firefox. If you can't see them on this page, try using a
+different browser like Chrome or Edge.
+:::
+
 ### Container
 
 The Container diagram shows the larger parts of the system, what they

From 251114022af152720597feef18e6988d98bca716 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?=
 <signebroedbaek@gmail.com>
Date: Tue, 14 Oct 2025 10:14:44 +0200
Subject: [PATCH 3/3] docs: :fire: remove callout on diagrams not being shown
 in Firefox

They are now displayed in Firefox as well #114

Co-authored-by: Luke W. Johnston <lwjohnst86@users.noreply.github.com>
---
 docs/design/architecture.qmd | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd
index c12e9f89..0f5e4920 100644
--- a/docs/design/architecture.qmd
+++ b/docs/design/architecture.qmd
@@ -76,11 +76,6 @@ flowchart LR
     style Users fill:#FFFFFF, color:#000000
 ```
 
-::: callout-caution
-For some reason, these diagrams don't display well on some browsers, for
-example Firefox. If you can't see them on this page, try using a
-different browser like Chrome or Edge.
-:::
 
 ### Container