# aaravkalia-88/hephaestus architecture

> Architecture diagram of the GitHub repository aaravkalia-88/hephaestus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaravkalia-88/hephaestus
- Repository: https://github.com/aaravkalia-88/hephaestus

## Overview

Hephaestus is a set of installable coding-agent skills for auditing and repairing existing frontend and backend projects. A user invokes the router or a fixer directly; the selected workflow applies its policies, scopes any edits, gathers verification evidence, and produces a report. The frontend mode also offers optional Taste design tools. The three report checkers are included as substantial runtime modules. Relationships for the skill workflows are based on the README; unsampled skill instructions and integration details are not independently verified here.

Main entry points: [`skills/hephaestus-frontend/SKILL.md`](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/SKILL.md) (Frontend Fixer), [`skills/hephaestus-backend/SKILL.md`](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/SKILL.md) (Backend Fixer), [`skills/hephaestus/SKILL.md`](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus/SKILL.md) (Hephaestus router), [`skills/hephaestus-frontend/policy/frontend-policy.json`](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/policy/frontend-policy.json) (Frontend policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Skill entrypoints"]
  node_router["Hephaestus router<br/>[SKILL.md]"]
  node_welcome["Welcome<br/>[README.md]"]
end

subgraph group_workflows["Fixer workflows"]
  node_frontend["Frontend Fixer<br/>[SKILL.md]"]
  node_backend["Backend Fixer<br/>[SKILL.md]"]
end

subgraph group_guidance["Policies and references"]
  node_frontend_policy["Frontend policy"]
  node_backend_policy["Backend policy"]
  node_backend_guide["Backend workflow<br/>[backend.md]"]
  node_taste_guide["Taste integration<br/>[taste.md]"]
  node_report_contract["Report contract<br/>[report.md]"]
  node_taste["Taste tools"]
end

subgraph group_reporting["Report validation"]
  node_core_checker["Core report checker<br/>[check-report.mjs]"]
  node_frontend_checker["Frontend report checker<br/>[check-report.mjs]"]
  node_backend_checker["Backend report checker<br/>[check-report.mjs]"]
end

node_user(("Project owner"))
node_agent(("Coding agent"))
node_target_project["Existing project"]
node_host_tools["Host tools"]

node_user -->|"requests audit or repair"| node_agent
node_agent -->|"invokes"| node_router
node_router -->|"presents"| node_welcome
node_router -->|"offers mode"| node_frontend
node_router -->|"offers mode"| node_backend
node_agent -->|"invokes directly"| node_frontend
node_agent -->|"invokes directly"| node_backend
node_frontend -->|"applies rules"| node_frontend_policy
node_backend -->|"applies guardrails"| node_backend_policy
node_backend -->|"follows workflow"| node_backend_guide
node_frontend -->|"consults integration"| node_taste_guide
node_taste_guide -->|"describes use"| node_taste
node_frontend -->|"uses contract"| node_report_contract
node_backend -->|"uses contract"| node_report_contract
node_agent -->|"audits and edits"| node_target_project
node_agent -->|"uses for verification"| node_host_tools
node_agent -->|"validates report"| node_core_checker
node_agent -->|"validates report"| node_frontend_checker
node_agent -->|"validates report"| node_backend_checker
node_core_checker -->|"loads policy"| node_frontend_policy
node_core_checker -->|"loads policy"| node_backend_policy
node_frontend_checker -->|"loads policy"| node_frontend_policy
node_frontend_checker -->|"loads policy"| node_backend_policy
node_backend_checker -->|"loads policy"| node_frontend_policy
node_backend_checker -->|"loads policy"| node_backend_policy

click node_router "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus/SKILL.md"
click node_welcome "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus/README.md"
click node_frontend "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/SKILL.md"
click node_backend "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/SKILL.md"
click node_frontend_policy "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/policy/frontend-policy.json"
click node_backend_policy "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/policy/backend-policy.json"
click node_backend_guide "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/references/backend.md"
click node_taste_guide "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/references/taste.md"
click node_report_contract "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/references/report.md"
click node_core_checker "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus/scripts/check-report.mjs"
click node_frontend_checker "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/scripts/check-report.mjs"
click node_backend_checker "https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/scripts/check-report.mjs"

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_router,node_welcome toneBlue
class node_frontend,node_backend toneAmber
class node_frontend_policy,node_backend_policy,node_backend_guide,node_taste_guide,node_report_contract,node_taste toneMint
class node_core_checker,node_frontend_checker,node_backend_checker toneRose
class node_user,node_agent,node_target_project,node_host_tools toneIndigo
```

## Components

### Skill entrypoints

- [Hephaestus router](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus/SKILL.md): `skills/hephaestus/SKILL.md`
- [Welcome](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus/README.md): `skills/hephaestus/README.md`

### Fixer workflows

- [Frontend Fixer](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/SKILL.md): `skills/hephaestus-frontend/SKILL.md`
- [Backend Fixer](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/SKILL.md): `skills/hephaestus-backend/SKILL.md`

### Policies and references

- [Frontend policy](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/policy/frontend-policy.json): `skills/hephaestus-frontend/policy/frontend-policy.json`
- [Backend policy](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/policy/backend-policy.json): `skills/hephaestus-backend/policy/backend-policy.json`
- [Backend workflow](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/references/backend.md): `skills/hephaestus-backend/references/backend.md`
- [Taste integration](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/references/taste.md): `skills/hephaestus-frontend/references/taste.md`
- [Report contract](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/references/report.md): `skills/hephaestus-frontend/references/report.md`
- **Taste tools**

### Report validation

- [Core report checker](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus/scripts/check-report.mjs): `skills/hephaestus/scripts/check-report.mjs`
- [Frontend report checker](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-frontend/scripts/check-report.mjs): `skills/hephaestus-frontend/scripts/check-report.mjs`
- [Backend report checker](https://github.com/aaravkalia-88/hephaestus/blob/main/skills/hephaestus-backend/scripts/check-report.mjs): `skills/hephaestus-backend/scripts/check-report.mjs`

### Other components

- **Project owner**
- **Coding agent**
- **Existing project**
- **Host tools**

## Connections

- Project owner → Coding agent: requests audit or repair (evidence: `README.md`)
- Coding agent → Hephaestus router: invokes (evidence: `README.md`)
- Hephaestus router → Welcome: presents (evidence: `README.md`)
- Hephaestus router → Frontend Fixer: offers mode (evidence: `README.md`)
- Hephaestus router → Backend Fixer: offers mode (evidence: `README.md`)
- Coding agent → Frontend Fixer: invokes directly (evidence: `README.md`)
- Coding agent → Backend Fixer: invokes directly (evidence: `README.md`)
- Frontend Fixer → Frontend policy: applies rules (evidence: `README.md`)
- Backend Fixer → Backend policy: applies guardrails (evidence: `README.md`)
- Backend Fixer → Backend workflow: follows workflow (evidence: `README.md`)
- Frontend Fixer → Taste integration: consults integration (evidence: `README.md`)
- Taste integration → Taste tools: describes use (evidence: `README.md`)
- Frontend Fixer → Report contract: uses contract (evidence: `README.md`)
- Backend Fixer → Report contract: uses contract (evidence: `README.md`)
- Coding agent → Existing project: audits and edits (evidence: `README.md`)
- Coding agent → Host tools: uses for verification (evidence: `README.md`)
- Coding agent → Core report checker: validates report (evidence: `README.md`)
- Coding agent → Frontend report checker: validates report (evidence: `README.md`)
- Coding agent → Backend report checker: validates report (evidence: `README.md`)
- Core report checker → Frontend policy: loads policy (evidence: `skills/hephaestus/scripts/check-report.mjs`)
- Core report checker → Backend policy: loads policy (evidence: `skills/hephaestus/scripts/check-report.mjs`)
- Frontend report checker → Frontend policy: loads policy (evidence: `skills/hephaestus-frontend/scripts/check-report.mjs`)
- Frontend report checker → Backend policy: loads policy (evidence: `skills/hephaestus-frontend/scripts/check-report.mjs`)
- Backend report checker → Frontend policy: loads policy (evidence: `skills/hephaestus-backend/scripts/check-report.mjs`)
- Backend report checker → Backend policy: loads policy (evidence: `skills/hephaestus-backend/scripts/check-report.mjs`)