corp-v1/portal
2
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: add real Corp v1 architecture and skill context
Build and publish Corp v1 Board portal / build (pull_request) Successful in 36s
Details

Browse Source
This commit is contained in:
jarvis-at-skic
2026-08-25 20:11:54 +00:00
parent 661bcde0f2
commit 382a9cc670
10 changed files with 265 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture-high-level/overview.mdx
+33 -19
View File
@@ -1,36 +1,50 @@
---
id: overview
title: "Overview"
description: "Follow the single-agent, multi-session Corp v1 pilot from Board governance through design, delivery, release, and verified evidence."
description: "See the real Corp v1 service architecture: people and Discord, Hermes Agent, Gitea, CI, Pages, Harbor, Argo CD, and Gondor MicroK8s."
---
import Drawio from '@theme/Drawio';
import overviewDiagram from '!!raw-loader!./diagrams/overview.drawio';
import architectureDiagram from '!!raw-loader!./diagrams/architecture-overview.drawio';
# Overview
Corp v1 is an SDLC operating-model pilot: **one AI agent works across multiple focused Discord sessions, each governed by specialised project skills and explicit human decision rights**. Every approved project repeats the same flow while keeping its decisions, repositories, and delivery evidence isolated.
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.
<Drawio content={overviewDiagram} title="Corp v1 governed project operating flow" toolbar="zoom layers lightbox" responsive maxHeight={820} />
<Drawio content={architectureDiagram} title="Corp v1 deployed service architecture" toolbar="zoom layers lightbox" responsive maxHeight={820} />
## How the setup fits together
## Services in the current setup
1. **`corp-v1-board` governs the portfolio.** Listed Board members approve project kickoffs, closures, membership changes, and changes to the global operating model.
2. **General establishes the project workspace.** It handles onboarding, shared coordination, questions, and broadcasts verified outcomes.
3. **Scope decides what creates value.** Ideas become Epics and Features; a human project member approves an exact Feature for solution work.
4. **Architecture decides how the system should work.** Requirements, ADRs, interfaces, constraints, and implementation Tasks become durable project evidence.
5. **UI/UX makes the frontend experience implementable.** User journeys, information architecture, accessibility, Penpot designs, prototypes, and handoff evidence bridge Architecture and execution.
6. **Kanban controls admission and flow.** A human project member admits an exact Task to Focus before Delivery may execute it.
7. **Delivery produces a reviewed candidate.** Work proceeds through branches, pull requests, exact-head validation, and reviewable implementation evidence.
8. **Releases control deployment and outcomes.** Immutable artifacts, risk, rollback, deployment, acceptance, and post-release evidence are assessed explicitly.
9. **Verification closes the evidence loop.** Hermes reads the deployed page or runtime back, updates project documentation and the Board portal, and reports remaining gates honestly.
| Service | Current role in Corp v1 |
|---|---|
| **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. |
## Why sessions and skills are separated
## Documentation delivery path
Each channel is a concern boundary with its own session. The same agent can coordinate the whole project, while the loaded project-adopted channel skill prevents responsibilities and approval rules from blurring together. The project uses seven channel skills to define the workspaces and seven engineering skills to provide reusable execution practices.
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.
Project copies preserve project-specific authority, terminology, repository links, environment namespaces, and operating lessons. Central skill changes are compared and deliberately adopted; they never silently overwrite project decisions.
## Application delivery path
## Automation boundary
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.
Corp v1 projects and channels do **not** use cronjobs or scheduler jobs under the current approved model. Work advances through explicit human decisions, Discord events, reviewed repository changes, exact-commit CI, and deployed readback.
Penpot evidence enters this flow through reviewed links and project documentation; it does not replace versioned requirements, ADRs, code, or release evidence.
## Boundaries of truth
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.