Choose How to Start

An Archyl project holds a C4 model of your software: systems, containers, components and code, and the relationships between them. There are four ways to fill it. They can be combined, and none of them locks you in.

Whatever you pick, the next steps are the same: connect your coding agents, and keep the model in step with the code.

Draw it in the app

Create a project from the dashboard, then add systems, containers and relationships on the canvas. The Quickstart walks through it step by step.

Drawing is the right start for a system that does not exist yet, or to sketch the context before any code. You can switch to code later: archyl dsl pull writes what you drew to archyl.yaml.

Discover it with AI

AI Discovery reads a connected repository and proposes systems, containers, components, relationships and technologies. Nothing lands in the model until you approve it.

From the app: connect the repository in Project Settings › Git Integration (see Git Integration), start a discovery, then review what it found.

From the terminal, at the root of the repository:

archyl login
archyl init --new

init --new creates the project, connects the repository from its git remote, runs the discovery while you watch, opens the review, draws the result and offers to connect your coding agents. Useful flags: --name, --team, --branch, --provider for a self-hosted remote (github_enterprise, gitlab_private, gitea), and --yes to accept every default. See the CLI guide.

Discovery handles monorepos: it recognizes apps/, packages/, services/ and libs/, and maps each service to a container.

Write it as code

Describe the architecture in an archyl.yaml at the root of the repository and push it. The file format is in Architecture as Code.

archyl login
archyl init --new --no-discover   # create the project and link this repository, no AI
$EDITOR archyl.yaml               # describe the architecture
archyl dsl diff                   # what a push would create or change
archyl dsl push                   # import it
archyl diagram                    # look at the result

A minimal file:

version: "1.0"
systems:
  - name: Shop
    containers:
      - name: Storefront
        type: web_app
        technologies: [React]
      - name: Orders API
        type: api
        technologies: [Go]
      - name: Orders DB
        type: database
        technologies: [PostgreSQL]
  - name: Stripe
    external: true
relationships:
  - from: Storefront
    to: Orders API
    label: Places orders
    type: calls
  - from: Orders API
    to: Orders DB
    type: reads_from
  - from: Orders API
    to: Stripe
    label: Charges cards
    type: calls

Elements are matched by name. A push creates what is new and updates what changed, and never deletes: an element only Archyl has stays, and archyl dsl diff lists it as "only in Archyl".

Your coding agent can write the first version: run archyl setup, then ask it to describe the repository in archyl.yaml following the schema. It is still your file to review.

To keep the file and the model in step, commit archyl.yaml and either push it from CI with the GitHub Action, or use Sync Now in Project Settings › Architecture as Code. archyl dsl diff --exit-code fails a CI job when they differ.

Import it from another tool

From the project list, click Import Project and pick the format: Archyl YAML, Structurizr DSL, LikeC4, IcePanel JSON or Backstage JSON. A Structurizr workspace split across !include files can be uploaded as a zip. Details, and where each format keeps the project name, are in Importing Projects.

Monorepo walkthrough

This is the code path end to end for a monorepo, without AI discovery:

shop/
├── apps/
│   ├── storefront/
│   └── admin/
├── services/
│   ├── orders/
│   └── payments/
└── packages/
    └── ui/

1. Create the project and link the repository. From the root of the monorepo:

archyl init --new --no-discover --name "Shop" --team platform

This writes .archyl.json, which links the repository to the project. Commit it: it holds no secret.

2. Model one system with a container per deployable. Apps and services become containers. A shared package such as packages/ui is usually not a container of its own: describe it as a component of the containers that use it, or leave it out.

3. Name each container after its folder. This is what lets archyl brief, where, check, impact and the Guard hook tell which element a changed file belongs to: a file belongs to an element when one of the folders in its path has the element's name. The comparison ignores case, spaces and punctuation, and a trailing word such as API, Service or Worker, so Orders Service matches services/orders/… and Payments API matches services/payments/….

4. Choose one file or several. A single archyl.yaml at the root is the simplest. For a large monorepo, give each service its own file next to its code and include them from the root, so each team edits its own part:

# archyl.yaml
version: "1.0"
include:
  - apps/storefront/archyl.yaml
  - services/orders/archyl.yaml
  - services/payments/archyl.yaml
systems:
  - name: Shop
    description: The online shop
  - name: Stripe
    external: true

# services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Shop
    type: api
    technologies: [Go]
relationships:
  - from: Payments API
    to: Stripe
    label: Charges cards
    type: calls

Include paths are relative to the file that declares them, and relationships can point at elements in any of the files. The rules are in Include.

5. Push and check.

archyl dsl diff
archyl dsl push
archyl where services/payments/internal/charge.go   # should name Payments API
archyl diagram "Payments API"                       # the container and its neighbours

If where reports a file as unmatched, rename the container after its folder and push again.

6. Keep it current. Commit archyl.yaml and the included files. Push from CI on changes, or use Sync Now, which fetches the included files from the repository too.

Then put it to work

Once the model exists:

• Connect your coding agents with archyl setup (Claude Code, Cursor, VS Code, Codex), or from the dashboard. They then call plan, brief and the harness before changing code.
• Check changes against it with archyl check and archyl review in CI. See the CLI guide.
• Onboard people and agents with archyl tour: a guided walk through the parts to meet first, with the files to read. archyl tour --markdown > ONBOARDING.md writes it down.
• Explore it with archyl map, archyl diagram <element>, or the canvas in the app.

Combining paths

• Discover, then manage as code: run a discovery, approve it, then archyl dsl pull and commit archyl.yaml from then on.
• Write as code, then discover: a discovery proposes only what the model does not already have, so it can fill in components under the containers you wrote. Review it like any other discovery.
• Draw in the app and push from code: both edit the same model. A push updates what the file describes and leaves the rest alone.