🏗️ Archlette

Code speaks. Archlette listens. Architecture evolves.

Architecture shouldn't live in slides. It should live with your code.

Archlette analyzes your TypeScript/JavaScript codebase and generates C4 architecture diagrams automatically. Your code is the source of truth. Your diagrams stay synchronized.

Documentation | Quick Start

---

Why Archlette?

Code as truth. Diagrams as artifacts.

• Code is the source — diagrams follow automatically
• Zero boilerplate — annotations only when needed
• Multiple outputs — Structurizr DSL, PlantUML, Mermaid, PNG
• CI-native — runs wherever your code runs

See Archlette documenting itself: architecture docs.

---

Quick Start

Install

npm install -D @chrislyons-dev/archlette

Requirements: Node.js ≥ 18 (Node 20+ recommended), Java ≥ 11

Free and open-source — MIT licensed. No accounts, no telemetry, no lock-in.

See Installation Guide for platform-specific setup.

Annotate

Works with TypeScript, JavaScript, and Astro components:

TypeScript/JavaScript:

/**
 * @module UserService
 * User authentication and management
 *
 * @actor User {Person} {in} End user accessing the system
 * @uses Database Stores user credentials
 */
export class UserService {
  async login(email: string, password: string) {
    // Implementation
  }
}

Astro Components:

---
/**
 * @component Button
 * Reusable button component with multiple variants
 *
 * @uses Icon Displays button icon
 * @actor User {Person} {in} Clicks button to trigger action
 */

interface Props {
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
}

const { variant = 'primary', disabled = false } = Astro.props;
---

<button class={`btn btn-${variant}`} disabled={disabled}>
  <slot />
</button>

Configure

Create .aac.yaml:

project:
  name: MyProject

extractors:
  - use: extractors/builtin/basic-node
    inputs:
      include: ['src/**/*.ts', 'src/**/*.js']
  - use: extractors/builtin/basic-astro
    inputs:
      include: ['src/**/*.astro']

Note: Use basic-node for TypeScript/JavaScript files and basic-astro for Astro components. Both produce compatible IR for aggregation.

Generate

npx archlette

Output:

• docs/architecture/README.md — System overview
• docs/architecture/diagrams/*.png — C4 diagrams
• docs/architecture/workspace.dsl — Structurizr DSL

---

Documentation

Getting Started:

• Quick Start — Complete walkthrough
• Installation — Requirements and setup

User Guide:

• Annotations — JSDoc tags reference
• Configuration — YAML configuration
• CI/CD Integration — GitHub Actions, GitLab CI
• Troubleshooting — Common issues

Reference:

• CLI Commands — Command-line interface
• Component Detection — How extraction works

Extending:

• Plugin Development — Write custom extractors
• Security Guide — Input validation and security model

Contributing:

• How to Contribute — Development setup
• Security Guide — Security architecture and best practices
• Changelog — Release history

---

Extractors

Archlette includes built-in extractors for multiple languages:

basic-node

Extracts architecture from TypeScript and JavaScript codebases using AST analysis with ts-morph.

• Detects components from directory structure or explicit @component tags
• Extracts classes, functions, types, and interfaces
• Parses JSDoc annotations for actors and relationships
• Identifies dependencies from import statements

When to use: TypeScript/JavaScript projects, Node.js backends, frontend libraries

basic-astro

Extracts architecture from Astro components using the Astro compiler.

• Identifies components from Astro file names or @component tags
• Extracts component props, slots, and client directives
• Parses frontmatter code for additional type information
• Detects component composition from template markup
• Works seamlessly with basic-node for full-stack analysis

When to use: Astro-based projects, island architecture, mixed TypeScript + Astro applications

basic-python

Extracts architecture from Python codebases using AST parsing (no runtime required).

• Supports Python 3.8+ syntax
• Detects classes, functions, and dependencies

When to use: Python projects, data science applications, mixed-language monorepos

custom-extractors

Write your own extractor to support additional languages or frameworks. See Plugin Development.

---

Features

Pipeline: Extract. Validate. Generate. Render. Docs.

What it extracts:

• Components, actors, relationships (from JSDoc tags)
• Classes, functions, types (static analysis)
• Dependencies (import statements)

What it generates:

• C4 architecture diagrams (System Context, Container, Component, Code)
• Structurizr DSL workspace
• PlantUML and Mermaid diagrams
• Markdown documentation with embedded diagrams

Extensible: Write extractors. Write validators. Write generators. See plugin development.

---

Example

See the architecture docs generated by Archlette for this project.

---

License

MIT © 2025 Chris Lyons

See THIRD_PARTY_LICENSES.md for runtime dependencies (Structurizr CLI, PlantUML).

---

Links

• Documentation: https://chrislyons-dev.github.io/archlette/
• npm Package: https://www.npmjs.com/package/@chrislyons-dev/archlette
• GitHub Repository: https://github.com/chrislyons-dev/archlette
• Issue Tracker: https://github.com/chrislyons-dev/archlette/issues