Creating Your First Project

This guide walks you through creating your first architecture documentation project in Archyl by drawing it in the app, from initial setup to sharing with your team.

Drawing is one of four ways to start. You can also let AI discover the architecture from your code, write it as code in an archyl.yaml, or import it from Structurizr, LikeC4, IcePanel or Backstage. Choose How to Start compares them and walks through a monorepo.

Prerequisites

Before you begin:

  • An Archyl account (sign up here)
  • A software system you want to document
  • Optionally: Access to your codebase repository

Step 1: Create a New Project

From the Dashboard

  1. Log in to Archyl
  2. Click the "+ New Project" button
  3. Enter your project details:
    • Name: A clear, descriptive name (e.g., "E-commerce Platform")
    • Description: Brief overview of the system
    • Tags: Keywords for organization (e.g., "backend", "microservices")
  4. Click "Create Project"

Project Settings

After creation, configure your project:

  • Visibility: Public or private
  • Team access: Which teams can view/edit
  • Repository: Connect for AI discovery (optional)

Step 2: Understand the System Context

Before drawing diagrams, understand your system's context:

Identify Users

Who uses your system?

  • End users (customers, employees)
  • Administrators
  • External developers
  • Other systems

Identify External Systems

What does your system interact with?

  • Payment processors
  • Authentication providers
  • Email/notification services
  • Analytics platforms
  • Partner APIs

Step 3: Create the System Context Diagram

Add Your Main System

  1. In the empty canvas, click "+" or right-click
  2. Select "Add System"
  3. Enter:
    • Name: Your system's name
    • Description: What it does
    • Type: Internal (you own it)

Add Users

  1. Click "+" and select "Add Person"
  2. Create each user type:
    • Name: "Customer", "Admin User", etc.
    • Description: Their role and what they do

Add External Systems

  1. Click "+" and select "Add External System"
  2. For each external dependency:
    • Name: "Stripe", "SendGrid", etc.
    • Description: What it provides

Create Relationships

  1. Hover over the source element
  2. Drag from the connection point to the target
  3. Add a label: "Places orders via", "Sends emails through", etc.
  4. Optionally add technology: "REST/HTTPS", "SMTP"

Step 4: Dive into Containers

Open the Container View

Double-click on your main system to zoom into the Container level.

Identify Containers

What are the technical building blocks?

  • Applications: Web app, mobile app, desktop client
  • Services: API server, background workers
  • Data stores: Databases, caches, file storage
  • Message queues: Event buses, queues

Add Containers

For each container:

  1. Click "+" and select "Add Container"
  2. Enter:
    • Name: "Web Application", "API Server", "PostgreSQL"
    • Description: Its responsibility
    • Technology: "React", "Node.js", "PostgreSQL 15"

Connect Containers

Show how containers communicate:

  • Web App → API Server: "Makes API calls [REST/HTTPS]"
  • API Server → Database: "Reads/writes data [SQL]"
  • API Server → Cache: "Caches session data [Redis protocol]"

Step 5: Add Components (Optional)

For critical containers, zoom into components:

  1. Double-click a container
  2. Add components representing major modules:
    • Controllers
    • Services
    • Repositories
    • Utilities

Step 6: Fill In the Rest Faster (Optional)

Drawing every component by hand takes time. Two ways to fill in the model from your code:

Use AI Discovery

  1. Connect the repository: see Git Integration
  2. Start a discovery and wait for the analysis to complete
  3. Review what it found: approve accurate items, edit names and descriptions, reject the rest

A discovery proposes only what the model does not already have, so what you drew stays as it is. See AI Discovery.

Manage the Model as Code

Write the rest in an archyl.yaml and push it with the CLI. archyl dsl pull first writes what you drew to the file, so you start from it:

archyl init        # link the repository to this project
archyl dsl pull    # what you drew, as archyl.yaml
archyl dsl push    # after editing it

See Architecture as Code.

Step 7: Add Documentation

Element Descriptions

Click any element and add detailed descriptions:

  • Purpose and responsibilities
  • Key decisions made
  • Important notes

Architecture Decision Records

Document important decisions:

  1. Go to ADRs section
  2. Click "New ADR"
  3. Fill in:
    • Title: "Use PostgreSQL for persistence"
    • Context: Why this decision was needed
    • Decision: What was decided
    • Consequences: Impact of the decision

Link Documentation

Link ADRs and docs to specific elements for context.

Step 8: Share with Your Team

Invite Team Members

  1. Go to Project Settings → Team
  2. Click "Invite"
  3. Enter email addresses
  4. Assign roles (Viewer, Editor, Admin)

Create Share Links

For stakeholders without accounts:

  1. Click "Share" in the toolbar
  2. Configure access options
  3. Copy and share the link

Export Diagrams

For presentations or documents:

  1. Click "Export"
  2. Choose format (PNG, SVG, PDF)
  3. Download your diagrams

Best Practices

Start Simple

  • Begin with System Context
  • Add detail progressively
  • Don't try to document everything at once

Keep It Current

  • Update when architecture changes
  • Run AI discovery after major changes, or push archyl.yaml from CI
  • Review regularly with your team

Focus on Communication

  • Use clear, descriptive names
  • Add context in descriptions
  • Show the most important relationships

Next Steps

Congratulations! You've created your first architecture documentation. Continue learning: