# kanukuntla-r/forge architecture

> Architecture diagram of the GitHub repository kanukuntla-r/forge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kanukuntla-r/forge
- Repository: https://github.com/kanukuntla-r/forge

## Overview

forge is a project-scaffolding and codebase-understanding CLI. Users select a blueprint, supply variables, and generate a project; they can extend an existing project, then analyze and visualize its wiring in a live dashboard. The graph preserves the documented multi-language, cross-language, and database-analysis capabilities, plus batch rendering. Some subsystem links are documented in the README rather than shown in sampled implementation excerpts; those links cite the README, and unsampled internals are represented at their exact enclosing directory paths.

Main entry points: [`internal/analyzer/pipeline.go`](https://github.com/kanukuntla-r/forge/blob/main/internal/analyzer/pipeline.go) (Analysis pipeline), [`cmd/forge/main.go`](https://github.com/kanukuntla-r/forge/blob/main/cmd/forge/main.go) (CLI entry), [`internal/dashboard/server.go`](https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/server.go) (Dashboard server), [`internal/cli/new.go`](https://github.com/kanukuntla-r/forge/blob/main/internal/cli/new.go) (Create project)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_entry["CLI entry<br/>[main.go]"]
  node_new["Create project<br/>[new.go]"]
  node_add["Add extension<br/>[add.go]"]
  node_analyze_cli["Analyze command<br/>[analyze.go]"]
  node_visualize["Visualize command<br/>[visualize.go]"]
  node_list["List blueprints<br/>[list.go]"]
  node_install["Install blueprint<br/>[install.go]"]
end

subgraph group_scaffold["Blueprint scaffolding"]
  node_registry["Blueprint registry<br/>[registry.go]"]
  node_blueprints["Blueprint catalog<br/>[embedded.go]"]
  node_manifest["Manifest parsing"]
  node_variables["Variable resolution<br/>[values.go]"]
  node_templates["Template rendering<br/>[walk.go]"]
  node_graph_emit["Knowledge graphs<br/>[emit.go]"]
  node_hooks["Post-create hooks<br/>[runner.go]"]
  node_project["Project detection<br/>[detect.go]"]
end

subgraph group_analysis["Project analysis"]
  node_analyzer["Analysis pipeline<br/>[pipeline.go]"]
  node_ts_parser["TypeScript parsing"]
  node_py_parser["Python parsing"]
  node_frameworks["Framework analysis"]
  node_cross_match["Route matching<br/>[cross_framework.go]"]
  node_database[("Database detection<br/>[database.go]")]
end

subgraph group_dashboard["Dashboard and rendering"]
  node_dashboard_server["Dashboard server<br/>[server.go]"]
  node_watcher["Live file watcher<br/>[watcher.go]"]
  node_websocket["Update channel<br/>[websocket.go]"]
  node_dashboard_ui["Dashboard UI<br/>[app.js]"]
  node_batch["Batch rendering<br/>[batch.go]"]
  node_pages["Page rendering<br/>[pages.go]"]
end

node_user(("Developer"))
node_project_files["Project source"]
node_browser(("Browser"))
node_external_blueprint["Git blueprint"]

node_user -->|"runs command"| node_entry
node_entry -.->|"dispatches"| node_new
node_entry -.->|"dispatches"| node_add
node_entry -.->|"dispatches"| node_analyze_cli
node_entry -.->|"dispatches"| node_visualize
node_entry -.->|"dispatches"| node_list
node_entry -.->|"dispatches"| node_install
node_new -->|"looks up"| node_registry
node_new -->|"resolves inputs"| node_variables
node_new -->|"writes project"| node_templates
node_new -->|"emits graph"| node_graph_emit
node_new -->|"runs hooks"| node_hooks
node_add -->|"detects project"| node_project
node_add -->|"looks up"| node_registry
node_add -->|"resolves inputs"| node_variables
node_add -->|"writes extension"| node_templates
node_add -->|"merges graph"| node_graph_emit
node_registry -->|"loads embedded"| node_blueprints
node_blueprints -->|"parses manifests"| node_manifest
node_registry -->|"parses installed"| node_manifest
node_variables -->|"reads definitions"| node_manifest
node_install -->|"installs from Git"| node_external_blueprint
node_analyze_cli -->|"analyzes project"| node_analyzer
node_visualize -->|"analyzes project"| node_analyzer
node_project_files -->|"supplies source"| node_analyzer
node_analyzer -->|"parses TypeScript"| node_ts_parser
node_analyzer -->|"parses Python"| node_py_parser
node_analyzer -->|"detects frameworks"| node_frameworks
node_analyzer -->|"matches routes"| node_cross_match
node_analyzer -->|"detects schema use"| node_database
node_visualize -->|"opens dashboard"| node_dashboard_server
node_dashboard_server -->|"reanalyzes changes"| node_analyzer
node_dashboard_server -->|"starts watcher"| node_watcher
node_watcher -->|"triggers analysis"| node_dashboard_server
node_dashboard_server -->|"serves updates"| node_websocket
node_dashboard_server -->|"serves interface"| node_dashboard_ui
node_browser -->|"opens dashboard"| node_dashboard_server
node_batch -->|"loads analysis"| node_analyzer
node_visualize -.->|"renders previews"| node_batch
node_batch -.->|"uses page renderer"| node_pages

click node_entry "https://github.com/kanukuntla-r/forge/blob/main/cmd/forge/main.go"
click node_new "https://github.com/kanukuntla-r/forge/blob/main/internal/cli/new.go"
click node_add "https://github.com/kanukuntla-r/forge/blob/main/internal/cli/add.go"
click node_analyze_cli "https://github.com/kanukuntla-r/forge/blob/main/internal/cli/analyze.go"
click node_visualize "https://github.com/kanukuntla-r/forge/blob/main/internal/cli/visualize.go"
click node_list "https://github.com/kanukuntla-r/forge/blob/main/internal/cli/list.go"
click node_install "https://github.com/kanukuntla-r/forge/blob/main/internal/cli/install.go"
click node_registry "https://github.com/kanukuntla-r/forge/blob/main/internal/blueprint/registry.go"
click node_blueprints "https://github.com/kanukuntla-r/forge/blob/main/internal/blueprint/embedded.go"
click node_manifest "https://github.com/kanukuntla-r/forge/tree/main/internal/manifest"
click node_variables "https://github.com/kanukuntla-r/forge/blob/main/internal/render/values.go"
click node_templates "https://github.com/kanukuntla-r/forge/blob/main/internal/render/walk.go"
click node_graph_emit "https://github.com/kanukuntla-r/forge/blob/main/internal/graph/emit.go"
click node_hooks "https://github.com/kanukuntla-r/forge/blob/main/internal/hooks/runner.go"
click node_project "https://github.com/kanukuntla-r/forge/blob/main/internal/project/detect.go"
click node_analyzer "https://github.com/kanukuntla-r/forge/blob/main/internal/analyzer/pipeline.go"
click node_ts_parser "https://github.com/kanukuntla-r/forge/tree/main/internal/analyzer/parser/typescript"
click node_py_parser "https://github.com/kanukuntla-r/forge/tree/main/internal/analyzer/parser/python"
click node_frameworks "https://github.com/kanukuntla-r/forge/tree/main/internal/analyzer"
click node_cross_match "https://github.com/kanukuntla-r/forge/blob/main/internal/analyzer/cross_framework.go"
click node_database "https://github.com/kanukuntla-r/forge/blob/main/internal/analyzer/database.go"
click node_dashboard_server "https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/server.go"
click node_watcher "https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/watcher.go"
click node_websocket "https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/websocket.go"
click node_dashboard_ui "https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/static/app.js"
click node_batch "https://github.com/kanukuntla-r/forge/blob/main/internal/renderer/batch.go"
click node_pages "https://github.com/kanukuntla-r/forge/blob/main/internal/renderer/pages.go"

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_entry,node_new,node_add,node_analyze_cli,node_visualize,node_list,node_install,node_browser toneBlue
class node_registry,node_blueprints,node_manifest,node_variables,node_templates,node_graph_emit,node_hooks,node_project toneAmber
class node_analyzer,node_ts_parser,node_py_parser,node_frameworks,node_cross_match,node_database toneMint
class node_dashboard_server,node_watcher,node_websocket,node_dashboard_ui,node_batch,node_pages toneRose
class node_user,node_project_files,node_external_blueprint toneIndigo
```

## Components

### CLI workflows

- [CLI entry](https://github.com/kanukuntla-r/forge/blob/main/cmd/forge/main.go): `cmd/forge/main.go`
- [Create project](https://github.com/kanukuntla-r/forge/blob/main/internal/cli/new.go): `internal/cli/new.go`
- [Add extension](https://github.com/kanukuntla-r/forge/blob/main/internal/cli/add.go): `internal/cli/add.go`
- [Analyze command](https://github.com/kanukuntla-r/forge/blob/main/internal/cli/analyze.go): `internal/cli/analyze.go`
- [Visualize command](https://github.com/kanukuntla-r/forge/blob/main/internal/cli/visualize.go): `internal/cli/visualize.go`
- [List blueprints](https://github.com/kanukuntla-r/forge/blob/main/internal/cli/list.go): `internal/cli/list.go`
- [Install blueprint](https://github.com/kanukuntla-r/forge/blob/main/internal/cli/install.go): `internal/cli/install.go`

### Blueprint scaffolding

- [Blueprint registry](https://github.com/kanukuntla-r/forge/blob/main/internal/blueprint/registry.go): `internal/blueprint/registry.go`
- [Blueprint catalog](https://github.com/kanukuntla-r/forge/blob/main/internal/blueprint/embedded.go): `internal/blueprint/embedded.go`
- [Manifest parsing](https://github.com/kanukuntla-r/forge/tree/main/internal/manifest): `internal/manifest`
- [Variable resolution](https://github.com/kanukuntla-r/forge/blob/main/internal/render/values.go): `internal/render/values.go`
- [Template rendering](https://github.com/kanukuntla-r/forge/blob/main/internal/render/walk.go): `internal/render/walk.go`
- [Knowledge graphs](https://github.com/kanukuntla-r/forge/blob/main/internal/graph/emit.go): `internal/graph/emit.go`
- [Post-create hooks](https://github.com/kanukuntla-r/forge/blob/main/internal/hooks/runner.go): `internal/hooks/runner.go`
- [Project detection](https://github.com/kanukuntla-r/forge/blob/main/internal/project/detect.go): `internal/project/detect.go`

### Project analysis

- [Analysis pipeline](https://github.com/kanukuntla-r/forge/blob/main/internal/analyzer/pipeline.go): `internal/analyzer/pipeline.go`
- [TypeScript parsing](https://github.com/kanukuntla-r/forge/tree/main/internal/analyzer/parser/typescript): `internal/analyzer/parser/typescript`
- [Python parsing](https://github.com/kanukuntla-r/forge/tree/main/internal/analyzer/parser/python): `internal/analyzer/parser/python`
- [Framework analysis](https://github.com/kanukuntla-r/forge/tree/main/internal/analyzer): `internal/analyzer`
- [Route matching](https://github.com/kanukuntla-r/forge/blob/main/internal/analyzer/cross_framework.go): `internal/analyzer/cross_framework.go`
- [Database detection](https://github.com/kanukuntla-r/forge/blob/main/internal/analyzer/database.go): `internal/analyzer/database.go`

### Dashboard and rendering

- [Dashboard server](https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/server.go): `internal/dashboard/server.go`
- [Live file watcher](https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/watcher.go): `internal/dashboard/watcher.go`
- [Update channel](https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/websocket.go): `internal/dashboard/websocket.go`
- [Dashboard UI](https://github.com/kanukuntla-r/forge/blob/main/internal/dashboard/static/app.js): `internal/dashboard/static/app.js`
- [Batch rendering](https://github.com/kanukuntla-r/forge/blob/main/internal/renderer/batch.go): `internal/renderer/batch.go`
- [Page rendering](https://github.com/kanukuntla-r/forge/blob/main/internal/renderer/pages.go): `internal/renderer/pages.go`

### Other components

- **Developer**
- **Project source**
- **Browser**
- **Git blueprint**

## Connections

- Developer → CLI entry: runs command
- CLI entry → Create project: dispatches
- CLI entry → Add extension: dispatches
- CLI entry → Analyze command: dispatches
- CLI entry → Visualize command: dispatches
- CLI entry → List blueprints: dispatches
- CLI entry → Install blueprint: dispatches
- Create project → Blueprint registry: looks up (evidence: `internal/cli/new.go`)
- Create project → Variable resolution: resolves inputs (evidence: `internal/cli/new.go`)
- Create project → Template rendering: writes project (evidence: `internal/cli/new.go`)
- Create project → Knowledge graphs: emits graph (evidence: `internal/cli/new.go`)
- Create project → Post-create hooks: runs hooks (evidence: `internal/cli/new.go`)
- Add extension → Project detection: detects project (evidence: `internal/cli/add.go`)
- Add extension → Blueprint registry: looks up (evidence: `internal/cli/add.go`)
- Add extension → Variable resolution: resolves inputs (evidence: `internal/cli/add.go`)
- Add extension → Template rendering: writes extension (evidence: `internal/cli/add.go`)
- Add extension → Knowledge graphs: merges graph (evidence: `internal/cli/add.go`)
- Blueprint registry → Blueprint catalog: loads embedded (evidence: `internal/blueprint/registry.go`)
- Blueprint catalog → Manifest parsing: parses manifests (evidence: `internal/blueprint/embedded.go`)
- Blueprint registry → Manifest parsing: parses installed (evidence: `internal/blueprint/registry.go`)
- Variable resolution → Manifest parsing: reads definitions (evidence: `internal/render/values.go`)
- Install blueprint → Git blueprint: installs from Git
- Analyze command → Analysis pipeline: analyzes project
- Visualize command → Analysis pipeline: analyzes project
- Project source → Analysis pipeline: supplies source
- Analysis pipeline → TypeScript parsing: parses TypeScript
- Analysis pipeline → Python parsing: parses Python
- Analysis pipeline → Framework analysis: detects frameworks
- Analysis pipeline → Route matching: matches routes
- Analysis pipeline → Database detection: detects schema use
- Visualize command → Dashboard server: opens dashboard
- Dashboard server → Analysis pipeline: reanalyzes changes (evidence: `internal/dashboard/server.go`)
- Dashboard server → Live file watcher: starts watcher (evidence: `internal/dashboard/server.go`)
- Live file watcher → Dashboard server: triggers analysis (evidence: `internal/dashboard/server.go`)
- Dashboard server → Update channel: serves updates (evidence: `internal/dashboard/server.go`)
- Dashboard server → Dashboard UI: serves interface (evidence: `internal/dashboard/server.go`)
- Browser → Dashboard server: opens dashboard (evidence: `internal/dashboard/server.go`)
- Batch rendering → Analysis pipeline: loads analysis (evidence: `internal/renderer/batch.go`)
- Visualize command → Batch rendering: renders previews
- Batch rendering → Page rendering: uses page renderer
