Archflow Modeling And Review Practices

Model For Questions

Start with the architecture questions the team needs to answer. Model boundaries, ownership, information, journeys, and deployment detail only to the depth needed for those questions.

• Name Systems and capabilities in human language.
• Put source paths, packages, and symbols in descriptions or evidence.
• Use one canonical resource rather than duplicating the same fact across surfaces.
• Keep hierarchy architectural: System → Container → Component → Block.
• Give every Relationship a direction, interaction style, and meaningful description.

Keep Structure And Behavior Separate

Relationships describe intended static architecture. Workflows provide named runtime co-activity. The Behavior Model captures lower-level commands, events, policy, state, and questions.

Connect these evidence types, but do not collapse them into one overloaded diagram.

Use The Data Model For Logical Information

Give each logical entity one canonical architecture owner and represent readers and writers as usages. Keep physical tables, ORM classes, transport payloads, and source symbols out of the logical model unless they are genuinely the concept being reviewed.

Build Focused Views

• Use Explorer for read-only orientation.
• Use Sketch for rapid architecture editing.
• Use Architecture Views for curated review and publication.
• Keep one audience and one question per View.
• Reference canonical Architecture Documents instead of copying text between Views.

Treat Analysis As Evidence

Complexity, Blast Radius, and Coupling are model-derived review aids. Confirm version, scope, and context/module/leaf lens before comparing results.

• Investigate the path behind a score.
• Compare static and workflow evidence.
• Validate operational claims with telemetry and testing.
• Promote only accepted conclusions into Decisions or the Handbook.

Work Safely With Archie

• Confirm the selected version and focused resource.
• Ask for the evidence behind recommendations.
• Inspect artifacts and approval cards before applying changes.
• Reconcile interrupted changes instead of duplicating them.
• Use Architecture Simulations for durable future-state exploration.

Curate Knowledge

Uploaded sources are evidence, not accepted truth. Review extracted candidates, memories, and insights before allowing them to influence future work. Put formal goals, constraints, ADRs, quality requirements, risks, and debt in the Architecture Handbook.

Version Before Significant Change

Create a named baseline or Architecture Simulation before a redesign. Keep candidates inactive until reviewed, compare before merge, and verify the result after merge.

Match Access To Purpose

• Use project roles for collaborators.
• Use private publications and expiring guest links for readers.
• Start MCP clients read-only and enable writes only for defined work.
• Prefer project-scoped credentials over account tokens when possible.
• Revoke obsolete shares and rotate exposed tokens.

Keep Documentation Current

Use generation as a feedback loop: generate, find weak evidence, improve the model, regenerate the affected section, and edit for project-specific truth. Record the owning version and republish after material changes.