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: