# manish-9245/hackpack architecture

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

- Interactive diagram: https://gitdiagram.com/manish-9245/hackpack
- Repository: https://github.com/manish-9245/hackpack

## Overview

#### Purpose and Entry Points
Hackpack is a deterministic project scaffolder: it composes a framework base, optional feature packs, and pages/CRUD scaffolds into deployable TypeScript or Python projects. The production CLI is Node/npm, launched by `cli/bin/hackpack.js` and dispatched through `cli/src/index.ts`; its command surface is implemented under `cli/src/commands/`. An experimental standalone Go implementation starts at `go-cli/cmd/hackpack/main.go`.

#### CLI Command Layer
Commands define user-facing lifecycle operations: create (`new`), layer a feature (`add`), generate CRUD (`page add`), reapply/update, manage registries, and deploy. The TypeScript implementations are `cli/src/commands/new.ts`, `cli/src/commands/add.ts`, and `cli/src/commands/pageAdd.ts`; deployment is isolated in `cli/src/commands/deploy.ts`. Commands orchestrate composition and filesystem effects rather than embedding framework-specific templates.

#### Registry and Template Contract
The registry is the core extension boundary: a registry supplies `bases/`, `features/`, and `pages/` folders, locally or from a Git source. Resolution and registry management live in `cli/src/registry.ts` and `cli/src/commands/registry.ts`. Each template pack declares metadata and compatibility through colocated `template.config.json`, for example `templates/bases/ts-nextjs/template.config.json` and `templates/features/db-d1-drizzle/template.config.json`.

#### Composition Pipeline
`new` selects a base, then overlays compatible features and requested pages into the target project. Composition and rendering are centralized in `cli/src/compose.ts` and `cli/src/generate.ts`; file operations are bounded in `cli/src/fsutil.ts`. The base establishes runtime, scripts, and deployment configuration; feature overlays add dependencies, environment requirements, source files, and integration wiring. Template material is data-driven Handlebars/filesystem content, notably `templates/bases/` and `templates/features/`.

#### Page and CRUD Generation
Prebuilt pages are applied from `templates/pages/`, with variants selected by installed capabilities such as auth: `templates/pages/login/variants/auth-better-auth/` and `templates/pages/dashboard/variants/`. Dynamic CRUD generation parses explicit fields or local natural-language descriptions, then renders stack-specific scaffold templates and inserts code at declared anchors. This stage is implemented by `cli/src/commands/pageAdd.ts`, `cli/src/nlp.ts`, and `templates/pages/_scaffold/`; it may update UI routes, API handlers, schemas, migrations, and dashboard navigation without arbitrary code execution.

#### Target Runtimes and External Services
Generated targets include Next.js, Vite/React, SvelteKit, Hono, FastAPI/Pyodide, and Nuxt/Svelte variants, defined in `templates/bases/`. Cloudflare Workers is the primary deployment target, configured per base through files such as `templates/bases/ts-nextjs/wrangler.jsonc.hbs`; D1 integrations are supplied by `templates/features/db-d1-drizzle/` and `templates/features/db-d1-sqlmodel/`. Optional packs integrate Better Auth/JWT and AI frameworks including LangChain, Mastra, Pydantic AI, and Vercel AI SDK.

#### Parallel Distributions and Marketing Site
The Go CLI mirrors the composition architecture through `go-cli/internal/compose/compose.go`, `go-cli/internal/generate/generate.go`, and `go-cli/internal/registry/registry.go`, but is explicitly experimental and lacks the Node CLI’s NLP capability. Separately, `landing/` is a Next.js/Vercel showcase application, entered at `landing/pages/index.tsx`; it is not part of the scaffolding runtime.

