docs(architecture): manifesto Layer 4 — C4 Context (draft)#155
Open
Yambr wants to merge 3 commits into
Open
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (2)
WalkthroughThis PR adds a C4 Context architecture page and a companion Mermaid flowchart describing OCU’s inside-the-box boundary, external actors (required vs optional), integration edges, scope exclusions, and a packaging question for next/v1. ChangesC4 Context Architecture Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture/03-c4-context.md`:
- Line 6: Replace the future date in the frontmatter key "last-reviewed" in
docs/architecture/03-c4-context.md with a non-future date (e.g., the PR creation
date or today's date); locate the "last-reviewed: 2026-05-25" entry and update
it to a valid date like "last-reviewed: 2026-05-24" so audit/review tracking
isn't confused.
- Around line 1-2: Replace the existing SPDX header lines ("<!--
SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->" and the following copyright
comment) with the required BUSL header: add a top-of-file comment containing "#
SPDX-License-Identifier: BUSL-1.1" and "# Copyright (c) 2025 Open Computer Use
Contributors" (use the same comment style as other docs in the repo), ensuring
the new header exactly matches the mandated strings.
In `@docs/architecture/diagrams/c4-context.mmd`:
- Around line 1-2: Replace the current SPDX and copyright header in
docs/architecture/diagrams/c4-context.mmd: change the SPDX identifier from
"FSL-1.1-Apache-2.0" to "BUSL-1.1" and ensure the copyright line reads "#
Copyright (c) 2025 Open Computer Use Contributors" so the file header matches
the repo policy for new source files.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 151e614b-0e20-4f1c-ac26-591caa125300
📒 Files selected for processing (2)
docs/architecture/03-c4-context.mddocs/architecture/diagrams/c4-context.mmd
Comment on lines
+1
to
+2
| <!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 --> | ||
| <!-- Copyright (c) 2025 Open Computer Use Contributors --> |
There was a problem hiding this comment.
Replace the license header with the required BUSL header.
This file’s SPDX header is not the required one for new files in this repo.
Proposed fix
-<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
-<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+# SPDX-License-Identifier: BUSL-1.1
+# Copyright (c) 2025 Open Computer Use ContributorsAs per coding guidelines, All other new source files MUST include SPDX license header: # SPDX-License-Identifier: BUSL-1.1 with # Copyright (c) 2025 Open Computer Use Contributors.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture/03-c4-context.md` around lines 1 - 2, Replace the existing
SPDX header lines ("<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->" and
the following copyright comment) with the required BUSL header: add a
top-of-file comment containing "# SPDX-License-Identifier: BUSL-1.1" and "#
Copyright (c) 2025 Open Computer Use Contributors" (use the same comment style
as other docs in the repo), ensuring the new header exactly matches the mandated
strings.
|
|
||
| --- | ||
| status: draft | ||
| last-reviewed: 2026-05-25 |
There was a problem hiding this comment.
Use a non-future last-reviewed date.
last-reviewed: 2026-05-25 is ahead of this PR’s creation date (2026-05-24), which can confuse audit/review tracking.
Proposed fix
-last-reviewed: 2026-05-25
+last-reviewed: 2026-05-24📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| last-reviewed: 2026-05-25 | |
| last-reviewed: 2026-05-24 |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture/03-c4-context.md` at line 6, Replace the future date in the
frontmatter key "last-reviewed" in docs/architecture/03-c4-context.md with a
non-future date (e.g., the PR creation date or today's date); locate the
"last-reviewed: 2026-05-25" entry and update it to a valid date like
"last-reviewed: 2026-05-24" so audit/review tracking isn't confused.
Comment on lines
+1
to
+2
| %% SPDX-License-Identifier: FSL-1.1-Apache-2.0 | ||
| %% Copyright (c) 2025 Open Computer Use Contributors |
There was a problem hiding this comment.
Align diagram file license header with repo policy.
The SPDX/copyright header does not match the required BUSL header for new files.
Proposed fix
-%% SPDX-License-Identifier: FSL-1.1-Apache-2.0
-%% Copyright (c) 2025 Open Computer Use Contributors
+# SPDX-License-Identifier: BUSL-1.1
+# Copyright (c) 2025 Open Computer Use ContributorsAs per coding guidelines, All other new source files MUST include SPDX license header: # SPDX-License-Identifier: BUSL-1.1 with # Copyright (c) 2025 Open Computer Use Contributors.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| %% SPDX-License-Identifier: FSL-1.1-Apache-2.0 | |
| %% Copyright (c) 2025 Open Computer Use Contributors | |
| # SPDX-License-Identifier: BUSL-1.1 | |
| # Copyright (c) 2025 Open Computer Use Contributors |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture/diagrams/c4-context.mmd` around lines 1 - 2, Replace the
current SPDX and copyright header in docs/architecture/diagrams/c4-context.mmd:
change the SPDX identifier from "FSL-1.1-Apache-2.0" to "BUSL-1.1" and ensure
the copyright line reads "# Copyright (c) 2025 Open Computer Use Contributors"
so the file header matches the repo policy for new source files.
Yambr
force-pushed
the
feat/manifesto-04-c4-context-draft
branch
from
0ccbaf0 to
2a78b1b
Compare
Layer 4 of the next/v1 manifesto stack, following §01 audience-and-buyer (PR #143), §02 NFRs (PR #146), and §02 trust-boundaries (PR #147). One canonical Mermaid + one ≤80-line doc, per the plan's "intentionally minimal" framing. Scope: - 03-c4-context.md (54 lines) — purpose / inside-the-box / diagram reference / external actor table with required-vs-optional column / scope-out / open questions. - diagrams/c4-context.mmd (44 lines) — flowchart LR + project palette (red/amber/green/blue), same engine as 02-trust-boundaries.mmd. Convention: solid = required, dashed = optional configuration. Five research agents (competitor format sweep, legacy mine, OCU value articulation, OCU-vs-Wide-Moat boundary, diagram-format advisor) synthesised in docs/future-architecture/research/SUMMARY-layer4.md. Key agreed decisions: - OCU is the central box; Wide-Moat is mentioned once as the opinionated bundle that ships OCU + peers (n8n, Open WebUI) as one curated stack but is not required for OCU to be useful. - Siblings are an open class: any MCP-speaking peer is a first-class integration; REST is a fallback. n8n and Open WebUI are examples in the bundle, not the definition of "sibling." - The §02 §3 actor table stays the single source of truth — Layer 4 cross-references it instead of duplicating, then adds an "optionality" column the actor table did not need at Layer 3. - LLM upstream is NOT a separate actor on Layer 4 — it is one of the MCP-speaking peers (model-neutral by construction). Customer object store is not an actor either — §02 line 45 already classifies it as an outbound endpoint behind the egress policy, not a contract-bearing actor. No backport to §02 §3 needed. - Preamble framing (Why OCU): practitioner-first value-creation ("build automations once, delegate, scale across a team without leaving the safety boundary"), with model-neutrality via MCP as the integration property. Not TPRM-first, not moat-intersection. Diagram engine: plain Mermaid flowchart with the project palette verbatim from 02-trust-boundaries.mmd. Rejected alternatives: Mermaid C4Context (upstream-experimental, palette divergence), C4-PlantUML (no GitHub-native render). Open question §6 #1 (Wide-Moat bundling status for n8n + Open WebUI on next/v1) tracked at #154. The integration shape is locked here; the packaging decision is not Layer 4's job. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…wers)
Four reviewers (gsd-code-reviewer, gsd-plan-checker, cross-architectural
coherence, competitor comparison) converged on one load-bearing defect
plus 12 follow-ups. Verdict matrix: 2 Error / 4 Warning / 7 Info.
Errors (block merge):
1. LLM upstream as inbound MCP peer — three reviewers caught it.
§02 trust-boundaries:45 explicitly classifies LLM upstream as an
outbound endpoint behind the egress policy ("not actors against our
contracts"), and 02-trust-boundaries.mmd:13 draws it as a separate
outbound node. Listing it inside the inbound PEER node label put two
opposing semantics on the same name. Fix: drop "LLM upstream" from
the PEER node label and from the §4 actor-row example list. The
§41 paragraph remains the canonical mention.
2. AI-guardrail anchor pointed at §02 §6 (Data classification taxonomy);
the ownership statement lives in §02 §2 zone 4 / §7. Repointed to
§2 zone 4 so the link lands where the claim actually lives.
Warnings:
3. SIEM edge was solid in c4-context.mmd:35, but SIEM is :::extOpt
(dashed-border optional). Layer 4's own header convention says
"solid border = required; dashed border = optional configuration".
The Layer 3 diagram already draws it dashed. Fixed.
4. "Layer 6" forward references in three places (doc §2 / §3 + diagram
BOX node). Layer 6 does not exist as an artifact. Reworded to
"Internal decomposition is out of scope at this layer" + dropped
the pointer line from the diagram BOX node.
5. BOX node carried three lines of internal description that duplicated
§1 prose. Collapsed to a single role-line
"Open Computer Use / in-perimeter agent-execution platform".
6. §1 first sentence opened with value-prop voice ("users build
automations once, delegate them to agents..."). Replaced with a
scope declaration; the practitioner framing remains in §01
audience-and-buyer where it belongs.
Info / polish:
7. Palette claim in §3 named all four colors (red / amber / green /
blue) but the diagram only uses red + green. Weakened claim to
"red-untrusted / green-trusted convention; amber and blue from the
trust-boundary diagram do not apply at the Context level".
8. Added solo-install callout in §3: "the solid / dashed split makes
the one-click solo-install path visible at a glance".
9. SIEM Role cell rephrased to "OCSF v1.x event bridge consumed by the
customer's SIEM" for voice consistency with other customer-* rows.
10. Dropped repetitive `02-trust-boundaries.md §3` link from each actor
row (the preamble already pins the actor table to §02 §3). Renamed
column to "NFR anchor"; em-dash where no NFR anchor exists.
11. Operator edge in diagram now labelled `PAM-JIT SAML attr / NFR-COMP-29`
matching 02-trust-boundaries.mmd:47.
12. PEER edge label simplified to `MCP authz spec / audience-validated`
matching the Layer 3 wording.
13. Added compliance pointer after the actor table: "Regulator citations
and measurable targets for each row land in manifesto/02-nfrs.md".
14. Added footnote tracing master-plan `agent user` → folded behind
`MCP-speaking peer` (humans drive OCU only through an MCP-speaking
peer; direct human-to-OCU UI is a v1 non-goal).
Length 58 lines (≤80 budget). Banned vocab grep clean.
ai-slop-detector OK. No new ASCII diagrams.
Glossary additions (MCP-speaking peer, REST fallback, Wide-Moat
opinionated bundle) and a few cross-doc reconciliations (NFR-FLEX-14 vs
REST fallback wording, Layer 3 SOAR edge dashed-vs-solid) deliberately
deferred to a follow-up PR — not Layer 4 scope.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
W-01 — IdP optionality row: rewrite to two-clause form mirroring SIEM
("optional on minimal shelf (local auth fallback) — required on
full-capability shelf"); resolves doc/diagram mismatch where doc said
"required on full shelf" but .mmd drew IDP dashed.
I-01 — Trim .mmd palette comment: list only colors actually used at
Context level (red, green); amber/blue carve-out already explained in
§3 prose.
I-03 — Bind "regulated-enterprise" term once in §1 (CLAUDE.md default
audience term) so a cold reader knows what flavor of customer
"customer's existing IdP" means.
I-05 — Drop "Master-plan agent user" phrasing (term not defined
anywhere in architecture tree); rewrite as plain "humans drive OCU only
through an MCP-speaking peer" sentence.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Yambr
force-pushed
the
feat/manifesto-04-c4-context-draft
branch
from
2a78b1b to
59021ca
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
next/v1manifesto stack: one ≤80-line doc + one canonical Mermaid, per the plan's intentionally-minimal framing for this layer.docs/future-architecture/research/SUMMARY-layer4.md.Files
docs/architecture/03-c4-context.md(54 lines) — purpose, inside-the-box, diagram reference, external-actor table with required-vs-optional column, scope-out, one tracked open question.docs/architecture/diagrams/c4-context.mmd(44 lines) —flowchart LR+ project palette (red untrusted / amber semi-trusted / green trusted / blue isolated), same engine and conventions as02-trust-boundaries.mmd. Solid border = required; dashed = optional configuration.Decisions encoded
02-trust-boundaries.md:45already classifies it as an outbound endpoint behind the egress policy. No §02 §3 backport needed.flowchart LRper the format advisor's verdict A (MermaidC4Contextis upstream-experimental; PlantUML doesn't render on GitHub natively).Open question
§6 #1 — Wide-Moat bundling status for n8n + Open WebUI on
next/v1(integration shape vs packaging) tracked at #154. Layer 4 locks the integration shape; packaging is not Layer 4's scope.Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit