# codecatalysthadeed/forgepy architecture

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

- Interactive diagram: https://gitdiagram.com/codecatalysthadeed/forgepy
- Repository: https://github.com/codecatalysthadeed/forgepy

## Overview

ForgePy is a local, deterministic Python project generator. A developer runs `forgepy create`, selects a project type and options, and receives a staged project foundation; optional setup creates an environment, installs dependencies, and verifies the generated starter. The graph preserves the documented template families and generated-project capabilities, although their detailed internals are largely represented by the shared builder module. Relationships are included only where the excerpts or README support them; unsampled template internals are not expanded.

Main entry points: [`src/forgepy/templates/builders.py`](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py) (Template builders), [`src/forgepy/registry/templates.py`](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/registry/templates.py) (Template registry), [`src/forgepy/generator.py`](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/generator.py) (Generation orchestrator), [`src/forgepy/cli.py`](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/cli.py) (Create command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and selection"]
  node_cli["Create command<br/>[cli.py]"]
  node_config["Project options<br/>[config.py]"]
end

subgraph group_generation["Template generation"]
  node_registry["Template registry<br/>[templates.py]"]
  node_generator["Generation orchestrator<br/>[generator.py]"]
  node_models["Project specification<br/>[models.py]"]
  node_builders["Template builders<br/>[builders.py]"]
  node_shared["Shared project files<br/>[shared.py]"]
  node_writer["Safe staged writer<br/>[filesystem.py]"]
end

subgraph group_output["Generated foundations"]
  node_fastapi["FastAPI starter<br/>[builders.py]"]
  node_rag["RAG starter<br/>[builders.py]"]
  node_agent["AI agent starter<br/>[builders.py]"]
  node_langgraph["LangGraph starter<br/>[builders.py]"]
  node_ml["ML starter<br/>[builders.py]"]
  node_data_science["Data science starter<br/>[builders.py]"]
  node_python_cli["Python CLI starter<br/>[builders.py]"]
  node_project_guidance["Guidance and config<br/>[shared.py]"]
  node_project_files["Generated project files<br/>[filesystem.py]"]
end

subgraph group_setup["Optional setup"]
  node_setup["Environment setup<br/>[setup.py]"]
end

node_developer(("Developer"))

node_developer -->|"runs create"| node_cli
node_cli -->|"lists templates"| node_registry
node_registry -->|"registers builders"| node_builders
node_generator -->|"selects template"| node_registry
node_builders -->|"uses helpers"| node_shared
node_generator -->|"writes project"| node_writer
node_developer -->|"selects template"| node_fastapi
node_developer -->|"selects template"| node_rag
node_developer -->|"selects template"| node_agent
node_developer -->|"selects template"| node_langgraph
node_developer -->|"selects template"| node_ml
node_developer -->|"selects template"| node_data_science
node_developer -->|"selects template"| node_python_cli
node_builders -->|"generates support files"| node_project_guidance
node_writer -->|"commits staged files"| node_project_files
node_developer -->|"requests setup"| node_setup

click node_cli "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/cli.py"
click node_config "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/config.py"
click node_registry "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/registry/templates.py"
click node_generator "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/generator.py"
click node_models "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/models.py"
click node_builders "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py"
click node_shared "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/shared.py"
click node_writer "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/utils/filesystem.py"
click node_fastapi "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py"
click node_rag "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py"
click node_agent "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py"
click node_langgraph "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py"
click node_ml "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py"
click node_data_science "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py"
click node_python_cli "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py"
click node_project_guidance "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/shared.py"
click node_project_files "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/utils/filesystem.py"
click node_setup "https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/setup.py"

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_cli,node_config toneBlue
class node_registry,node_generator,node_models,node_builders,node_shared,node_writer toneAmber
class node_fastapi,node_rag,node_agent,node_langgraph,node_ml,node_data_science,node_python_cli,node_project_guidance,node_project_files toneMint
class node_setup toneRose
class node_developer toneIndigo
```

## Components

### CLI and selection

- [Create command](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/cli.py): `src/forgepy/cli.py`
- [Project options](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/config.py): `src/forgepy/config.py`

### Template generation

- [Template registry](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/registry/templates.py): `src/forgepy/registry/templates.py`
- [Generation orchestrator](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/generator.py): `src/forgepy/generator.py`
- [Project specification](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/models.py): `src/forgepy/models.py`
- [Template builders](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py): `src/forgepy/templates/builders.py`
- [Shared project files](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/shared.py): `src/forgepy/templates/shared.py`
- [Safe staged writer](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/utils/filesystem.py): `src/forgepy/utils/filesystem.py`

### Generated foundations

- [FastAPI starter](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py): `src/forgepy/templates/builders.py`
- [RAG starter](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py): `src/forgepy/templates/builders.py`
- [AI agent starter](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py): `src/forgepy/templates/builders.py`
- [LangGraph starter](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py): `src/forgepy/templates/builders.py`
- [ML starter](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py): `src/forgepy/templates/builders.py`
- [Data science starter](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py): `src/forgepy/templates/builders.py`
- [Python CLI starter](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/builders.py): `src/forgepy/templates/builders.py`
- [Guidance and config](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/templates/shared.py): `src/forgepy/templates/shared.py`
- [Generated project files](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/utils/filesystem.py): `src/forgepy/utils/filesystem.py`

### Optional setup

- [Environment setup](https://github.com/codecatalysthadeed/forgepy/blob/main/src/forgepy/setup.py): `src/forgepy/setup.py`

### Other components

- **Developer**

## Connections

- Developer → Create command: runs create (evidence: `README.md`)
- Create command → Template registry: lists templates (evidence: `src/forgepy/cli.py`)
- Template registry → Template builders: registers builders (evidence: `src/forgepy/registry/templates.py`)
- Generation orchestrator → Template registry: selects template (evidence: `src/forgepy/generator.py`)
- Template builders → Shared project files: uses helpers (evidence: `src/forgepy/templates/builders.py`)
- Generation orchestrator → Safe staged writer: writes project (evidence: `src/forgepy/generator.py`)
- Developer → FastAPI starter: selects template (evidence: `README.md`)
- Developer → RAG starter: selects template (evidence: `README.md`)
- Developer → AI agent starter: selects template (evidence: `README.md`)
- Developer → LangGraph starter: selects template (evidence: `README.md`)
- Developer → ML starter: selects template (evidence: `README.md`)
- Developer → Data science starter: selects template (evidence: `README.md`)
- Developer → Python CLI starter: selects template (evidence: `README.md`)
- Template builders → Guidance and config: generates support files (evidence: `README.md`)
- Safe staged writer → Generated project files: commits staged files (evidence: `src/forgepy/utils/filesystem.py`)
- Developer → Environment setup: requests setup (evidence: `README.md`)