AI-Powered Discovery

Archyl's AI Discovery feature analyzes your codebase to automatically discover and document your software architecture. This saves hours of manual documentation work and ensures your architecture documentation stays in sync with your actual code.

How It Works

1. Connect Your Repository

First, connect your Git repository to Archyl:

1. Go to your project settings
2. Click "Connect Repository"
3. Choose your Git provider (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, or self-hosted instances)
4. Authorize Archyl to access your repository

2. Start Discovery

Once connected, start the AI discovery:

1. Click "Start Discovery" in your project
2. Select which branch to analyze
3. Click "Run Discovery"

3. AI Analysis

The AI analyzes your codebase in multiple phases:

1. Structure Analysis — Identifies the system name, containers, and external dependencies
2. Detailed Discovery — Analyzes source files in parallel chunks to find components, code elements, and relationships
3. Relationship Refinement — Cross-references containers to find inter-service dependencies
4. Parallel Post-Analysis — Discovers ADRs, documentation, API contracts, and package dependencies

Elements discovered include:

• Systems: Top-level software systems and external dependencies
• Containers: Services, APIs, databases, web applications, workers
• Components: Modules, packages, handlers, repositories, services
• Code Elements: Classes, interfaces, functions with file paths
• Relationships: How elements communicate (uses, calls, sends to, reads from)

4. Review & Approve

Discoveries are placed in a Pending state for review:

1. Review each discovered element
2. Edit names, descriptions, or relationships
3. Approve accurate discoveries
4. Reject or modify incorrect ones

For new projects (no existing C4 elements), discoveries are auto-approved to get you started quickly.

Incremental Discovery

Incremental discovery keeps your C4 model up to date by analyzing only the files that changed — not the entire repository. This is faster, cheaper, and can run automatically on every push.

How Incremental Discovery Works

1. Code is pushed to the default branch
2. Archyl receives the push event (via webhook or GitHub Action)
3. Changed files are extracted from the push commits
4. Only source files are analyzed (removed files are skipped)
5. AI runs on the smaller file set
6. New elements are created as pending discoveries for review
7. Existing elements are automatically deduplicated — no duplicates

Enabling Incremental Discovery

There are two ways to enable incremental discovery:

Option A: GitHub Webhook (Zero Config)

1. Go to your project's Webhook Config settings
2. Enable Discovery on Push
3. Copy the webhook URL and add it to your GitHub repository settings
4. Select the push event

Every push to the default branch will trigger incremental discovery automatically.

Option B: GitHub Action (CI/CD)

Add the Archyl Incremental Discovery action to your workflow. See GitHub Actions Integration for full setup instructions.

name: Architecture Sync
on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Full vs. Incremental Discovery

Combining Full + Incremental

The recommended workflow:

1. Run full discovery when you first connect a repository
2. Enable incremental discovery to keep the model fresh
3. Re-run full discovery after major refactors or migrations

Incremental discovery creates pending elements just like full discovery — you always review before changes are applied to your C4 model.

Supported Technologies

AI Discovery works with 15+ languages and frameworks:

Languages

Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, Scala

Frameworks

React, Next.js, Vue, Angular, Express, Fastify, NestJS, Django, Flask, FastAPI, Spring Boot, ASP.NET Core, Ruby on Rails, Gin, Fiber

Infrastructure

Docker, Kubernetes, Terraform, Helm, Ansible, GitHub Actions, AWS CDK, Pulumi

Monorepo Support

Archyl automatically detects monorepo structures:

• apps/, packages/, services/, libs/ directories
• Proportional file sampling across services
• Each service maps to a separate container in the C4 model
• Cross-service relationships are detected

Best Practices

Start Small

For large codebases:

1. Start with a single service or module
2. Review and refine the results
3. Gradually expand to other areas

Regular Updates

Keep your documentation current:

1. Enable incremental discovery for automatic updates
2. Review pending discoveries regularly
3. Run full discovery after major refactors

Combine with Manual

AI Discovery is a starting point:

1. Use AI for the heavy lifting
2. Add business context manually (descriptions, ADRs)
3. Refine relationships and descriptions

REST API

POST   /api/v1/discovery/start                            # Start full discovery
GET    /api/v1/discovery/jobs/:jobId                       # Get job status
POST   /api/v1/projects/:id/discovery/incremental          # Trigger incremental discovery

Troubleshooting

Discovery Takes Too Long

• Reduce the number of files analyzed (adjust max files in config)
• Use incremental discovery for regular updates
• Focus on specific branches

Inaccurate Results

• Review and correct as you go — the pending system lets you approve/reject each element
• More structured code produces better results
• Add descriptions to approved elements to improve context for future discoveries

No Files Analyzed

• Check that your repository is connected and the branch exists
• Ensure source files have recognized extensions (.go, .ts, .py, .java, etc.)
• Verify the access token has read permissions on the repository