Best Practices

These best practices will help you get the most out of Archflow for your architecture documentation.

Modeling

Start with Context

Begin with a high-level context diagram before diving into details. This establishes the scope and identifies key actors and external dependencies.

Use Consistent Naming

Adopt a naming convention and stick with it:

Systems: Use noun phrases ("Order Service", "Customer Database")
Connections: Describe the action ("Sends order data", "Authenticates users")
Workflows: Use verb phrases ("Process Payment", "Onboard Customer")

Describe Everything

Every system, connection, and workflow step should have a description. Even a brief sentence makes a difference for:

Readability of your diagrams
Quality of AI-generated documentation
Onboarding new team members
Archie's ability to analyze your architecture

Model What Matters

You don't need to model every class or function. Focus on:

System boundaries and responsibilities
Integration points and data flows
Business-critical processes
Infrastructure decisions

The Dashboard is your starting point. Use the stat cards (Projects, Systems, Diagrams, Connections, Deployments) to get a quick pulse on your architecture work. Check recent projects to jump back into active work.

Diagram Layout

Follow Convention

Arrange diagrams following common patterns:

Users/actors at the top or left
Your systems in the center
External systems on the periphery
Data flow left-to-right or top-to-bottom

Keep It Clean

Avoid crossing connections where possible
Use consistent spacing between systems
Group related systems together
Create separate diagram views for different concerns

One Purpose Per Diagram

Each diagram should answer one question:

"What does our system interact with?" (Context)
"What are the main building blocks?" (Container)
"How is this service structured internally?" (Component)

Working with Archie

Ask Early and Often

Archie is context-aware with 100+ tools across 12+ categories. Use it to:

Analyze your architecture for patterns and issues
Generate documentation for systems and connections
Identify gaps in your architecture coverage
Navigate to relevant pages and resources

Use Context

Archie automatically detects your current page. When you're on a system page, ask "tell me about this system" --- Archie already knows which system you mean.

Store Memories

Use Archie's memory feature to store architectural decisions and context that persists across sessions.

Documentation

Generate Early, Iterate Often

Don't wait until your architecture is "complete" to generate documentation. Use AI documentation as a feedback mechanism:

Generate documentation after initial modeling
Review the output for gaps and inaccuracies
Improve your model based on what's missing
Regenerate specific sections
Hand-edit for final polish

Layer Your Documentation

Use different technical levels for different audiences:

Level 1-3: Executive summaries and business stakeholders
Level 4-6: Solution architects and technical leads
Level 7-10: Development teams and implementation details

Include Visual Context

Upload architecture screenshots and diagrams using the image gallery. Enable visual references when generating to embed deployment and architecture images directly in the documentation.

Keep Documentation Current

Architecture documentation loses value quickly when it drifts from reality. Update your Archflow models when the architecture changes, and regenerate documentation accordingly.

Complexity & Blast Radius

Use the Architecture hub to monitor architectural health:

Complexity --- Check the NK model coupling matrix for tightly coupled systems
Blast Radius --- Analyze change impact before refactoring any system
Context Map --- Verify DDD context relationships are consistent
Architecture Health --- Ask Archie for a combined assessment

Run blast radius analysis before making significant changes to understand the full scope of impact across systems and workflows.

MCP Integration

If your team uses AI coding assistants, set up MCP Integration to bring Archie's tools into your IDE:

Generate MCP API keys from project Settings → MCP / API
Configure Claude Code, Cursor, or Windsurf with the provided config
Ask your IDE assistant architecture questions without switching tools

Source Documents

Use Source Documents to bootstrap projects from existing documentation:

Upload RFPs, design docs, or architecture decision records
Let AI extract systems, connections, and knowledge blocks
Review and sync extracted data into your project
Useful for migrating from other tools or capturing meeting notes

Use published documentation for stakeholder communication
Use groups for team collaboration
Use export for archiving and backup

Learning

Browse ArchDeck to build your architecture knowledge. The card library covers design patterns, integration patterns, cloud architecture, and DDD concepts in a digestible card format.