Documentation

Technical reference

Everything you need to define, generate, and govern architecture with HexaGen Monaco.

Quick Start

Manifest Schema

Architecture Patterns

Quick Start

HexaGen Monaco is a monorepo that generates monorepos. Clone, install, and build your own governance engine in under a minute.

git clone

command

Clone the monorepo: git clone git@github.com:martinkrakowski/hexagen-monaco.git

cd hexagen-monaco

command

Enter the project directory

corepack enable

command

Enable Yarn 4 via corepack

yarn install

command

Install all dependencies across all packages

yarn build

command

Build all 27 packages in parallel via Turborepo

yarn sync

command

Generate hexagonal boilerplate from manifest. Idempotent — safe to run twice.

yarn sync:dry

command

Preview changes without writing files

yarn sync:force

command

Overwrite non-generated files (hand-written code)

yarn lint

command

Run ESLint on all packages + architecture validation

yarn lint:arch

command

Validate manifest against boundary rules. Add to CI.

yarn typecheck

command

TypeScript type checking across all packages

Manifest Schema

The manifest at .architecture/manifest.yaml is the single source of truth for your system topology. It declares bounded contexts, ports, adapters, layer rules, and module types. Every generated file and governance rule derives from this file.

system

string

Project identifier used in generated package names and @hexagen/* path aliases.

scope

string

NPM scope for packages (e.g. @hexagen).

architecture

string

Architecture style: 'modular-monolith' (currently supported).

monorepo

object

Monorepo config: packageManager, workspaces, ESLint, TypeScript settings.

modules

list

Array of module declarations (see below).

The monorepo object configures Yarn 4, Turborepo, ESLint, and TypeScript. It defines workspaces, build rules, and path aliases for the entire project.

name

string

Module name in kebab-case. Used for directory and package naming.

type

string

One of "core" | "supporting" | "driver" | "shared-kernel". Governance strictness varies.

ports

list[string]

Declared port interfaces (e.g. ProjectGeneratorPort). Generates TS interfaces.

adapters

list[string]

Adapter implementations for declared ports.

entities

list[string]

Domain entities in this module.

use_cases

list[string]

Application use cases orchestrated by this module.

layers

list[string]

Layer stack override — e.g. ["domain", "application", "infrastructure"].

core

strict

No outbound dependencies. Only ports exposed. Innermost boundary.

supporting

moderate

May depend on core. Must use ports. Infrastructure implementations live here.

driver

module

UI adapters, controllers, entry points. Depends on all other types.

shared-kernel

shared

Types and utilities only. Can be imported by any module.

CLI Commands

HexaGen Monaco exposes a small, deterministic CLI surface. Every command is idempotent — running it twice produces the same result.

yarn sync

command

Read manifest → generate hexagonal boilerplate. Idempotent.

yarn build

command

Turborepo-parallelized build across all packages. Incremental.

yarn dev

command

Start development mode with hot reload for Web UI and TUI.

yarn test

command

Run Vitest across the monorepo. Supports --watch, --coverage.

yarn sync:dry

command

Preview changes without writing files. Shows diffs.

yarn sync:force

command

Overwrite non-generated files (hand-written code).

yarn sync:strict

command

Fail on linter warnings.

yarn lint

command

Run ESLint on all packages + architecture validation.

yarn lint:arch

command

Validate manifest against boundary rules. Add to CI pipelines.

yarn typecheck

command

TypeScript across all packages.

yarn validate

command

Run purity + boundary validation.

yarn format

command

Format all TypeScript, Markdown, and JSON via Prettier.

Project Structure

HexaGen Monaco has 27 packages across 3 workspace roots plus 1 tool. All governed by the single manifest.

apps/web

app

Next.js web UI with Monaco Editor + React Flow canvas. Main entry point.

apps/tui

app

Terminal UI built with Ink. Three-pane layout with navigation, rule engine, violation inspector.

apps/api-gateway

app

Express-based API gateway for generated projects.

project-configuration

package

Manifest parsing and system topology.

code-generation

package

Manifest compiler. Generates hexagonal boilerplate.

architectural-enforcement

package

Risk mitigation. Dependency linting + boundary validation.

core-domain

package

Domain entities, value objects, use cases.

sync

package

CLI for artifact generation. The yarn sync command.

governance

package

Prompt compilation, rule engine, layer constraints.

mcp-server

package

MCP server exposing arch tools over stdio. For AI agents.

persistence

package

Lifecycle engine. Tracks architectural evolution.

visualization

package

Interactive graph. Renders module→port→adapter mappings.

monaco-orchestration

package

AST-based patching. ts-morph with confidence scoring.

wizard-orchestration

package

UI engine. Intent → Use Case → Projection pipeline.

tools/arch-linter

tool

Architecture validation tool. Validates manifest against rules.

.architecture/invariants/

dir

Custom rules as TypeScript functions asserting constraints.

Terminal UI

The TUI (apps/tui) is a full-featured terminal dashboard built with Ink (React for CLIs). It provides keyboard-driven architecture management from the command line.

Navigation tree

pane

Module and port browser. Navigate bounded contexts.

Rule engine

pane

Active invariants and layer constraints.

Violation inspector

pane

Boundary breaches with contextual refactoring suggestions.

j / k

key

Navigate up/down in the current pane.

Tab

key

Switch between panes.

r

key

Route context to MCP server for AI-assisted refactoring.

u

key

Refresh / update the view.

q

key

Quit the TUI.

Filesystem watching keeps all three panes live. The dashboard updates when the manifest or dependency graph changes without manual refresh.

Web UI & Canvas

The Web UI (apps/web) provides a visual architecture canvas for navigating bounded contexts, ports, adapters, and dependency flows. Built with Next.js and React Flow.

Bounded context nodes

visual

Each module renders as a hexagonal node on the graph.

Port adapters

visual

Dependencies flow between contexts visualized as edges.

Drag & zoom

interactive

Pan and zoom the canvas to explore large architectures.

Detail panels

interactive

Click nodes to view port/adapter details.

The manifest can be edited directly in the browser via Monaco Editor with syntax highlighting and semantic validation.

Monaco Orchestration (packages/monaco-orchestration) uses ts-morph for semantic patching. Confidence scoring gates mutations based on structural certainty.

MCP Server

The MCP Server (packages/mcp-server) exposes architectural tools over stdio transport. AI agents like Claude Code, Copilot, or any MCP-compatible client can interact with the manifest programmatically.

audit

tool

Audit architecture boundaries and report violations.

scaffold

tool

Scaffold new bounded contexts, ports, or adapters.

diff

tool

Show manifest changes between commits.

governance read

tool

Query active invariants and layer constraints.

When the TUI detects a boundary violation, pressing 'r' routes the context to the MCP server for AI-assisted refactoring. The LLM is modeled behind a port (LLMProviderPort), making it swappable and testable.

The agentic-interaction bounded context treats AI as infrastructure behind a port. LLMProviderPort abstracts OpenAI, Anthropic, local WebLLM, or future providers without coupling domain code to a specific provider.

Governance Rules

Governance is enforced at build time, not post-deploy. Three complementary mechanisms catch architectural violations before they reach production.

ESLint Boundaries

linter

Import restriction rules prevent cross-boundary access. Configured per manifest.

ts-morph AST

analyzer

Structural analysis verifies generated hexagonal interfaces remain intact.

Manifest Invariants

validator

Custom rules in .architecture/invariants/ — TypeScript functions asserting constraints on the manifest itself.

core

strict

No outbound dependencies. Only declared ports exposed.

supporting

moderate

May depend on core modules. Must go through ports.

driver

module

Entry points. Can depend on all other types.

shared-kernel

shared

Types only. Importable by any module.

Add 'yarn lint:arch' to your CI pipeline. The architecture linter runs in ~500ms and catches boundary violations on every commit.

Architecture Patterns

Every module follows the ports-and-adapters pattern. Domain logic sits at the center with no framework dependencies. External systems connect through declared port interfaces.

domain

layer

Pure business logic, no I/O, no framework imports. Innermost ring.

application

layer

Use cases / orchestration. Depends on domain + port interfaces.

infrastructure

layer

Adapters — databases, HTTP clients, framework bindings. Implements ports.

Dependencies point inward only. Infrastructure → Application → Domain. Domain depends on nothing. Violations caught by yarn lint:arch.

Wizard Orchestration routes every user interaction through I→U→P: Intent (entry), Use Case (system action), Projection (UI render). Intent is the only entry point; projections are pure.

The LLM is modeled behind LLMProviderPort in agentic-interaction. This makes the inference layer swappable, testable, and incapable of leaking into domain logic.

Need more detail?

The full source code, examples, and advanced configuration options are available on GitHub.

Quick Start Guide View on GitHub