# narayanan-cs/miniature-git-client architecture

> Architecture diagram of the GitHub repository narayanan-cs/miniature-git-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/narayanan-cs/miniature-git-client
- Repository: https://github.com/narayanan-cs/miniature-git-client

## Overview

##### Project Type and Purpose
- This is a Node.js/TypeScript command‐line tool (“miniature-git-client”) that implements a tiny subset of Git commands (init, add, commit, diff, push, status).
- It provides local repository management (index, objects, commits) and remote interactions (push via Git host API).

##### File Structure Analysis
- Top level:
- Configuration & metadata: `package.json`, `tsconfig.json`, `jest.config.ts`
- Scripts: `scripts.json` (likely npm/yarn script bindings)
- Source code under `src/`
- Test suites under `tests/`
- `src/` contains:
- Command entry points: `ccgitinit.ts`, `ccgitadd.ts`, `ccgitcommit.ts`, `ccgitdiff.ts`, `ccgitpush.ts`, `ccgitstatus.ts`
- Core modules: `HashObject.ts`, `UpdateIndexAdd.ts`, `Commit.ts`, `FileType.ts`, `Utils.ts`, `convert.ts`, `init.ts`
- Types definitions in `src/types/`
- Tests validate each CLI command and core module behavior.

##### Architectural Components
a. CLI Interface
- Entry point that parses user arguments and dispatches to the appropriate command handler (`ccgit*.ts`).
b. Command Handlers
- One handler per Git command: init, add, commit, diff, push, status.
- They orchestrate core modules to fulfill the command semantics.
c. Core Modules (Engine)
- Index Manager (`UpdateIndexAdd.ts`): reads/writes staging area.
- Object Hasher (`HashObject.ts`): creates blob/tree/commit objects.
- Commit Manager (`Commit.ts`): assembles commit objects.
- Diff Engine (`ccgitdiff.ts` & `convert.ts`): wraps jsdiff-like functionality.
- FileType and Utils (`FileType.ts`, `Utils.ts`): low‐level file system operations and type definitions.
d. Local Storage
- The `.git`-style directory structure on disk (managed via Utils & types).
- Stores objects, index file, HEAD pointer.
e. Remote Service
- Git host API (GitHub, GitLab, etc.) called in `ccgitpush.ts` using HTTP with personal access token.

##### Relationships & Data Flow
1. User invokes `yarn ccgit<command> [args]` →
2. CLI Interface parses args →
3. Delegates to the matching Command Handler →
4. Handler calls Core Modules to:
- Read/write staging area (Index Manager)
- Hash files/blobs (Object Hasher)
- Construct commit objects (Commit Manager)
- Compute diffs (Diff Engine)
- Interact with the file system (Utils)
5. For `push`, after local operations, Handler sends HTTP requests to Remote Service.
6. Results and status are printed back to the console.

##### Architectural Patterns & Principles
- Modular design: one command = one entry module + shared core libraries.
- Single‐responsibility: each core file handles a specific Git concept (index, object, commit, diff).
- Layered architecture:
- Presentation layer (CLI parser + console I/O)
- Application layer (Command Handlers)
- Domain layer (Core Modules)
- Infrastructure layer (File system + HTTP client)

##### Technologies & Frameworks
- Node.js runtime with TypeScript
- Jest for testing
- jsdiff (wrapped or reimplemented in `ccgitdiff.ts`)
- Git host REST API for push

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    CLI["CLI Interface (Terminal)"]:::presentation

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        InitHandler["Init Handler"]:::application
        AddHandler["Add Handler"]:::application
        CommitHandler["Commit Handler"]:::application
        DiffHandler["Diff Handler"]:::application
        PushHandler["Push Handler"]:::application
        StatusHandler["Status Handler"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        IndexManager["Index Manager"]:::domain
        ObjectHasher["Object Hasher"]:::domain
        CommitManager["Commit Manager"]:::domain
        DiffEngine["Diff Engine"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        Utils["Utils (FS Operations)"]:::infra
        FileType["FileType Definitions"]:::infra
        Types["Type Definitions"]:::infra
    end

    %% Storage and Remote
    GitStorage[".git Directory"]:::storage
    Remote["Git Host API"]:::remote

    %% Connections: CLI to Handlers
    CLI -->|"yarn ccgit init"| InitHandler
    CLI -->|"yarn ccgit add"| AddHandler
    CLI -->|"yarn ccgit commit"| CommitHandler
    CLI -->|"yarn ccgit diff"| DiffHandler
    CLI -->|"yarn ccgit push"| PushHandler
    CLI -->|"yarn ccgit status"| StatusHandler

    %% Handlers to Domain Modules
    InitHandler -->|"initialize repo"| Utils
    InitHandler -->|"setup types"| Types
    InitHandler --> GitStorage

    AddHandler -->|"update index"| IndexManager
    AddHandler -->|"hash blob"| ObjectHasher

    CommitHandler -->|"hash tree/blob"| ObjectHasher
    CommitHandler -->|"create commit"| CommitManager

    DiffHandler -->|"compute diff"| DiffEngine

    StatusHandler -->|"status check"| IndexManager

    PushHandler -->|"prepare data"| CommitManager
    PushHandler -->|"HTTP POST /git/push"| Remote

    %% Domain to Infrastructure
    IndexManager -->|"fs read/write"| Utils
    ObjectHasher -->|"fs write"| Utils
    CommitManager -->|"fs write"| Utils
    DiffEngine -->|"fs read"| Utils

    %% Infrastructure Types
    Utils --> Types
    FileType --> Types

    %% Domain to Storage
    IndexManager -->|"write index"| GitStorage
    ObjectHasher -->|"write object"| GitStorage
    CommitManager -->|"write commit"| GitStorage

    %% Styles
    classDef presentation fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef application fill:#DDF0D8,stroke:#333,stroke-width:1px
    classDef domain fill:#FFF5BA,stroke:#333,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef storage fill:#CCCCFF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef remote fill:#FFD1DC,stroke:#333,stroke-width:1px

    %% Click Events
    click CLI "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/init.ts"
    click InitHandler "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/init.ts"
    click AddHandler "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/ccgitadd.ts"
    click CommitHandler "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/ccgitcommit.ts"
    click DiffHandler "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/ccgitdiff.ts"
    click DiffHandler "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/ccgitdiff-base.ts"
    click PushHandler "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/ccgitpush.ts"
    click StatusHandler "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/ccgitstatus.ts"
    click IndexManager "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/UpdateIndexAdd.ts"
    click ObjectHasher "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/HashObject.ts"
    click CommitManager "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/Commit.ts"
    click DiffEngine "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/convert.ts"
    click Utils "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/Utils.ts"
    click FileType "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/FileType.ts"
    click Types "https://github.com/narayanan-cs/miniature-git-client/blob/main/src/types/index.ts"
```
