Welcome to ArchonSpecs

Choose the right Archon starting point, capability, and configuration specs for your workflow.

ArchonSpecs is an AI-native software development platform that works everywhere you do. Use this page to pick the right starting point, then drill into the capability and configuration docs that match your workflow.

Start with your surface

Explore core capabilities

Configure and extend

Guides, reference, and support

Governed Architecture

Archon is built on a three-layer governed architecture that ensures every line of code generated is traceable, compliant, and architecturally sound.

The Mental Model

Archon converges the best practices of modern infrastructure and build systems into a single architectural platform:

The Materialized Stack

Archon doesn't just generate boilerplate; it materializes a production-grade NestJS Enterprise Ecosystem. Every project comes pre-configured with a battle-tested technical stack:

1. Remote Layer (SSE & S3)

The Remote Layer acts as the orchestrator for all architectural missions. It manages the lifecycle of a materialization pass and provides the infrastructure for high-scale generation.

• SSE Stream: A persistent real-time channel that pushes file-system mutations directly to the CLI.
• S3 Artifacts: Stores immutable snapshots of compiled project ZIPs and specifications.
• Worker Pool: A pool of specialized MCP workers that execute heavy-duty compilation and validation tasks in isolation.

2. Core Archon (Governance)

This is the "Brain" of the system. It ensures that the generated code adheres to the Design Specification v1.

3. UML Layer (Parsing & Visuals)

The UML Layer translates human-readable ASCII diagrams into machine-readable DiagramIR.

ASCII Text ➔ DiagramIR ➔ DesignSpec ➔ Materialization

Key tools include uml_parse_ascii for parsing and archon_generate_diagram for rendering high-fidelity Mermaid class and sequence diagrams.

CLI Reference

The Archon CLI (`archonspecs`) is a high-performance bridge that connects your local development environment to the Archon Governance remote. It handles secure tool proxying, local shard management, and real-time file-system mutations.

Installation

Install the Archon CLI globally via npm to use it across all your projects.

npm install -g archonspecs

Or run it directly using npx:

npx archonspecs -token <YOUR_SECRET_TOKEN>

Archon Desktop

The ultimate command center for architectural engineering. Archon Desktop provides a visual control plane that goes beyond the limitations of traditional IDEs.

MCP Proxy Mode

By default, running archonspecs starts the MCP Proxy. This mode bridges standard Model Context Protocol (stdio) communication from IDEs like Claude Desktop to the Archon SSE backend.

Local Tool Injection

The proxy automatically augments the remote toolset with local-only capabilities that have direct access to your file system:

Core Runtime Layers

Archon's reliability stems from a multi-layered runtime that provides a deterministic and transactional environment for AI agents.

UML Modeling & Visualization

In the early days of AI coding, developers were forced to explain complex architectures through long, ambiguous prompts. We changed that by introducing the UML Visual DSL.

By parsing simple ASCII diagrams into high-fidelity Mermaid visualizations, Archon gives you a bird's-eye view of your system before a single line of code is written. This isn't just about pretty pictures—it's about creating a machine-readable DiagramIR that powers the rest of the compilation pipeline.

{
  "entities": [
    { "name": "Order", "fields": [...] }
  ],
  "services": [
    { "name": "OrderService", "operations": [...] }
  ]
}

This journey from Visualization to Validation is where the magic happens. Once your diagrams are structurally sound, Archon takes full control of the materialization pipeline—ensuring that every service, entity, and relationship matches your design with zero drift.

The Sharding Process

Large-scale systems are too complex to manage as a single file. Archon solves this through Domain Sharding.

Each module of your system is developed as an independent shard—a discrete piece of the architectural puzzle. Our compilation engine then takes these shards and merges them into a unified DesignSpec.json, validating every relationship and constraint along the way.

This process ensures that your "Identity Management" shard never conflicts with your "Billing" logic, maintaining perfect isolation and integrity.

Materialization Engine

The bridge between intent and reality. Materialization is not a one-time generation; it is a persistent stream of architectural decisions flowing directly into your file system.

Whether it's a new entity requested by an agent or a structural change in your JSON spec, the Materialization Engine calculates the exact delta and applies it via a secure SSE channel.

The Three Levels of Materialization

archonspecs materialize <projectId> --key <authKey>

Incremental Compiler

Codebases should evolve, not rot. The Incremental Compiler is designed for the long-term health of your project. Unlike traditional generators that overwrite your work, our compiler is region-aware—preserving your manual customizations (marked with // @archon-manual) while updating the governed structural code around them.

From O(N) to O(C)

In legacy systems, every small change triggered a "recompile the universe" event. At enterprise scale (100+ domains, 2,000+ entities), this monolithic approach collapses. Archon V2 recompiles only what changed and its immediate affected dependencies.

O(N) ➔ All Specs
  ➔ Full Parse
  ➔ Full Validate
  ➔ Full Compile

O(C) ➔ Changed Shards
  ➔ Affected Deps
  ➔ Cached Partials
  ➔ Parallel Merge

1. Architecture Sharding

Instead of a single DesignSpec.json, the architecture is split into independent compilation units (Shards) stored in spec/domains/.

2. Deterministic Fingerprinting

Every shard is normalized and hashed before compilation. The compiler uses these fingerprints to instantly detect if a shard needs processing without parsing the entire tree.

3. DAG-Based Dependency Resolution

Shards declare their dependencies explicitly. Archon builds a Directed Acyclic Graph (DAG) to guarantee a deterministic compilation order and detect circular dependencies.

4. Transitive Invalidation

If the Identity shard changes, Archon automatically invalidates downstream shards (Billing, Invoices). This ensures that architectural changes propagate safely and the final system remains consistent.

Configuration

Archon discovers configuration in a specific order: 1. Command-line flags, 2. Environment variables, 3. .env files, and 4. .archon/config.json.

Environment Variables

Core Project Files

• .archon/lineage.json: The "DNA" of your project. Tracks identity and architectural version.
• .archon/sync.lock: Prevents concurrent materialization passes from corrupting the workspace.
• .archon/config.json: Local persistent settings for the CLI bridge.

AI Agents & Workspace

Archon doesn't just generate code; it materializes a complete AI-native workspace. It provides your agents with the instructional foundation and context they need to operate autonomously.

What we materialize

When you initialize a project, Archon materializes a "System of Record" into your workspace root:

MCP Installation

Connect Archon directly to your AI agents (like Claude Desktop) using the Model Context Protocol. This allows your agent to perform architectural analysis, validation, and materialization directly within your workspace.

Claude Desktop Configuration

Add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "archonspecs-mcp": {
      "command": "archonspecs",
      "args": [
        "https://archonspecs.dev/mcp/sse?apiKey=<TOKEN>"
      ]
    }
  }
}

Prerequisites

• Node.js v18+: Required to run the MCP client bridge.
• Archon API Key: A valid sk_li token from your Archon dashboard.
• Global CLI: Ensure you have installed the CLI via npm install -g archon-mcp-client.

Future Roadmap

Archon is evolving from a code generator into a full-scale Architectural Operating System. Our mission is to eliminate the gap between high-level intent and production-grade reality.