# edumudu/loctry architecture

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

- Interactive diagram: https://gitdiagram.com/edumudu/loctry
- Repository: https://github.com/edumudu/loctry

## Overview

##### Project Type and Purpose
- This is a Node.js monorepo (managed by Turborepo) that contains a single package: a CLI tool named “loctry.”
- Purpose: streamline local library testing by generating an “npm pack” tarball identical to what you’d publish, then installing that tarball into a local project to verify correct setup.

##### Top-Level Structure and Key Directories
- Root
- turbo.json – Turborepo config for task orchestration
- .github/workflows/publish.yml – CI/CD pipeline for package publishing
- .husky/* and commitlint.config.js – Git hooks and commit‐message validation
- packages/cli
- bin/index.mjs – CLI entry point (invoked via `npx loctry`)
- commands/*.mjs – individual command modules (info, install, list, publish, unpublish)
- utils/*.mjs – shared helpers (resolving workdir, pkg.json, file paths)
- config/*.mjs – static settings (agent definitions, path specs)
- package.json – CLI’s manifest and dependency list

##### Main Components
- Actor: Developer (CLI user)
- Component: loctry CLI
- Bin Loader
- Command Registry (info, install, list, publish, unpublish)
- Utility Layer (file resolution, pkg manifest parsing)
- Config Layer (agents, path rules)
- Subsystems & External Interfaces
- Node.js Runtime (spawn child processes)
- Local File System (read/write package.json, create/read tarball)
- Child Process “npm pack” (generates .tgz)
- Child Process “npm install <tarball>” (injects tarball into target project)
- NPM Registry (HTTP API for publish, unpublish, version listing)
- DevOps Pipeline
- Git Hooks (pre-commit, commit-msg)
- GitHub Actions (CI run, build, test, publish)

##### Relationships & Data Flow
- Developer → invokes `loctry` on CLI
- Bin Loader → resolves the requested command module
- Command → uses Utils to locate target workdir & pkg.json
- Command → spawns `npm pack` → produces tarball → stored on local FS
- Install/List/Info commands → read from tarball or registry via HTTP
- Publish/Unpublish commands → HTTP calls to NPM registry
- All commands report results back to the Developer on stdout

##### Architectural Patterns & Principles
- Modular Command Pattern: each command in its own file, registered in an index
- Separation of Concerns: bin (bootstrap), commands (business logic), utils (IO + path logic), config (static constants)
- Monorepo with Turborepo: atomic package management, caching, and parallel task execution
- GitOps & CI/CD: commit linting, pre-commit hooks, GitHub Actions publishing flow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Developer["Developer"]:::external

    %% CLI Package Boundary
    subgraph "packages/cli"
        direction TB
        Bin["Bin Loader"]:::core
        CmdReg["Command Registry (commands/index.mjs)"]:::core

        subgraph "Commands"
            direction TB
            Info["info.mjs"]:::core
            Install["install.mjs"]:::core
            List["list.mjs"]:::core
            Publish["publish.mjs"]:::core
            Unpublish["unpublish.mjs"]:::core
        end

        subgraph "Utils"
            direction TB
            WGPM["get-workdir-pkg-manager.mjs"]:::util
            RF["resolve-file.mjs"]:::util
            RPJ["resolve-pkg-json.mjs"]:::util
        end

        subgraph "Config"
            direction TB
            Agents["agents.mjs"]:::util
            Paths["paths.mjs"]:::util
        end

        Manifest["package.json"]:::core
    end

    %% External Services and FS
    NPMPack["Child Process: npm pack"]:::external
    NPMInstall["Child Process: npm install <tarball>"]:::external
    FS["Local File System (tarball)"]:::external
    Registry["NPM Registry (HTTP API)"]:::external

    %% DevOps
    subgraph "DevOps"
        direction TB
        GHooksPre[".husky/pre-commit"]:::devops
        GHooksMsg[".husky/commit-msg"]:::devops
        Commitlint["commitlint.config.js"]:::devops
        GHAction[".github/workflows/publish.yml"]:::devops
        Turbo["turbo.json"]:::devops
    end

    %% Connections
    Developer -->|npx loctry| Bin
    Bin --> CmdReg
    CmdReg --> Info
    CmdReg --> Install
    CmdReg --> List
    CmdReg --> Publish
    CmdReg --> Unpublish

    Info -->|uses| WGPM
    Info -->|uses| RF
    Info -->|uses| RPJ
    Install -->|spawn npm pack| NPMPack
    NPMPack -->|writes .tgz| FS
    Install -->|spawn npm install| NPMInstall
    List -->|reads .tgz| FS
    List -->|HTTP GET /versions| Registry
    Publish -->|HTTP POST /package| Registry
    Unpublish -->|HTTP DELETE /package| Registry

    Developer -->|pre-commit| GHooksPre
    Developer -->|commit-msg| GHooksMsg
    GHooksMsg -->|validate| Commitlint
    GHAction -->|runs tasks| Turbo
    Turbo -->|orchestrates| Bin

    %% Click Events
    click Turbo "https://github.com/edumudu/loctry/blob/main/turbo.json"
    click GHAction "https://github.com/edumudu/loctry/blob/main/.github/workflows/publish.yml"
    click GHooksPre "https://github.com/edumudu/loctry/tree/main/.husky/pre-commit"
    click GHooksMsg "https://github.com/edumudu/loctry/tree/main/.husky/commit-msg"
    click Commitlint "https://github.com/edumudu/loctry/blob/main/commitlint.config.js"
    click Developer "https://github.com/edumudu/loctry/blob/main/package.json"
    click CliDir "https://github.com/edumudu/loctry/tree/main/packages/cli"
    click Bin "https://github.com/edumudu/loctry/blob/main/packages/cli/bin/index.mjs"
    click CmdReg "https://github.com/edumudu/loctry/blob/main/packages/cli/commands/index.mjs"
    click Info "https://github.com/edumudu/loctry/blob/main/packages/cli/commands/info.mjs"
    click Install "https://github.com/edumudu/loctry/blob/main/packages/cli/commands/install.mjs"
    click List "https://github.com/edumudu/loctry/blob/main/packages/cli/commands/list.mjs"
    click Publish "https://github.com/edumudu/loctry/blob/main/packages/cli/commands/publish.mjs"
    click Unpublish "https://github.com/edumudu/loctry/blob/main/packages/cli/commands/unpublish.mjs"
    click WGPM "https://github.com/edumudu/loctry/blob/main/packages/cli/utils/get-workdir-pkg-manager.mjs"
    click RF "https://github.com/edumudu/loctry/blob/main/packages/cli/utils/resolve-file.mjs"
    click RPJ "https://github.com/edumudu/loctry/blob/main/packages/cli/utils/resolve-pkg-json.mjs"
    click Agents "https://github.com/edumudu/loctry/blob/main/packages/cli/config/agents.mjs"
    click Paths "https://github.com/edumudu/loctry/blob/main/packages/cli/config/paths.mjs"
    click Manifest "https://github.com/edumudu/loctry/blob/main/packages/cli/package.json"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,color:#000
    classDef util fill:#90EE90,stroke:#000,color:#000
    classDef external fill:#FFA500,stroke:#000,color:#000
    classDef devops fill:#D3D3D3,stroke:#000,color:#000
```
