Creating Your First Project - Archyl Docs

A step-by-step guide to creating and documenting your first architecture project in Archyl

Creating Your First Project

This comprehensive guide walks you through creating your first architecture documentation project in Archyl, from initial setup to sharing with your team.

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: Use AI Discovery (Optional)

Let AI help document your architecture:

Connect Repository

  1. Go to Project Settings → Repository
  2. Connect your Git provider
  3. Select your repository

Run Discovery

  1. Click "Start Discovery"
  2. Wait for analysis to complete
  3. Review pending discoveries

Review & Approve

  1. Check each discovered element
  2. Edit names/descriptions if needed
  3. Approve accurate items
  4. Reject or modify incorrect ones

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
  • 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: