Arch domain model

[ainetx]

Summary by CodeRabbit

• Documentation
  • Added a comprehensive overview of Constructor Studio’s architecture and domain model in business-friendly terms.
  • Included a visual diagram, quick-reference tables, workflow guidance, governance/quality gate explanations, glossary definitions, and next steps.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5ec2b128-ab75-412c-826c-87bf2308173b

📥 Commits

Reviewing files that changed from the base of the PR and between dd4d13b and 8f6176f.

📒 Files selected for processing (1)

• STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md

✅ Files skipped from review due to trivial changes (1)

• STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md

---

📝 Walkthrough

Walkthrough

Added a business-oriented Constructor Studio architecture and domain model overview covering core concepts, PM workflows, action and data models, governance controls, quality gates, and technical glossary mappings.

Changes

Studio domain model documentation

Layer / File(s)	Summary
Document orientation and architecture STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md	Adds document navigation, Studio usage guidance, and a visual map of Studio’s models, kits, UI, and external systems.
Domain models and PM workflow STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md	Defines core business terms, daily PM workflows, Data Model entities, and Action Model components.
Governance and reference material STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md	Documents validators, approvals, policies, model routing, cost controls, audit trails, Constructor Fabric context, next steps, and glossary identifiers.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: adding an architecture/domain model overview document.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch arch-domain-model

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 6

🧹 Nitpick comments (1)

STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md (1)

69-74: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Clarify ownership of external-system ingestion.

The diagram shows both Constructor Insight and Studio Connectors feeding Work Items, but the document does not define whether these are separate ingestion paths, which is authoritative, or how duplicate updates and identities are reconciled. Add the boundary, ownership, and upsert/deduplication rules.

Also applies to: 176-180, 228-228, 250-250

🤖 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 `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md` around lines 69 - 74, Clarify in
STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md how Constructor Insight and Studio
Connectors relate to Work Item ingestion: define each system’s boundary and
ownership, identify the authoritative source, and document how duplicate
updates, identities, and upserts/deduplication are reconciled. Apply the
clarification consistently to the related sections and references to Work Items,
Constructor Insight, and Studio Connectors.

🤖 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 `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md`:
- Around line 129-132: The provenance model only identifies Automation Runs and
cannot represent human actors. Update the Work Item provenance fields and
related descriptions to use an actor type plus actor ID, or separate user and
run identifiers, ensuring both human and Automation Run changes are traceable;
apply the same correction to the additional provenance section.
- Around line 136-142: The documentation incorrectly excludes zero-link Work
Items from traceability analysis. Update the Link graph and gap-detection
descriptions around the affected sections to define orphan detection as an
analyzer over all Work Items, with missing Links represented as findings,
including requirements without test coverage; apply the same correction to the
corresponding Recommendations text.
- Around line 131-132: Clarify the staleness score definition in the glossary
and the “Staleness” description: explicitly state whether 1 represents most
stale or most current, whether 0 represents the opposite, and whether the
Recommendation threshold is inclusive or exclusive. Ensure the same semantics
are applied consistently in the related definition.
- Around line 220-224: The Audit trail section must define privacy and retention
controls for immutable Automation inputs and outputs. Update the “Audit trail”
subsection to specify sensitive-data redaction, encryption, access scope, and
retention/deletion rules, including how these controls apply to Work Item,
Automation, and Organization-level access.
- Around line 178-180: Document a distinct connector write-back policy surface
alongside Organization policy, covering per-operation scope, permitted target
systems, credential usage, and approval requirements; update the Connector and
related policy descriptions to reference this separate policy rather than
implying existing Automation policy is sufficient.
- Around line 204-206: The approval model must enforce immutable platform-level
approval baselines for all high-risk actions; update the relevant documentation
around the approval requirements to state that Kits and Flows may only add
stricter checks, while administrators configure approvers within those mandatory
platform constraints.

---

Nitpick comments:
In `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md`:
- Around line 69-74: Clarify in STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md how
Constructor Insight and Studio Connectors relate to Work Item ingestion: define
each system’s boundary and ownership, identify the authoritative source, and
document how duplicate updates, identities, and upserts/deduplication are
reconciled. Apply the clarification consistently to the related sections and
references to Work Items, Constructor Insight, and Studio Connectors.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: cf996cdb-b28d-4bf5-86ca-e73a8d556f50

📥 Commits

Reviewing files that changed from the base of the PR and between 0f6e30a and dd4d13b.

📒 Files selected for processing (1)

• STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Use an actor model for provenance.

createdByRunId and lastModifiedByRunId can identify Automation Runs, but they cannot represent the human actor described in the prose. Use an actor type plus actor ID, or separate user and run fields; otherwise the provenance and audit model cannot faithfully record human changes.

Also applies to: 242-243

🤖 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 `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md` around lines 129 - 132, The provenance
model only identifies Automation Runs and cannot represent human actors. Update
the Work Item provenance fields and related descriptions to use an actor type
plus actor ID, or separate user and run identifiers, ensuring both human and
Automation Run changes are traceable; apply the same correction to the
additional provenance section.

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Define the staleness score direction.

The glossary specifies a 0–1 score but not whether 1 means “most stale” or “most current,” nor whether the threshold is inclusive. State the direction and threshold semantics so UI indicators and Recommendation logic are implementable consistently.

Also applies to: 242-242

🤖 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 `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md` around lines 131 - 132, Clarify the
staleness score definition in the glossary and the “Staleness” description:
explicitly state whether 1 represents most stale or most current, whether 0
represents the opposite, and whether the Recommendation threshold is inclusive
or exclusive. Ensure the same semantics are applied consistently in the related
definition.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Allow analyzers to detect zero-link Work Items.

Line 140 says a Work Item with no Links is not visible to traceability analysis, but the Recommendations section explicitly promises findings such as requirements with no test coverage. Define orphan detection as an analyzer over Work Items, where missing Links are themselves findings; otherwise this core Recommendation cannot be produced.

Also applies to: 184-186

🤖 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 `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md` around lines 136 - 142, The
documentation incorrectly excludes zero-link Work Items from traceability
analysis. Update the Link graph and gap-detection descriptions around the
affected sections to define orphan detection as an analyzer over all Work Items,
with missing Links represented as findings, including requirements without test
coverage; apply the same correction to the corresponding Recommendations text.

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

sed -n '160,230p' STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md
rg -n "Organization|policy|Automation|connector|write-back|approval|credential|scope" STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md

Repository: constructorfabric/vision

Length of output: 19792

---

🏁 Script executed:

rg -n "write-back policy|write back policy|write-back|connector.*policy|policy.*connector|connector.*approval|approval.*connector" .

Repository: constructorfabric/vision

Length of output: 1360

---

🏁 Script executed:

sed -n '360,420p' STUDIO_VISION.md
sed -n '300,340p' STUDIO_VISION.md

Repository: constructorfabric/vision

Length of output: 3682

---

Define a separate policy surface for connector write-back. Organization policy currently covers Automation categories, models, and spending, but external writes need explicit rules for per-operation scope, target systems, credentials, and approval.

🤖 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 `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md` around lines 178 - 180, Document a
distinct connector write-back policy surface alongside Organization policy,
covering per-operation scope, permitted target systems, credential usage, and
approval requirements; update the Connector and related policy descriptions to
reference this separate policy rather than implying existing Automation policy
is sufficient.

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the cited section with line numbers
sed -n '190,220p' STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md | cat -n

# Find other mentions of approval requirements / high-risk actions / baseline language
rg -n "approval requirements|high-risk actions|explicit human approval|Kit and Flow designers|Organization level|Workspace|security exception|breaking changes|delegated|chained" .

# Map related docs/files if any are found
fd -i "approval|flow|kit|organization|workspace" .

Repository: constructorfabric/vision

Length of output: 7601

---

Require platform-level approval baselines. STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md:204-206 currently makes approval requirements something Kit/Flow designers define, so a high-risk action could be modeled without any mandatory approval. Keep the baseline immutable at the platform level and let Kits/Flows only add stricter checks.

🤖 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 `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md` around lines 204 - 206, The approval
model must enforce immutable platform-level approval baselines for all high-risk
actions; update the relevant documentation around the approval requirements to
state that Kits and Flows may only add stricter checks, while administrators
configure approvers within those mandatory platform constraints.

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== File size =="
wc -l STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md

echo
echo "== Relevant sections =="
sed -n '200,260p' STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md | cat -n

echo
echo "== Search related terms =="
rg -n --hidden --glob '!**/.git/**' -e 'audit trail|Automation Run|retention|redaction|encryption|privacy|sensitive payload|budget status|audit history' .

Repository: constructorfabric/vision

Length of output: 8125

---

Define audit-payload privacy and retention controls. The audit trail records immutable Automation inputs and outputs, so this should specify redaction, encryption, access scope, and retention/deletion rules before treating the design as complete.

🤖 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 `@STUDIO_ARCH_DOMAIN_MODEL_OVERVIEW.md` around lines 220 - 224, The Audit trail
section must define privacy and retention controls for immutable Automation
inputs and outputs. Update the “Audit trail” subsection to specify
sensitive-data redaction, encryption, access scope, and retention/deletion
rules, including how these controls apply to Work Item, Automation, and
Organization-level access.