# horosheff/aura-designer architecture

> Architecture diagram of the GitHub repository horosheff/aura-designer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/horosheff/aura-designer
- Repository: https://github.com/horosheff/aura-designer

## Overview

#### Purpose and Entry Points
Aura Designer is an installable AI sub-agent plus Python CLI for turning a URL, screenshot, image, or idea into a design contract and responsive HTML page. IDE-native entry points are the agent definitions for Cursor, Claude Code, and Codex: `.cursor/agents/aura-designer.md`, `.claude/agents/aura-designer.md`, `.codex/agents/aura-designer.md`. CLI entry point: `auradesign-agent/aura.py`.

#### Design Contract as System Boundary
`AURADESIGN.md` is the central handoff artifact: YAML tokens plus Markdown design rules governing palette, typography, layout, components, motion, accessibility, assets, and prohibitions. Its required format is specified by `auradesign-agent/AURADESIGN_SPEC.md`; a root example exists at `AURADESIGN.md`. Downstream generation and validation consume this contract rather than implicit style presets.

#### Source Intake and Analysis
The scanner ingests source URLs or images and extracts a design contract: `auradesign-agent/aura_scanner.py`. For source-driven work, analysis creates structured evidence and replication constraints through `auradesign-agent/aura_source_analyzer.py`, producing maps such as `AURA_SOURCE_MAP.json`, `AURA_COMPOSITION_LOCK.json`, and `AURA_COMPONENT_MAP.json`. This establishes the “copy-in-copy” boundary: preserve source composition, palette, imagery intent, and hero structure before proposing improvements.

#### Asset Gate and Brand Material
Asset handling is isolated in `auradesign-agent/aura_asset_manager.py`. It requires MCP-backed image generation via `user-mcp-kv/gpt-image-2` and background removal via `user-mcp-kv/recraft_remove_background`, explicitly avoiding fallback placeholder imagery. Supporting deliverables—including brand-kit image prompts and color rationale—are emitted by `auradesign-agent/aura_deliverables.py` into artifacts such as `AURA_ASSET_REGISTRY.json` and `AURA_BRAND_KIT_IMAGE_PROMPT.md`.

#### Two Page Production Paths
Standard contract-led HTML/CSS generation is implemented in `auradesign-agent/aura_generator.py`. Exact source replication follows the source-map-aware path in `auradesign-agent/aura_replicator.py`, consuming both the analysis artifacts and design contract to write the final `index.html` (for example, `auradesign-agent/index.html`). The CLI coordinates `scan`, `generate`, `analyze`, `replicate`, `deliverables`, `qa`, and end-to-end `pipeline` commands.

#### Quality Gates and Review Loop
Contract completeness is checked by `auradesign-agent/aura_linter.py`. Replicated HTML is assessed against source-map constraints by `auradesign-agent/aura_visual_qa.py`, producing visual-diff and QA artifacts such as `AURA_VISUAL_DIFF.md` and `AURA_VISUAL_QA.md`. A separate readonly reviewer agent, `.cursor/agents/aura-design-reviewer.md`, provides an additional visual review pass; equivalent definitions exist under `.claude/agents/` and `.codex/agents/`.

#### Runtime, Distribution, and Specialized Skills
The executable core is dependency-free Python 3. Installation copies sub-agent definitions into target IDE project scopes through `install.py`, `install.sh`, or `install.ps1`. Cursor-specific reusable skills constrain Cyrillic font selection and shape fidelity: `.cursor/skills/aura-cyrillic-google-fonts/SKILL.md` and `.cursor/skills/aura-shape-replication/SKILL.md`. Documentation of installation, agent topology, and MCP dependencies is under `docs/install.md`, `docs/agent-map.md`, and `docs/mcp-tools.md`.

