# polarsource/polar-init architecture

> Architecture diagram of the GitHub repository polarsource/polar-init, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polarsource/polar-init
- Repository: https://github.com/polarsource/polar-init

## Overview

##### Project type and purpose
- This is a developer tooling project—a CLI scaffolding tool (named “polar-init”) that bootstraps payment checkouts, customer portals, and webhooks into Next.js TypeScript applications.
- The README confirms it: “Run `npx polar-init` in the root of your Next.js project to get started.”

##### File structure
- Top-level “bin/cli.js” is the executable entry point.
- “src/” contains the CLI logic, broken into modules:
- `cli.tsx` – main Ink/TSX CLI UI component
- `prompts/` – interactive question flow
- `install.ts` – orchestrates dependency installation
- `template.ts` & `src/package.ts` – template handling and package-management helpers
- `ui/` – reusable TSX screens (environment check, installation progress, success)
- “templates/next/…” holds the file scaffolds for checkout, portal, webhooks, plus route definitions.
- The “example/” folder illustrates a generated Next.js project for testing/demo.

##### README for additional insights
- Confirms the target host framework (Next.js + TypeScript).

a. Main components
- CLI Executable (bin/cli.js invoking src/cli.tsx)
- Prompt Engine (src/prompts)
- Template Engine (src/template.ts, “templates/next”)
- Installer Module (src/install.ts + npm registry)
- File System Adapter (copy/write files to user project)
- UI Renderer (Ink/React TSX under src/ui)
- Target Next.js Project (user’s codebase)

b. Relationships & interactions
1. User runs `npx polar-init` → Node loads bin/cli.js
2. CLI loads and renders src/cli.tsx (Ink)
3. CLI invokes Prompt Engine → user selects features (checkout, portal, webhook, env)
4. Template Engine picks corresponding subfolder under templates/next
5. File System Adapter copies scaffold files into the target Next.js project directory
6. Installer Module optionally runs `npm install` (via src/package.ts) against the user’s project, reaching out to the npm registry
7. UI Renderer displays progress & success screens

c. Architectural patterns/design principles
- Modular separation: prompts, UI, template logic, installer are distinct modules
- Unidirectional data flow: user input → prompt engine → template selection → file writes → install → final status
- Reusable template assets, decoupled from code logic
- CLI UI leveraging Ink (React TSX in the terminal) for consistent user experience

d. Key technologies/frameworks/libraries
- Node.js + TypeScript
- Ink (TSX-based CLI rendering)
- File-system utilities (copy, mkdir)
- NPM/PNPM for package installation
- Next.js conventions in template files

##### Elements
- User → CLI
- CLI → Prompt Engine → User
- Prompt Engine → Template Engine → File System
- Template Engine ↔ Templates folder
- Installer Module → npm Registry → Target Project
- UI Renderer → Terminal
- Blue rectangles for local modules (src/*)
- Orange parallelogram for CLI UI

##### Final advice
- Be very detailed: separate each logical unit (prompts vs. UI vs. template logic vs. installer).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    U["User"]:::external

    %% CLI Entrypoint
    CLI["CLI Entrypoint\n(bin/cli.js)"]:::local
    click CLI "https://github.com/polarsource/polar-init/blob/main/bin/cli.js"

    U -->|"runs npx polar-init"| CLI

    %% UI Renderer Subgraph
    subgraph "UI Renderer (Ink TSX)" 
        direction TB
        UI_Pre["Precheck Screen"]:::ui
        UI_Env["Environment Screen"]:::ui
        UI_Install["Install Progress"]:::ui
        UI_Success["Success Screen"]:::ui
    end
    click UI_Pre "https://github.com/polarsource/polar-init/blob/main/src/ui/precheck.tsx"
    click UI_Env "https://github.com/polarsource/polar-init/blob/main/src/ui/environment.tsx"
    click UI_Install "https://github.com/polarsource/polar-init/blob/main/src/ui/install.tsx"
    click UI_Success "https://github.com/polarsource/polar-init/blob/main/src/ui/success.tsx"

    CLI -->|"render UI"| UI_Pre
    CLI -->|"render UI"| UI_Env
    CLI -->|"render UI"| UI_Install
    CLI -->|"render UI"| UI_Success

    %% Prompt Engine
    subgraph "Prompt Engine" 
        direction TB
        PE_Dir["src/prompts/"]:::folder
        PE_Tmpl["template.ts"]:::local
    end
    click PE_Dir "https://github.com/polarsource/polar-init/tree/main/src/prompts/"
    click PE_Tmpl "https://github.com/polarsource/polar-init/blob/main/src/prompts/template.ts"

    CLI -->|"invoke prompts"| PE_Dir

    %% Template Engine
    TE["Template Engine\n(src/template.ts)"]:::local
    click TE "https://github.com/polarsource/polar-init/blob/main/src/template.ts"

    PE_Dir -->|"user selects features"| TE

    %% Templates Folder
    subgraph "Scaffold Templates" 
        direction TB
        TMP["templates/next/"]:::folder
        T_CO["checkout/route.ts"]:::folder
        T_PO["portal/route.ts"]:::folder
        T_WH["api/webhook/polar/route.ts"]:::folder
    end
    click TMP "https://github.com/polarsource/polar-init/tree/main/templates/next/"
    click T_CO "https://github.com/polarsource/polar-init/blob/main/templates/next/checkout/route.ts"
    click T_PO "https://github.com/polarsource/polar-init/blob/main/templates/next/portal/route.ts"
    click T_WH "https://github.com/polarsource/polar-init/blob/main/templates/next/api/webhook/polar/route.ts"

    TE -->|"select scaffold"| TMP
    TMP --> T_CO
    TMP --> T_PO
    TMP --> T_WH

    %% File System Adapter
    FS["File System Adapter\n(src/utils.ts)"]:::local
    click FS "https://github.com/polarsource/polar-init/blob/main/src/utils.ts"

    TE -->|"copy files"| FS
    FS -->|"writes files into"| TARGET

    %% Installer Module and Package Helpers
    IM["Installer Module\n(src/install.ts)"]:::local
    PH["Package Helpers\n(src/package.ts)"]:::local
    click IM "https://github.com/polarsource/polar-init/blob/main/src/install.ts"
    click PH "https://github.com/polarsource/polar-init/blob/main/src/package.ts"

    FS -->|"trigger install"| IM
    IM -->|"uses helpers"| PH
    PH -->|"fetch packages"| NPM

    %% NPM Registry
    NPM[(NPM Registry)]:::db

    NPM -->|"serve packages"| TARGET

    %% Target Next.js Project
    subgraph "Target Next.js Project" 
        direction TB
        TARGET["example/"]:::folder
        EX_PKG["package.json"]:::folder
        EX_NXT["next.config.ts"]:::folder
        EX_TS["tsconfig.json"]:::folder
        EX_PUB["public/"]:::folder
    end
    click TARGET "https://github.com/polarsource/polar-init/tree/main/example/"
    click EX_PKG "https://github.com/polarsource/polar-init/blob/main/example/package.json"
    click EX_NXT "https://github.com/polarsource/polar-init/blob/main/example/next.config.ts"
    click EX_TS "https://github.com/polarsource/polar-init/blob/main/example/tsconfig.json"
    click EX_PUB "https://github.com/polarsource/polar-init/tree/main/example/public/"

    %% Styling
    classDef local fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef folder fill:#D3D3D3,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2;
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px,shape:parallelogram;
    classDef db fill:#98FB98,stroke:#333,stroke-width:1px;
    classDef external fill:#EFEFEF,stroke:#333,stroke-width:1px,stroke-dasharray: 4 2;
```
