# pana/nrm architecture

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

- Interactive diagram: https://gitdiagram.com/pana/nrm
- Repository: https://github.com/pana/nrm

## Overview

##### Project type and purpose
- This project (“nrm”) is a Node.js command-line application (CLI) for managing npm registries.
- Its main function is to let users list, switch, add, remove, and test npm registry configurations by manipulating local/global npm config files and performing HTTP requests to registry endpoints.

##### File structure
- Top-level files:
- package.json, pnpm-lock.yaml, tsconfig.json, biome.json: Node.js build & config files
- .github/workflows/*: CI pipelines (lint, test, release)
- .changeset/*, CHANGELOG.md, LICENSE: release management
- README.md: user documentation
- src/ directory (TypeScript):
- index.ts: CLI entrypoint (parses arguments, dispatches commands)
- actions.ts: implementations of `ls`, `use`, `add`, `del`, `login`, etc.
- helpers.ts: utilities for file I/O, registry file parsing, HTTP requests, base64 encoding
- constants.ts: built-in registry definitions, default file locations
- types.ts: TypeScript interfaces for registry objects, CLI options
- tests/ directory:
- cli.test.ts, helpers.test.ts: unit tests for core logic
- setup.ts: test harness setup

##### README for additional insights
- Confirms supported commands and flags
- Points out minimum Node.js v18 requirement
- Indicates external dependencies: Node’s fs, child_process (for `npm publish`), HTTP client

a. Main components:
1. CLI Parser (index.ts + commander-like argument parser)
2. Command Handlers (actions.ts)
3. Core Utilities (helpers.ts + constants.ts + types.ts)
4. File System (npm config files: ~/.npmrc, project .npmrc)
5. HTTP Client (for `test`, `login`, and remote registry interactions)
6. External Registries (npm, yarn, taobao, etc)
7. Test Harness (vitest, tests/*)
b. Relationships & interactions:
- User invokes `nrm <command>` → CLI Parser
- CLI Parser calls appropriate Command Handler
- Command Handler uses Core Utilities to read/write config files, perform HTTP requests, or spawn npm child processes
- For `test`, HTTP Client measures response times from External Registries
- For `publish`, actions may spawn `npm publish` or proxy via child_process
- Tests drive the Command Handlers and Core Utilities in isolation
c. Architectural patterns & principles:
- Modular separation: CLI entry, business logic (actions), utilities
- Single-process CLI application
- Pure functions and side-effect isolation in helpers for testability
- Configuration-driven (constants.ts defines registry list)
d. Key technologies & libraries:
- Node.js, TypeScript
- Third-party: commander (or built-in option parser), axios/fetch for HTTP, cross-env for child_process
- Testing: Vitest

- Blue for application logic
- Green for utilities
- Gray for infrastructure (FS, HTTP, external services)
- Orange for tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User initiates CLI
    User["User"]:::application
    User -->|"invokes nrm"| CLI

    %% Application Logic Layer
    CLI["CLI Parser<br/>(index.ts)"]:::application
    click CLI "https://github.com/pana/nrm/blob/master/src/index.ts"

    subgraph "Command Handlers"
        direction TB
        Handler["Command Handlers<br/>(actions.ts)"]:::application
        click Handler "https://github.com/pana/nrm/blob/master/src/actions.ts"
    end

    %% Utilities Layer
    subgraph "Core Utilities"
        direction TB
        Helpers["File I/O & HTTP Helpers<br/>(helpers.ts)"]:::utility
        click Helpers "https://github.com/pana/nrm/blob/master/src/helpers.ts"
        Constants["Configuration & Registries Definitions<br/>(constants.ts)"]:::utility
        click Constants "https://github.com/pana/nrm/blob/master/src/constants.ts"
        Types["Type Definitions<br/>(types.ts)"]:::utility
        click Types "https://github.com/pana/nrm/blob/master/src/types.ts"
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        FS["File System<br/>(~/.npmrc, .npmrc)"]:::infrastructure
        HTTP["HTTP Client"]:::infrastructure
        click HTTP "https://github.com/pana/nrm/blob/master/src/helpers.ts"
        ExtRegs["External Registries<br/>(npm, yarn, taobao, etc)"]:::infrastructure
    end

    %% Testing
    TestHarness["Test Harness<br/>(tests/)"]:::test
    click TestHarness "https://github.com/pana/nrm/tree/master/tests/"

    %% Relationships
    CLI --> Handler
    Handler -->|"uses"| Helpers
    Handler -->|"reads constants/types"| Constants
    Handler -->|"reads constants/types"| Types
    Helpers ---|"reads/writes"| FS
    Helpers ---|"executes HTTP request"| HTTP
    HTTP ---|"pings"| ExtRegs
    TestHarness ---|"tests commands"| Handler
    TestHarness ---|"tests utilities"| Helpers

    %% Styles
    classDef application fill:#D0E6FF,stroke:#0366D6,stroke-width:1px;
    classDef utility fill:#E6FFEA,stroke:#22863A,stroke-width:1px;
    classDef infrastructure fill:#F0F0F0,stroke:#6A737D,stroke-width:1px;
    classDef test fill:#FFF5D1,stroke:#DBAB09,stroke-width:1px;
```