Main entry points: [`auradesign-agent/aura.py`](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura.py) (Aura CLI), [`AURADESIGN.md`](https://github.com/horosheff/aura-designer/blob/main/AURADESIGN.md) (Design contract), [`auradesign-agent/aura_replicator.py`](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_replicator.py) (Source replicator), [`auradesign-agent/index.html`](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/index.html) (Final page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Distribution"]
  node_ide_agents["IDE designer agents<br/>agent definitions<br/>[aura-designer.md]"]
  node_cli{{"Aura CLI<br/>Python CLI<br/>[aura.py]"}}
  node_installer["Installer<br/>distribution scripts<br/>[install.py]"]
  node_cursor_skills["Cursor fidelity skills<br/>reusable skills<br/>[SKILL.md]"]
end

subgraph group_analysis["Intake &amp; Contract"]
  node_scanner["Source scanner<br/>intake<br/>[aura_scanner.py]"]
  node_source_analyzer["Source analyzer<br/>evidence analysis"]
  node_source_maps["Source maps<br/>analysis artifacts"]
  node_contract_spec["Contract specification<br/>format specification<br/>[AURADESIGN_SPEC.md]"]
  node_design_contract["Design contract<br/>handoff artifact<br/>[AURADESIGN.md]"]
end

subgraph group_production["Page Production"]
  node_asset_manager["Asset gate<br/>asset pipeline"]
  node_mcp_tools{{"MCP image tools<br/>external MCP"}}
  node_deliverables["Brand deliverables<br/>artifact producer"]
  node_generator["Contract HTML generator<br/>page generator<br/>[aura_generator.py]"]
  node_replicator["Source replicator<br/>page generator<br/>[aura_replicator.py]"]
  node_html_output["Final page<br/>HTML output<br/>[index.html]"]
end

subgraph group_quality["Quality &amp; Review"]
  node_linter["Contract linter<br/>quality gate<br/>[aura_linter.py]"]
  node_visual_qa["Visual QA<br/>quality gate<br/>[aura_visual_qa.py]"]
  node_qa_artifacts["Visual QA reports<br/>QA artifacts"]
  node_reviewer["Readonly design reviewer<br/>review agent"]
end

node_installer -->|"installs"| node_ide_agents
node_ide_agents -->|"invokes"| node_cli
node_cli -->|"scan"| node_scanner
node_scanner -->|"extracts"| node_design_contract
node_contract_spec -->|"defines format"| node_design_contract
node_cli -->|"analyze"| node_source_analyzer
node_source_analyzer -->|"produces"| node_source_maps
node_cli -->|"pipeline"| node_asset_manager
node_asset_manager -->|"uses"| node_mcp_tools
node_asset_manager -->|"supplies assets"| node_deliverables
node_cli -->|"generate"| node_generator
node_design_contract -->|"governs"| node_generator
node_generator -->|"writes"| node_html_output
node_cli -->|"replicate"| node_replicator
node_design_contract -->|"governs"| node_replicator
node_source_maps -->|"constrains"| node_replicator
node_replicator -->|"writes"| node_html_output
node_design_contract -->|"validated by"| node_linter
node_html_output -->|"assessed by"| node_visual_qa
node_source_maps -->|"QA constraints"| node_visual_qa
node_visual_qa -->|"produces"| node_qa_artifacts
node_reviewer -.->|"reviews"| node_html_output
node_cursor_skills -.->|"guides Cursor"| node_ide_agents

click node_ide_agents "https://github.com/horosheff/aura-designer/blob/main/.cursor/agents/aura-designer.md"
click node_cli "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura.py"
click node_installer "https://github.com/horosheff/aura-designer/blob/main/install.py"
click node_scanner "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_scanner.py"
click node_source_analyzer "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_source_analyzer.py"
click node_source_maps "https://github.com/horosheff/aura-designer/blob/main/AURA_SOURCE_MAP.json"
click node_contract_spec "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/AURADESIGN_SPEC.md"
click node_design_contract "https://github.com/horosheff/aura-designer/blob/main/AURADESIGN.md"
click node_asset_manager "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_asset_manager.py"
click node_deliverables "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_deliverables.py"
click node_generator "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_generator.py"
click node_replicator "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_replicator.py"
click node_html_output "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/index.html"
click node_linter "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_linter.py"
click node_visual_qa "https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_visual_qa.py"
click node_qa_artifacts "https://github.com/horosheff/aura-designer/blob/main/AURA_VISUAL_DIFF.md"
click node_reviewer "https://github.com/horosheff/aura-designer/blob/main/.cursor/agents/aura-design-reviewer.md"
click node_cursor_skills "https://github.com/horosheff/aura-designer/blob/main/.cursor/skills/aura-cyrillic-google-fonts/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ide_agents,node_cli,node_installer,node_cursor_skills toneBlue
class node_scanner,node_source_analyzer,node_source_maps,node_contract_spec,node_design_contract toneAmber
class node_asset_manager,node_mcp_tools,node_deliverables,node_generator,node_replicator,node_html_output toneMint
class node_linter,node_visual_qa,node_qa_artifacts,node_reviewer toneRose
```

## Components

### Entry & Distribution

- [IDE designer agents](https://github.com/horosheff/aura-designer/blob/main/.cursor/agents/aura-designer.md): agent definitions · Cursor, Claude Code, and Codex invoke the design sub-agent. · `.cursor/agents/aura-designer.md`
- [Aura CLI](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura.py): Python CLI · Coordinates scan, generate, analyze, replicate, deliverables, QA, and pipeline commands. · `auradesign-agent/aura.py`
- [Installer](https://github.com/horosheff/aura-designer/blob/main/install.py): distribution scripts · Copies agent definitions into target IDE project scopes. · `install.py`
- [Cursor fidelity skills](https://github.com/horosheff/aura-designer/blob/main/.cursor/skills/aura-cyrillic-google-fonts/SKILL.md): reusable skills · Constrains Cyrillic font choice and shape fidelity. · `.cursor/skills/aura-cyrillic-google-fonts/SKILL.md`

### Intake & Contract

- [Source scanner](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_scanner.py): intake · Ingests URLs and images to extract a design contract. · `auradesign-agent/aura_scanner.py`
- [Source analyzer](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_source_analyzer.py): evidence analysis · Builds structured source evidence and replication constraints. · `auradesign-agent/aura_source_analyzer.py`
- [Source maps](https://github.com/horosheff/aura-designer/blob/main/AURA_SOURCE_MAP.json): analysis artifacts · Composition locks and component maps preserve source intent. · `AURA_SOURCE_MAP.json`
- [Contract specification](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/AURADESIGN_SPEC.md): format specification · Defines the required YAML-plus-Markdown contract format. · `auradesign-agent/AURADESIGN_SPEC.md`
- [Design contract](https://github.com/horosheff/aura-designer/blob/main/AURADESIGN.md): handoff artifact · Tokens and rules for palette, type, layout, components, motion, accessibility, assets, and prohibitions. · `AURADESIGN.md`

### Page Production

- [Asset gate](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_asset_manager.py): asset pipeline · Requires MCP image generation and background removal without placeholders. · `auradesign-agent/aura_asset_manager.py`
- **MCP image tools**: external MCP · Provides gpt-image-2 and recraft_remove_background.
- [Brand deliverables](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_deliverables.py): artifact producer · Emits asset registry, image prompts, and color rationale. · `auradesign-agent/aura_deliverables.py`
- [Contract HTML generator](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_generator.py): page generator · Builds standard responsive HTML and CSS from the contract. · `auradesign-agent/aura_generator.py`
- [Source replicator](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_replicator.py): page generator · Uses contract and source maps for exact source-aware reproduction. · `auradesign-agent/aura_replicator.py`
- [Final page](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/index.html): HTML output · `auradesign-agent/index.html`

### Quality & Review

- [Contract linter](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_linter.py): quality gate · Checks contract completeness. · `auradesign-agent/aura_linter.py`
- [Visual QA](https://github.com/horosheff/aura-designer/blob/main/auradesign-agent/aura_visual_qa.py): quality gate · Assesses replicated HTML against source-map constraints. · `auradesign-agent/aura_visual_qa.py`
- [Visual QA reports](https://github.com/horosheff/aura-designer/blob/main/AURA_VISUAL_DIFF.md): QA artifacts · Visual-diff and visual-QA findings. · `AURA_VISUAL_DIFF.md`
- [Readonly design reviewer](https://github.com/horosheff/aura-designer/blob/main/.cursor/agents/aura-design-reviewer.md): review agent · Provides an additional visual review pass. · `.cursor/agents/aura-design-reviewer.md`

## Connections

- Installer → IDE designer agents: installs
- IDE designer agents → Aura CLI: invokes
- Aura CLI → Source scanner: scan
- Source scanner → Design contract: extracts
- Contract specification → Design contract: defines format
- Aura CLI → Source analyzer: analyze
- Source analyzer → Source maps: produces
- Aura CLI → Asset gate: pipeline
- Asset gate → MCP image tools: uses
- Asset gate → Brand deliverables: supplies assets
- Aura CLI → Contract HTML generator: generate
- Design contract → Contract HTML generator: governs
- Contract HTML generator → Final page: writes
- Aura CLI → Source replicator: replicate
- Design contract → Source replicator: governs
- Source maps → Source replicator: constrains
- Source replicator → Final page: writes
- Design contract → Contract linter: validated by
- Final page → Visual QA: assessed by
- Source maps → Visual QA: QA constraints
- Visual QA → Visual QA reports: produces
- Readonly design reviewer → Final page: reviews
- Cursor fidelity skills → IDE designer agents: guides Cursor