Main entry points: [`cli/src/compose.ts`](https://github.com/manish-9245/hackpack/blob/main/cli/src/compose.ts) (Composition engine), [`cli/src/registry.ts`](https://github.com/manish-9245/hackpack/blob/main/cli/src/registry.ts) (Registry resolution), [`cli/src/commands/new.ts`](https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/new.ts) (Project creation), [`cli/src/commands/add.ts`](https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/add.ts) (Feature layering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node_cli["Production Node CLI"]
  node_node_entry{{"CLI launcher<br/>Node entrypoint<br/>[hackpack.js]"}}
  node_node_dispatch["Command dispatcher<br/>TypeScript CLI<br/>[index.ts]"]
  node_commands["Lifecycle commands<br/>command layer"]
  node_new_command["Project creation<br/>new command<br/>[new.ts]"]
  node_add_command["Feature layering<br/>add command<br/>[add.ts]"]
  node_page_command["Pages and CRUD<br/>page add command<br/>[pageAdd.ts]"]
  node_deploy_command["Deployment<br/>deploy command<br/>[deploy.ts]"]
  node_registry["Registry resolution<br/>registry service<br/>[registry.ts]"]
  node_compose["Composition engine<br/>pipeline stage<br/>[compose.ts]"]
  node_generate["Renderer and writer<br/>pipeline stage<br/>[generate.ts]"]
  node_nlp["Field description parser<br/>NLP stage<br/>[nlp.ts]"]
end

subgraph group_templates["Registry Templates"]
  node_template_contract["Pack metadata<br/>template contract"]
  node_bases["Framework bases<br/>base templates"]
  node_features["Feature packs<br/>feature templates"]
  node_pages["Page packs and scaffolds<br/>page templates"]
end

subgraph group_go_cli["Experimental Go CLI"]
  node_go_entry{{"Go CLI entrypoint<br/>Go entrypoint<br/>[main.go]"}}
  node_go_compose["Go composition pipeline<br/>composition engine<br/>[compose.go]"]
end

subgraph group_outputs["Generated Projects"]
  node_generated_project["Generated application<br/>project output"]
  node_cloudflare{{"Cloudflare Workers<br/>deployment target<br/>[wrangler.jsonc.hbs]"}}
  node_d1[("Cloudflare D1<br/>database integration")]
end

node_landing["Marketing site<br/>Next.js showcase<br/>[index.tsx]"]

node_node_entry -->|"launches"| node_node_dispatch
node_node_dispatch -->|"dispatches"| node_commands
node_commands -->|"create"| node_new_command
node_commands -->|"add"| node_add_command
node_commands -->|"page add"| node_page_command
node_commands -->|"deploy"| node_deploy_command
node_new_command -->|"selects packs"| node_registry
node_add_command -->|"resolves feature"| node_registry
node_page_command -->|"parses descriptions"| node_nlp
node_page_command -->|"applies pages"| node_compose
node_registry -->|"validates"| node_template_contract
node_registry -->|"resolves"| node_bases
node_registry -->|"resolves"| node_features
node_registry -->|"resolves"| node_pages
node_new_command -->|"composes"| node_compose
node_add_command -->|"overlays"| node_compose
node_compose -->|"render plan"| node_generate
node_bases -->|"base layer"| node_compose
node_features -->|"feature overlays"| node_compose
node_pages -->|"pages and CRUD templates"| node_compose
node_generate -->|"writes"| node_generated_project
node_generated_project -->|"deploys to"| node_cloudflare
node_features -.->|"optional integration"| node_d1
node_go_entry -->|"runs"| node_go_compose
node_go_compose -.->|"experimental generation"| node_generated_project

click node_node_entry "https://github.com/manish-9245/hackpack/blob/main/cli/bin/hackpack.js"
click node_node_dispatch "https://github.com/manish-9245/hackpack/blob/main/cli/src/index.ts"
click node_new_command "https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/new.ts"
click node_add_command "https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/add.ts"
click node_page_command "https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/pageAdd.ts"
click node_deploy_command "https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/deploy.ts"
click node_registry "https://github.com/manish-9245/hackpack/blob/main/cli/src/registry.ts"
click node_compose "https://github.com/manish-9245/hackpack/blob/main/cli/src/compose.ts"
click node_generate "https://github.com/manish-9245/hackpack/blob/main/cli/src/generate.ts"
click node_nlp "https://github.com/manish-9245/hackpack/blob/main/cli/src/nlp.ts"
click node_template_contract "https://github.com/manish-9245/hackpack/blob/main/templates/bases/ts-nextjs/template.config.json"
click node_cloudflare "https://github.com/manish-9245/hackpack/blob/main/templates/bases/ts-nextjs/wrangler.jsonc.hbs"
click node_go_entry "https://github.com/manish-9245/hackpack/blob/main/go-cli/cmd/hackpack/main.go"
click node_go_compose "https://github.com/manish-9245/hackpack/blob/main/go-cli/internal/compose/compose.go"
click node_landing "https://github.com/manish-9245/hackpack/blob/main/landing/pages/index.tsx"

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_node_entry,node_node_dispatch,node_commands,node_new_command,node_add_command,node_page_command,node_deploy_command,node_registry,node_compose,node_generate,node_nlp toneBlue
class node_template_contract,node_bases,node_features,node_pages toneAmber
class node_go_entry,node_go_compose toneMint
class node_generated_project,node_cloudflare,node_d1 toneRose
class node_landing toneNeutral
```

## Components

### Production Node CLI

npm-distributed scaffolding runtime.

- [CLI launcher](https://github.com/manish-9245/hackpack/blob/main/cli/bin/hackpack.js): Node entrypoint · `cli/bin/hackpack.js`
- [Command dispatcher](https://github.com/manish-9245/hackpack/blob/main/cli/src/index.ts): TypeScript CLI · `cli/src/index.ts`
- **Lifecycle commands**: command layer · New, add, update, registry, and deploy operations.
- [Project creation](https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/new.ts): new command · `cli/src/commands/new.ts`
- [Feature layering](https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/add.ts): add command · `cli/src/commands/add.ts`
- [Pages and CRUD](https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/pageAdd.ts): page add command · `cli/src/commands/pageAdd.ts`
- [Deployment](https://github.com/manish-9245/hackpack/blob/main/cli/src/commands/deploy.ts): deploy command · `cli/src/commands/deploy.ts`
- [Registry resolution](https://github.com/manish-9245/hackpack/blob/main/cli/src/registry.ts): registry service · Resolves local or Git template registries. · `cli/src/registry.ts`
- [Composition engine](https://github.com/manish-9245/hackpack/blob/main/cli/src/compose.ts): pipeline stage · Overlays compatible bases, features, and pages. · `cli/src/compose.ts`
- [Renderer and writer](https://github.com/manish-9245/hackpack/blob/main/cli/src/generate.ts): pipeline stage · Renders Handlebars content and writes target files. · `cli/src/generate.ts`
- [Field description parser](https://github.com/manish-9245/hackpack/blob/main/cli/src/nlp.ts): NLP stage · Turns local descriptions into explicit CRUD fields. · `cli/src/nlp.ts`

### Registry Templates

Composable base, feature, and page packs.

- [Pack metadata](https://github.com/manish-9245/hackpack/blob/main/templates/bases/ts-nextjs/template.config.json): template contract · Declares pack metadata and compatibility. · `templates/bases/ts-nextjs/template.config.json`
- **Framework bases**: base templates · Establish runtime, scripts, and deployment configuration.
- **Feature packs**: feature templates · Add dependencies, integrations, and environment requirements.
- **Page packs and scaffolds**: page templates · Includes variants and stack-specific CRUD scaffolds.

### Experimental Go CLI

Standalone mirror without NLP generation.

- [Go CLI entrypoint](https://github.com/manish-9245/hackpack/blob/main/go-cli/cmd/hackpack/main.go): Go entrypoint · `go-cli/cmd/hackpack/main.go`
- [Go composition pipeline](https://github.com/manish-9245/hackpack/blob/main/go-cli/internal/compose/compose.go): composition engine · Experimental mirror of registry, compose, and generate stages. · `go-cli/internal/compose/compose.go`

### Generated Projects

Deployable target applications and services.

- **Generated application**: project output · Next.js, Vite, SvelteKit, Hono, FastAPI, Nuxt, or Svelte target.
- [Cloudflare Workers](https://github.com/manish-9245/hackpack/blob/main/templates/bases/ts-nextjs/wrangler.jsonc.hbs): deployment target · Primary deployment target configured by bases. · `templates/bases/ts-nextjs/wrangler.jsonc.hbs`
- **Cloudflare D1**: database integration · Optional Drizzle or SQLModel data layer.

### Other components

- [Marketing site](https://github.com/manish-9245/hackpack/blob/main/landing/pages/index.tsx): Next.js showcase · Separate Vercel application, not part of scaffolding. · `landing/pages/index.tsx`

## Connections

- CLI launcher → Command dispatcher: launches
- Command dispatcher → Lifecycle commands: dispatches
- Lifecycle commands → Project creation: create
- Lifecycle commands → Feature layering: add
- Lifecycle commands → Pages and CRUD: page add
- Lifecycle commands → Deployment: deploy
- Project creation → Registry resolution: selects packs
- Feature layering → Registry resolution: resolves feature
- Pages and CRUD → Field description parser: parses descriptions
- Pages and CRUD → Composition engine: applies pages
- Registry resolution → Pack metadata: validates
- Registry resolution → Framework bases: resolves
- Registry resolution → Feature packs: resolves
- Registry resolution → Page packs and scaffolds: resolves
- Project creation → Composition engine: composes
- Feature layering → Composition engine: overlays
- Composition engine → Renderer and writer: render plan
- Framework bases → Composition engine: base layer
- Feature packs → Composition engine: feature overlays
- Page packs and scaffolds → Composition engine: pages and CRUD templates
- Renderer and writer → Generated application: writes
- Generated application → Cloudflare Workers: deploys to
- Feature packs → Cloudflare D1: optional integration
- Go CLI entrypoint → Go composition pipeline: runs
- Go composition pipeline → Generated application: experimental generation