Your First Project

This guide covers creating a full architecture project in Archflow, from setting up your project to generating documentation.

Project Structure

An Archflow project contains:

• Systems --- The software components, services, and external dependencies in your architecture
• Connections --- The relationships and data flows between systems
• Diagrams --- Visual views of your architecture (you can have multiple)
• Workflows --- Business processes that span multiple systems
• Deployments --- Infrastructure and deployment configurations
• Documentation --- AI-generated or manually written architecture docs

Project Sidebar Navigation

Once inside a project, the sidebar provides access to all areas:

A version picker appears in the project header, letting you switch between architecture versions. The current version name (e.g., "main") is displayed next to the page title.

Step 1: Plan Your Architecture

Before opening Archflow, sketch out what you want to model:

• What are the main systems or services?
• Who are the users or external actors?
• What external systems do you integrate with?
• How do these components communicate?

Step 2: Create Systems

Navigate to Systems in the project sidebar. The systems page shows summary statistics at the top --- Total Systems, Applications, Containers, and Components --- and offers three view modes:

• Tree view --- Hierarchical view with drag-and-drop reordering
• Card view --- Grid of system cards
• Table view --- Tabular view with sortable columns

Click Add Element to create a new system. For each system, you can define:

You can also click Document All Elements to batch-generate documentation for all systems, or Import Project to import an external project as a subsystem.

System Hierarchy

Archflow supports nested systems following the C4 model:

Software System
  └── Container (e.g., Web App, API, Database)
        └── Component (e.g., Auth Module, Payment Service)

Use the parent system field to create this hierarchy. In Tree view, you can drag systems to rearrange the hierarchy. Each system shows a completion percentage badge and connection count.

Step 3: Define Connections

Navigate to Connections in the sidebar. Connections describe how systems interact. For each connection, specify:

• Source and Target --- Which systems are connected
• Description --- What data or actions flow between them
• Technology --- The communication protocol or technology
• Direction --- Whether the flow is one-way or bidirectional

You can also create connections directly on the diagram canvas by dragging from one system's connection handle to another.

Step 4: Create Diagram Views

Navigate to Views and click Create Diagram to create a new view. Each view provides multiple perspectives through its tabs:

• Editor --- The main canvas for arranging systems and drawing connections
• Workflows --- Select and manage business process workflows for this view
• Infrastructure --- Model deployment nodes and infrastructure
• Documentation --- Generate, edit, and publish AI documentation

Create multiple views to show different aspects of your architecture:

• A high-level context view for stakeholders
• Detailed container views for development teams
• Component views for specific subsystems

Step 5: Add Workflows

Navigate to Workflows in the project sidebar. Workflows model business processes that span multiple systems. They help answer questions like:

• "How does a user complete a purchase?"
• "What happens when an order is placed?"

Create workflows to map these processes, linking each step to the relevant system in your architecture. Each workflow has its own canvas where you can visually arrange process steps.

Step 6: Generate Documentation

Open a diagram view and switch to the Documentation tab. Click Generate Documentation to open the generation modal with three tabs:

1. Content Type --- Choose full overview or section-specific generation
2. Customize --- Set audience, technical level (1-10), focus areas, and more
3. Generate --- Review settings and generate

The AI analyzes your systems, connections, workflows, and deployments to produce comprehensive documentation. See the Generating Documentation guide for details.

Tips

• Start simple --- Begin with a context-level view before drilling into containers and components
• Use meaningful names --- Clear naming makes diagrams self-documenting
• Add descriptions --- Even brief descriptions help the AI generate better documentation
• Version your work --- Use the version picker to create snapshots before major changes
• Ask Archie --- The AI assistant in the right sidebar can analyze your architecture and suggest improvements