docs: model owned home-lab services as Corp v1 containers
Build and publish Corp v1 Board portal / build (push) Successful in 34s

Merge PR #12: keep only Discord and LLM provider external; classify Lego-maintained home-lab services as internal containers.
This commit was merged in pull request #12.
This commit is contained in:
2026-08-26 00:53:50 -07:00
6 changed files with 111 additions and 89 deletions
+22 -18
View File
@@ -1,7 +1,7 @@
---
id: context
title: "Context"
description: "Identify the Corp v1 target system, the people who use or govern it, and the external collaboration, design, source, and delivery systems around it."
description: "See the Corp v1 home-lab system boundary, its human actors, and its only external systems: the LLM provider and Discord."
---
import Drawio from '@theme/Drawio';
@@ -9,32 +9,36 @@ import contextDiagram from '!!raw-loader!./diagrams/context.drawio';
# Context
The target system on this page is the **Corp v1 Hermes delivery system**: one Hermes Agent operating through focused project sessions, specialised skills, tool integrations, and a durable evidence loop. It helps people govern and deliver projects; it does not replace human authority or become the application being built.
The target system is the **Corp v1 managed delivery platform in Lego's home lab**. The boundary follows operational responsibility: services and managed service slices that Lego deploys, configures, versions, upgrades, secures, or restores are inside the Corp v1 system boundary.
<Drawio content={contextDiagram} title="Corp v1 system context with human actors and external systems" toolbar="zoom layers lightbox" responsive maxHeight={760} />
<Drawio content={contextDiagram} title="Corp v1 home-lab system context" toolbar="zoom layers lightbox" responsive maxHeight={760} />
## Human actors
| Actor | Relationship to the target system |
| Actor | Relationship to Corp v1 |
|---|---|
| **Corp v1 Board members** | Govern the portfolio. They approve project kickoff and closure, membership, the global operating model, and central `corp-v1-channel-*` reference changes. |
| **Project leads and contributors** | Use focused project channels to define value, approve solution work and Task admission, review architecture and UI/UX, implement changes, and accept releases. |
| **Prospective project sponsors and contributors** | May request or join a future Corp v1 project after Board approval, identity resolution, and explicit onboarding. They have no authority merely because they are interested. |
| **Solution users and reviewers** | Supply needs, feedback, usability evidence, and acceptance observations for a project solution. Their product input does not automatically grant Board or project decision rights. |
| **Corp v1 Board members** | Govern the portfolio and approve project lifecycle, membership, the global operating model, and central channel-reference changes. |
| **Project leads and contributors** | Define value, approve solution work and Task admission, review architecture and UI/UX, implement changes, and accept releases. |
| **Prospective project sponsors and contributors** | May request or join future Corp v1 projects after explicit Board approval and onboarding. |
| **Solution users and reviewers** | Provide needs, usability feedback, acceptance observations, and evidence about the products delivered through Corp v1. |
Hermes is an executing system participant, not a human approver. An agent message, CI result, silence, or inferred intent never substitutes for an approval reserved to a listed human actor.
Human authority remains outside automation. Hermes, CI, deployments, inferred intent, and silence never substitute for an approval reserved to a listed person.
## External systems around the target
## External systems
| System | How Corp v1 uses it |
Corp v1 currently has only two external software systems:
| External system | Relationship to Corp v1 |
|---|---|
| **Discord** | Carries Board governance and project channel sessions, human decisions, coordination, and handoff messages. |
| **Penpot** | Holds editable UI/UX design sources and review evidence before implementation. |
| **Gitea and Gitea Actions** | Preserve source, documentation, skills, decisions, pull requests, CI, and GitOps desired state. |
| **LEGO Cloud delivery platform** | Provides Pages, Harbor, Argo CD, the three-node Gondor v1 MicroK8s cluster, ingress, authentication, and deployed readback. |
| **LLM Provider** | Supplies model inference to Hermes Agent. The currently used providers are ICA or GPT Codex. Model execution is consumed as an external capability; Corp v1 does not deploy or maintain the provider platform. |
| **Communication Service — Discord** | Carries Board governance and project conversations. Corp v1 configures and maintains its channel structure, permissions, guidance, and pins, while Discord operates the communication platform itself. |
## Target-system boundary
## Inside the system boundary
Inside the target system are Hermes Agent behavior, focused sessions, skill selection, tool execution, and evidence verification. Human decision rights remain outside that boundary. Discord, Penpot, Gitea, and the delivery platform are connected external systems with their own authority and state.
Hermes Agent and the home-lab services it depends on are internal containers in this architecture: Gitea, Actions runners, Penpot, the Board portal, Pages, Harbor, Argo CD, the access and identity stack, MicroK8s, and the hosted workloads. Their Corp v1 configuration is not modeled as an external dependency because Lego is responsible for its lifecycle and operational state.
A project's product or service is also outside this boundary. Corp v1 can govern its lifecycle and operate its delivery path, but each project must maintain its own product context, requirements, architecture, UI/UX, security, data, and release decisions.
The [Container Overview](/architecture-high-level/overview/) shows those internal containers and their delivery relationships. The [Operating Model](/architecture-high-level/operating-model/) separately explains Board authority, channel sessions, skills, approvals, and handoffs.
## Product boundary
A project product delivered through Corp v1 remains its own product boundary. Corp v1 operates the delivery platform and governs the lifecycle, while every project must maintain its own product context, requirements, architecture, data, security, UI/UX, and release decisions.
@@ -1,34 +1,41 @@
<mxfile host="app.diagrams.net" modified="2026-08-25T00:00:00.000Z" agent="Hermes Agent" version="26.0.16" type="device">
<diagram id="corp-v1-service-architecture-v1" name="CORP V1 — SERVICE ARCHITECTURE">
<mxGraphModel dx="2080" dy="920" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="2080" pageHeight="920" math="0" shadow="0" adaptiveColors="auto">
<diagram id="corp-v1-home-lab-containers-v2" name="CORP V1 — HOME-LAB CONTAINERS">
<mxGraphModel dx="2080" dy="1100" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="2080" pageHeight="1100" math="0" shadow="0" adaptiveColors="auto">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="title" value="CORP V1 — SERVICE ARCHITECTURE" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=24;fontStyle=1;fontColor=#102A43;" vertex="1" parent="1"><mxGeometry x="80" y="20" width="1920" height="40" as="geometry"/></mxCell>
<mxCell id="subtitle" value="Decisions → agent execution → source → CI → deployed evidence" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=14;fontColor=#486581;" vertex="1" parent="1"><mxGeometry x="80" y="70" width="1920" height="40" as="geometry"/></mxCell>
<mxCell id="humans" value="HUMAN ACTORS · Board · project contributors · reviewers" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="80" y="180" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="discord" value="DISCORD · Board governance · seven project channel sessions" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="360" y="180" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="hermes" value="HERMES AGENT · sessions · skills · tools · verification" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="640" y="180" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="gitea" value="GITEA · source · docs · skills · PRs · GitOps state" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="920" y="180" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="actions" value="GITEA ACTIONS · exact-head validation · build · publication" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1200" y="180" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="pages" value="LEGO CLOUD PAGES · Board and project documentation" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1480" y="180" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="access" value="ACCESS EDGE · Cloudflare · Keycloak · Nginx · oauth2-proxy" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1760" y="180" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="penpot" value="PENPOT · journeys · prototypes · accessibility · design handoff" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="640" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="harbor" value="HARBOR · immutable application images" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1200" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="argocd" value="ARGO CD · reads GitOps state · reconciles desired state" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1480" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="microk8s" value="GONDOR MICROK8S · 3 nodes · Pages and approved workloads" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1760" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="title" value="CORP V1 — HOME-LAB CONTAINER OVERVIEW" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=24;fontStyle=1;fontColor=#102A43;" vertex="1" parent="1"><mxGeometry x="80" y="20" width="1920" height="40" as="geometry"/></mxCell>
<mxCell id="subtitle" value="Two external services · internally deployed and maintained delivery containers" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=14;fontColor=#486581;" vertex="1" parent="1"><mxGeometry x="80" y="70" width="1920" height="40" as="geometry"/></mxCell>
<mxCell id="humans" value="HUMAN ACTORS · Board · project teams · solution users" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="80" y="140" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="discord" value="EXTERNAL · DISCORD · communication service" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FFF7ED;strokeColor=#C2410C;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="360" y="140" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="hermes" value="INTERNAL · HERMES AGENT · tools · sessions · verification" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=3;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="640" y="140" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="llm" value="EXTERNAL · LLM PROVIDER · ICA OR GPT CODEX" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FFF7ED;strokeColor=#C2410C;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="920" y="140" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="e1" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="humans" target="discord"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e2" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="discord" target="hermes"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e3" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="hermes" target="gitea"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e3" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="hermes" target="llm"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="tools-arrow" value="TOOLS" style="shape=singleArrow;direction=south;whiteSpace=wrap;html=1;fillColor=#2563EB;strokeColor=#2563EB;fontColor=#FFFFFF;fontSize=11;fontStyle=1;" vertex="1" parent="1"><mxGeometry x="720" y="340" width="80" height="80" as="geometry"/></mxCell>
<mxCell id="internal-label" value="INTERNAL CONTAINERS · DEPLOYED AND MAINTAINED BY LEGO" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=16;fontStyle=1;fontColor=#334E68;" vertex="1" parent="1"><mxGeometry x="80" y="420" width="1920" height="40" as="geometry"/></mxCell>
<mxCell id="penpot" value="PENPOT · UI/UX service · sources · reviews · handoff" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="80" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="skills" value="SKILLS &amp; SESSIONS · governed runtime configuration" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="360" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="gitea" value="GITEA · source · docs · skills · PRs · GitOps state" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="640" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="actions" value="GITEA ACTIONS RUNNERS · exact-head build and publication" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="920" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="portal" value="BOARD PORTAL · Docusaurus application · registries · architecture" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1200" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="pages" value="LEGO CLOUD PAGES · protected documentation publication" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1480" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="access" value="ACCESS EDGE · Cloudflare config · Keycloak · OAuth · Nginx" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1760" y="500" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="e4" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="gitea" target="actions"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e5" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="actions" target="pages"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e6" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="pages" target="access"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="penpot-arrow" value="DESIGN" style="shape=singleArrow;direction=north;whiteSpace=wrap;html=1;fillColor=#0F766E;strokeColor=#0F766E;fontColor=#FFFFFF;fontSize=11;fontStyle=1;" vertex="1" parent="1"><mxGeometry x="720" y="380" width="80" height="80" as="geometry"/></mxCell>
<mxCell id="actions-arrow" value="IMAGE" style="shape=singleArrow;direction=south;whiteSpace=wrap;html=1;fillColor=#7E22CE;strokeColor=#7E22CE;fontColor=#FFFFFF;fontSize=11;fontStyle=1;" vertex="1" parent="1"><mxGeometry x="1280" y="380" width="80" height="80" as="geometry"/></mxCell>
<mxCell id="e9" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#7E22CE;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="harbor" target="argocd"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#7E22CE;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="argocd" target="microk8s"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="runtime-arrow" value="RUNTIME" style="shape=singleArrow;direction=north;whiteSpace=wrap;html=1;fillColor=#7E22CE;strokeColor=#7E22CE;fontColor=#FFFFFF;fontSize=10;fontStyle=1;" vertex="1" parent="1"><mxGeometry x="1840" y="380" width="80" height="80" as="geometry"/></mxCell>
<mxCell id="evidence" value="DELIVERY CLAIM = EXACT-COMMIT CI + DEPLOYED PAGE OR RUNTIME READBACK" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#F8FAFC;strokeColor=#64748B;strokeWidth=2;fontColor=#102A43;fontSize=16;fontStyle=1;align=center;" vertex="1" parent="1"><mxGeometry x="360" y="780" width="1360" height="80" as="geometry"/></mxCell>
<mxCell id="e5" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="actions" target="portal"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e6" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="portal" target="pages"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e7" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="pages" target="access"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="image-arrow" value="IMAGE" style="shape=singleArrow;direction=south;whiteSpace=wrap;html=1;fillColor=#2563EB;strokeColor=#2563EB;fontColor=#FFFFFF;fontSize=11;fontStyle=1;" vertex="1" parent="1"><mxGeometry x="1000" y="700" width="80" height="80" as="geometry"/></mxCell>
<mxCell id="runtime-arrow" value="ROUTE" style="shape=singleArrow;direction=north;whiteSpace=wrap;html=1;fillColor=#2563EB;strokeColor=#2563EB;fontColor=#FFFFFF;fontSize=11;fontStyle=1;" vertex="1" parent="1"><mxGeometry x="1840" y="700" width="80" height="80" as="geometry"/></mxCell>
<mxCell id="harbor" value="HARBOR · registry · immutable images · retention" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="920" y="820" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="argocd" value="ARGO CD · GitOps desired state · sync · health" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1200" y="820" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="microk8s" value="GONDOR MICROK8S · 3-node runtime · namespaces · workloads" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1480" y="820" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="workloads" value="PROJECT WORKLOADS · Services · routes · releases · readback" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1760" y="820" width="240" height="160" as="geometry"/></mxCell>
<mxCell id="e8" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="harbor" target="argocd"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e9" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="argocd" target="microk8s"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;strokeColor=#475569;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="microk8s" target="workloads"><mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="evidence" value="OWNERSHIP = CONFIGURE · VERSION · DEPLOY · UPGRADE · SECURE · RESTORE · VERIFY" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=16;fontStyle=1;align=center;" vertex="1" parent="1"><mxGeometry x="80" y="1020" width="1920" height="40" as="geometry"/></mxCell>
</root>
</mxGraphModel>
</diagram>
@@ -1,23 +1,21 @@
<mxfile host="app.diagrams.net" modified="2026-08-25T00:00:00.000Z" agent="Hermes Agent" version="26.0.16" type="device">
<diagram id="corp-v1-system-context-v2" name="CORP V1 — SYSTEM CONTEXT">
<diagram id="corp-v1-home-lab-context-v3" name="CORP V1 — HOME-LAB SYSTEM CONTEXT">
<mxGraphModel dx="1440" dy="960" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1440" pageHeight="960" math="0" shadow="0" adaptiveColors="auto">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="title" value="CORP V1 — SYSTEM CONTEXT" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=24;fontStyle=1;fontColor=#102A43;" vertex="1" parent="1"><mxGeometry x="80" y="20" width="1280" height="40" as="geometry"/></mxCell>
<mxCell id="subtitle" value="Target system, human authority, current integrations, and future participants" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=14;fontColor=#486581;" vertex="1" parent="1"><mxGeometry x="80" y="70" width="1280" height="40" as="geometry"/></mxCell>
<mxCell id="title" value="CORP V1 — HOME-LAB SYSTEM CONTEXT" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=24;fontStyle=1;fontColor=#102A43;" vertex="1" parent="1"><mxGeometry x="80" y="20" width="1280" height="40" as="geometry"/></mxCell>
<mxCell id="subtitle" value="Owned home-lab platform · human authority · only two external systems" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=14;fontColor=#486581;" vertex="1" parent="1"><mxGeometry x="80" y="70" width="1280" height="40" as="geometry"/></mxCell>
<mxCell id="actors-label" value="HUMAN ACTORS" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=16;fontStyle=1;fontColor=#334E68;" vertex="1" parent="1"><mxGeometry x="80" y="120" width="1280" height="40" as="geometry"/></mxCell>
<mxCell id="board" value="BOARD MEMBERS · portfolio authority · lifecycle · global policy" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="80" y="180" width="400" height="120" as="geometry"/></mxCell>
<mxCell id="teams" value="PROJECT LEADS &amp; CONTRIBUTORS · decisions · design · delivery" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="520" y="180" width="400" height="120" as="geometry"/></mxCell>
<mxCell id="future" value="FUTURE SPONSORS &amp; USERS · requests · feedback · acceptance" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="960" y="180" width="400" height="120" as="geometry"/></mxCell>
<mxCell id="future" value="SPONSORS &amp; SOLUTION USERS · requests · feedback · acceptance" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E6FFFA;strokeColor=#0F766E;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="960" y="180" width="400" height="120" as="geometry"/></mxCell>
<mxCell id="actor-relation" value="GOVERN · DIRECT · COLLABORATE · REVIEW" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#0F766E;strokeColor=#0F766E;fontColor=#FFFFFF;fontSize=14;fontStyle=1;align=center;" vertex="1" parent="1"><mxGeometry x="480" y="340" width="480" height="40" as="geometry"/></mxCell>
<mxCell id="target" value="TARGET SYSTEM · CORP V1 HERMES · agent · sessions · skills · evidence" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=3;fontColor=#102A43;fontSize=18;fontStyle=1;spacing=20;align=center;" vertex="1" parent="1"><mxGeometry x="320" y="420" width="800" height="160" as="geometry"/></mxCell>
<mxCell id="system-relation" value="COMMUNICATE · DESIGN · PERSIST · BUILD · DEPLOY · VERIFY" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#2563EB;strokeColor=#2563EB;fontColor=#FFFFFF;fontSize=14;fontStyle=1;align=center;" vertex="1" parent="1"><mxGeometry x="440" y="620" width="560" height="40" as="geometry"/></mxCell>
<mxCell id="systems-label" value="CONNECTED EXTERNAL SYSTEMS" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=16;fontStyle=1;fontColor=#334E68;" vertex="1" parent="1"><mxGeometry x="80" y="700" width="1280" height="40" as="geometry"/></mxCell>
<mxCell id="discord" value="DISCORD · governance and project sessions" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="80" y="780" width="280" height="120" as="geometry"/></mxCell>
<mxCell id="penpot" value="PENPOT · UI/UX sources and review" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="400" y="780" width="280" height="120" as="geometry"/></mxCell>
<mxCell id="gitea" value="GITEA · source · skills · PRs · Actions · GitOps" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="720" y="780" width="280" height="120" as="geometry"/></mxCell>
<mxCell id="platform" value="LEGO CLOUD · Pages · Harbor · Argo CD · MicroK8s · access" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FAF5FF;strokeColor=#7E22CE;strokeWidth=2;fontColor=#102A43;fontSize=14;fontStyle=1;spacing=12;" vertex="1" parent="1"><mxGeometry x="1040" y="780" width="280" height="120" as="geometry"/></mxCell>
<mxCell id="target" value="TARGET SYSTEM · CORP V1 MANAGED HOME-LAB DELIVERY PLATFORM" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#EFF6FF;strokeColor=#2563EB;strokeWidth=3;fontColor=#102A43;fontSize=18;fontStyle=1;spacing=20;align=center;" vertex="1" parent="1"><mxGeometry x="320" y="420" width="800" height="160" as="geometry"/></mxCell>
<mxCell id="system-relation" value="MODEL INFERENCE · HUMAN COMMUNICATION" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#C2410C;strokeColor=#C2410C;fontColor=#FFFFFF;fontSize=14;fontStyle=1;align=center;" vertex="1" parent="1"><mxGeometry x="480" y="620" width="480" height="40" as="geometry"/></mxCell>
<mxCell id="systems-label" value="EXTERNAL SYSTEMS · ONLY TWO" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=16;fontStyle=1;fontColor=#334E68;" vertex="1" parent="1"><mxGeometry x="80" y="700" width="1280" height="40" as="geometry"/></mxCell>
<mxCell id="discord" value="COMMUNICATION SERVICE · DISCORD" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FFF7ED;strokeColor=#C2410C;strokeWidth=2;fontColor=#102A43;fontSize=16;fontStyle=1;spacing=16;" vertex="1" parent="1"><mxGeometry x="280" y="780" width="400" height="120" as="geometry"/></mxCell>
<mxCell id="llm" value="LLM PROVIDER · ICA OR GPT CODEX" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FFF7ED;strokeColor=#C2410C;strokeWidth=2;fontColor=#102A43;fontSize=16;fontStyle=1;spacing=16;" vertex="1" parent="1"><mxGeometry x="760" y="780" width="400" height="120" as="geometry"/></mxCell>
</root>
</mxGraphModel>
</diagram>
+38 -31
View File
@@ -1,50 +1,57 @@
---
id: overview
title: "Overview"
description: "See the real Corp v1 service architecture: people and Discord, Hermes Agent, Gitea, CI, Pages, Harbor, Argo CD, and Gondor MicroK8s."
title: "Container Overview"
description: "See the internal containers Lego deploys and maintains for Corp v1, from Hermes and Gitea through Pages, Harbor, Argo CD, identity, ingress, and MicroK8s."
---
import Drawio from '@theme/Drawio';
import architectureDiagram from '!!raw-loader!./diagrams/architecture-overview.drawio';
# Overview
# Container Overview
This is the **deployed service architecture around Corp v1 today**. It is different from the [Operating Model](/architecture-high-level/operating-model/): the operating model explains how work moves; this page shows which services perform and preserve that work.
This view treats the **Corp v1 managed home-lab platform** as the software system. A container here is an independently operated service or managed service slice for which Lego owns configuration, versioning, deployment, upgrades, access, backup or recovery, and operational verification.
<Drawio content={architectureDiagram} title="Corp v1 deployed service architecture" toolbar="zoom layers lightbox" responsive maxHeight={820} />
<Drawio content={architectureDiagram} title="Corp v1 internal container architecture" toolbar="zoom layers lightbox" responsive maxHeight={860} />
## Services in the current setup
## Internal containers
| Service | Current role in Corp v1 |
| Container | Corp v1 responsibility |
|---|---|
| **Discord** | Human interaction surface: one `corp-v1-board` governance channel and seven focused sessions per project. |
| **Hermes Agent** | The executing AI agent. It loads channel and engineering skills, uses connected tools, changes repositories, observes CI and runtime state, and reports evidence. It is not placed inside the Kubernetes cluster in this model. |
| **Penpot** | Current UI/UX design workspace for journeys, information architecture, prototypes, accessibility review, and implementation handoff. |
| **Gitea** | Durable source and collaboration system for the Board portal, project documentation, application source, adopted skills, branches, pull requests, decisions, and GitOps repositories. |
| **Gitea Actions** | Self-hosted validation and publication. Exact-head runs are part of delivery evidence. |
| **LEGO Cloud Pages** | Publishes the Board and project Docusaurus portals through the `pages` workload. The current `0500-pages` Argo CD application is `Synced / Healthy`. |
| **Harbor** | Stores immutable application images. The current `0200-harbor` Argo CD application is `Synced / Healthy`. |
| **Argo CD** | Reconciles GitOps desired state into Gondor v1. The current AeroSim application is `Synced / Healthy`; a project is not shown as deployed merely because a repository exists. |
| **Gondor v1 MicroK8s** | Three-node Kubernetes runtime: Osgiliath plus two Minas Tirith workers. It currently hosts Pages and approved application workloads. |
| **Access edge** | Cloudflare and Osgiliath Nginx route public traffic. Pages uses `pages-oauth2-proxy`, with Keycloak providing the observed sign-in boundary. |
| **Hermes Agent** | Agent runtime, connected tools, model-provider integration, focused sessions, skill loading, execution, and evidence verification. |
| **Corp v1 Board portal** | Docusaurus source, registries, architecture, decisions, build, publication, navigation, and deployed-content readback. |
| **Gitea** | Service operation plus Corp organizations, teams, repositories, branches, pull requests, variables, permissions, skills, documentation, application source, and GitOps state. |
| **Gitea Actions runners** | Runner operation, workflow versions, exact-head validation, documentation builds, image publication, and delivery evidence. |
| **Penpot** | Service deployment and the project design workspaces, editable design sources, review state, accessibility evidence, and handoff. |
| **LEGO Cloud Pages** | Pages workload, route structure, publication behavior, OAuth-protected access, and content readback. |
| **Harbor** | Registry service, projects, repositories, robot integration, immutable application images, retention, and availability. |
| **Argo CD** | Service lifecycle, AppProjects, Applications, repository access, desired-state reconciliation, health, and sync evidence. |
| **Identity and access** | Keycloak, OAuth proxy configuration, protected routes, clients, policies, and sign-in behavior. |
| **Ingress edge** | Cloudflare configuration, Osgiliath Nginx, ACME, Kubernetes ingress, routing, certificates, and public endpoints. |
| **Gondor v1 MicroK8s** | Three-node runtime, namespaces, workloads, Services, Ingress, storage integration, readiness, image identity, and runtime readback. |
| **Project workloads** | Approved application Deployments, Services, routes, configuration, release candidates, rollback state, and observable behavior. |
## Documentation delivery path
## External connections
1. Hermes or a human contributor changes an editable source in Gitea.
2. Gitea Actions validates the exact commit and builds Docusaurus.
3. The Pages publication workload serves the built route.
4. Protected readers pass through the access boundary.
5. Hermes verifies distinctive content through the authorized Pages service path before claiming completion.
Only two software systems cross the Corp v1 boundary:
## Application delivery path
- **Discord** supplies the communication service. Corp v1 owns the managed channel configuration represented in its operating model.
- **ICA or GPT Codex** supplies LLM inference to Hermes Agent.
1. Project source and GitOps desired state are reviewed in Gitea.
2. Gitea Actions validates the exact commit and publishes an immutable image to Harbor when credentials and policy gates are satisfied.
3. Argo CD reconciles approved desired state into the target MicroK8s namespace.
4. Runtime pod readiness, image identity, service route, and user-visible behavior are read back.
## Documentation path
Penpot evidence enters this flow through reviewed links and project documentation; it does not replace versioned requirements, ADRs, code, or release evidence.
`Hermes → Gitea → Gitea Actions → Board portal build → LEGO Cloud Pages → identity/ingress → deployed readback`
## Boundaries of truth
A documentation delivery claim requires successful exact-commit CI and distinctive content from the deployed Pages service path.
Discord and agent sessions coordinate work, but they are not the only durable record. Approved decisions, current architecture, source, adopted skills, and delivery evidence are persisted in Gitea-backed documentation. CI success proves validation; deployed readback proves publication or runtime behavior. The two are required together when delivery is claimed.
## Application path
`Hermes → Gitea → Gitea Actions → Harbor → GitOps state → Argo CD → MicroK8s workload → ingress → runtime readback`
Argo CD also reads desired state from Gitea. A repository or image alone is not a deployed product; the runtime image identity, readiness, route, and user-visible behavior must be verified.
## Related views
- [Context](/architecture-high-level/context/) defines the home-lab boundary, human actors, and two external systems.
- [Operating Model](/architecture-high-level/operating-model/) explains governance and the delivery lifecycle.
- [Overview Skills](/architecture-high-level/overview-skills/) explains the instructions Hermes loads to operate these containers safely.
- [Overview Repositories](/architecture-high-level/overview-repositories/) explains the versioned project and skill sources.
+10 -4
View File
@@ -78,7 +78,7 @@ const expectedArchitectureSidebar = `import type {SidebarsConfig} from '@docusau
const sidebars: SidebarsConfig = {
architectureHighLevelSidebar: [
{type: 'doc', id: 'context', label: 'Context'},
{type: 'doc', id: 'overview', label: 'Overview'},
{type: 'doc', id: 'overview', label: 'Container Overview'},
{type: 'doc', id: 'operating-model', label: 'Operating Model'},
{type: 'doc', id: 'overview-channels', label: 'Overview Channels'},
{type: 'doc', id: 'overview-skills', label: 'Overview Skills'},
@@ -109,6 +109,12 @@ for (const term of ['seven channel skills', 'seven engineering skills', 'Gitea A
for (const term of ['Corp v1 Board members', 'Project leads and contributors', 'Prospective project sponsors and contributors', 'Solution users and reviewers']) {
assert.ok(architecturePages.context.includes(term), `system context is missing actor: ${term}`);
}
for (const term of ['only two external software systems', 'LLM Provider', 'ICA or GPT Codex', 'Communication Service — Discord']) {
assert.ok(architecturePages.context.includes(term), `system context is missing boundary rule: ${term}`);
}
for (const term of ['Gitea Actions runners', 'Penpot', 'LEGO Cloud Pages', 'Harbor', 'Argo CD', 'Identity and access', 'Ingress edge', 'Gondor v1 MicroK8s']) {
assert.ok(architecturePages.overview.includes(term), `container overview is missing internal container: ${term}`);
}
for (const term of ['corp-v1--main', 'corp-v1-channel-ui-ux', 'development-gitops-argo-cd', 'drawio-main', 'systematic-debugging', 'gondor-v1-nodes']) {
assert.ok(architecturePages.skills.includes(term), `skills overview is missing: ${term}`);
}
@@ -116,8 +122,8 @@ for (const [name, page] of Object.entries(architecturePages)) {
assert.doesNotMatch(page, /exactly six|six project channels|six channel skills|thirteen adopted skill/i, `${name} retains the superseded six-channel model`);
}
for (const [name, markers] of Object.entries({
'context.drawio': ['CORP V1 — SYSTEM CONTEXT', 'HUMAN ACTORS', 'TARGET SYSTEM', 'CONNECTED EXTERNAL SYSTEMS'],
'architecture-overview.drawio': ['CORP V1 — SERVICE ARCHITECTURE', 'HERMES AGENT', 'GITEA ACTIONS', 'HARBOR', 'ARGO CD', 'GONDOR MICROK8S'],
'context.drawio': ['CORP V1 — HOME-LAB SYSTEM CONTEXT', 'HUMAN ACTORS', 'TARGET SYSTEM', 'EXTERNAL SYSTEMS · ONLY TWO', 'DISCORD', 'ICA OR GPT CODEX'],
'architecture-overview.drawio': ['CORP V1 — HOME-LAB CONTAINER OVERVIEW', 'EXTERNAL · DISCORD', 'EXTERNAL · LLM PROVIDER', 'INTERNAL CONTAINERS', 'GITEA ACTIONS RUNNERS', 'HARBOR', 'ARGO CD', 'GONDOR MICROK8S'],
'operating-model.drawio': ['CORP V1 — OPERATING MODEL FLOW', 'CORP-V1-BOARD', 'BOARD APPROVAL', 'UI/UX', 'KANBAN / FOCUS', 'VERIFY &amp; RECORD'],
'channels.drawio': ['CORP V1 — BOARD &amp; PROJECT CHANNELS', 'CORP-V1-BOARD', 'GENERAL', 'ARCHITECTURE', 'UI/UX', 'RELEASES', 'MULTIPLE FOCUSED SESSIONS'],
'skills.drawio': ['CORP V1 — SKILLS MODEL', 'CENTRAL SOURCES', 'DELIBERATE ADOPTION', 'PROJECT COPIES', 'FOCUSED SESSION'],
@@ -135,7 +141,7 @@ if (existsSync(join(root, 'build'))) {
const filename = readdirSync(join(root, 'build')).find((name) => /^search-index(?:-[a-f0-9]+)?\.json$/.test(name));
assert.ok(filename, 'production search index is missing');
const search = readFileSync(join(root, 'build', filename), 'utf8').toLowerCase();
for (const term of ['projects registry', 'teams registry', 'members registry', 'board members', 'project lifecycle', 'corp v1 board', 'operating model', 'overview channels', 'overview skills', 'overview repositories']) {
for (const term of ['projects registry', 'teams registry', 'members registry', 'board members', 'project lifecycle', 'corp v1 board', 'container overview', 'operating model', 'overview channels', 'overview skills', 'overview repositories']) {
assert.ok(search.includes(term), `search index is missing: ${term}`);
}
}
+1 -1
View File
@@ -3,7 +3,7 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
architectureHighLevelSidebar: [
{type: 'doc', id: 'context', label: 'Context'},
{type: 'doc', id: 'overview', label: 'Overview'},
{type: 'doc', id: 'overview', label: 'Container Overview'},
{type: 'doc', id: 'operating-model', label: 'Operating Model'},
{type: 'doc', id: 'overview-channels', label: 'Overview Channels'},
{type: 'doc', id: 'overview-skills', label: 'Overview Skills'},