# vinod-m-1/repo-health architecture

> Architecture diagram of the GitHub repository vinod-m-1/repo-health, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinod-m-1/repo-health
- Repository: https://github.com/vinod-m-1/repo-health

## Overview

##### What this project is (type + purpose)
**Repo-Health** is a **Node.js-based repository analysis tool** that:
- **Ingests a code repository** (likely via local path or remote Git URL),
- **Crawls files**, builds an **AST-based analysis summary** (metrics like cyclomatic complexity, LOC, depth),
- Runs **code smell detection** in two modes:
1) **Metadata/threshold checks** over precomputed metrics (fast pass),
2) **AST structural traversal** for smells that require syntax inspection (e.g., empty catch blocks),
- Exposes results either via a **web UI** (EJS view) and/or a **CLI/script entrypoint**.

This is not a “full-stack app” in the product sense; it’s primarily an **analysis engine** with a thin web presentation layer.

##### What the file tree tells you (architecture clues)
Top-level files imply a small, modular Node.js codebase:

- `server.js`
Likely an **Express** server hosting endpoints and rendering `views/home.ejs`.

- `views/home.ejs`
A server-rendered UI to submit a repo target and view results.

- `crawler.js`
A filesystem/repo walker: enumerates files, filters extensions, builds a list of JS/TS files, etc.

- `metricsEngine.js`
Computes metrics from AST or source (LOC, cyclomatic complexity, nesting depth). Produces the “Summary Object (analysis)” referenced in README.

- `codesmel.js`
Implements smell detection:
- **Threshold check**: iterates `analysis.Cyclo.funs` (precomputed per-function data) and emits events when thresholds exceeded.
- **Tree traversal check**: AST walk to find patterns like `CatchClause` with empty body.

- `main.js`
Likely the **orchestrator** tying together: clone/prepare repo → crawl → metrics → smells → output.

- `temp_repo/`
Strong hint there is a **“workspace” directory** where a target repo is cloned/unzipped for analysis.

- `package.json` / `package-lock.json`

The README explicitly describes two internal pipelines:

##### Metadata Analysis (Threshold Check)
- Input: `analysis` summary object (already computed)
- Loop: `analysis.Cyclo.funs`
- Compare: `loc`, `counter` (CC), `depth` against `THRESHOLDS`
- Output: “event objects” for bulky/complex functions

##### Tree Traversal (Structural Check)
- Input: AST (per file)
- Search: nodes with `type === 'CatchClause'`
- Condition: `node.body.body.length === 0`
- Output: smell event with `node.loc.start.line` (precise location)

These two checks are important enough to explicitly show as two separate “subsystems” inside the analysis engine.

##### Web Server Container (`server.js`)
- Responsibilities: HTTP endpoints, request parsing, calling the analysis orchestration, rendering results via EJS.
- Tech: Node.js + (likely) Express + EJS.

##### Analysis Engine Container (library-style modules)
- Responsibilities: crawl repo, parse/build AST, compute metrics, detect smells, produce report artifacts.
- Includes modules: `main.js`, `crawler.js`, `metricsEngine.js`, `codesmel.js`.

##### Workspace/Storage
- `temp_repo/` directory (ephemeral clone workspace)
- Possibly result JSON in-memory or on disk (even if not visible in tree, show the concept if it exists in code).

##### (Optional) Scheduler/Automation
- README says “daily code for my project”; if there’s a daily run (cron/CI), include a “Scheduler/CI” actor/container even if it’s external.

- Browser → Web Server (submit repo target)
- Web Server → Analysis Engine (invoke run)
- Analysis Engine → Workspace FS (`temp_repo/`) (clone/read)
- Analysis Engine → Web Server (return report object)
- Web Server → Browser (render `home.ejs` with results)

**Orchestrator**
- `main.js`
- Calls crawler
- Calls metrics engine
- Calls smell detector
- Aggregates final report

**Repo Acquisition / Preparation**
- If present in code: a “Repo Cloner” step that writes into `temp_repo/`
- It even if it’s just `git clone` via child process.

**Crawling / File Selection**
- `crawler.js`
- Input: repo root path
- Output: list of files to analyze

**Parsing + Metrics**
- `metricsEngine.js`
- Input: file contents (and/or AST)
- Output: `analysis` summary object

**Smell Detection**
- `codesmel.js`
Split it into two subcomponents (because README says they’re distinct):
1. **Threshold Rules Engine**
- Input: `analysis.Cyclo.funs`
- Output: smell events (bulky/complex functions)
2. **AST Structural Rules**
- Input: AST nodes + locations
- Output: smell events (e.g., empty catch blocks)

**Report Model**
- A conceptual component (even if it’s just a JS object):
- Aggregates events, counts, severities, file/line mapping

- `crawler.js` → list of paths → `metricsEngine.js`
- `metricsEngine.js` → `analysis` object → `codesmel.js` (threshold check)
- `metricsEngine.js` (or parser) → AST → `codesmel.js` (structural check)
- `codesmel.js` → smell events → `main.js` → report → `server.js` → `home.ejs`

##### What to explicitly include
Use these conventions:

##### Labels
- Name components using **file names + responsibility**:
- “`metricsEngine.js` — Metrics + Summary Object Builder”
- “`codesmel.js` — Smell Rules (Threshold + AST Traversal)”
- “`crawler.js` — Repo File Walker”
- “`server.js` — HTTP + EJS Rendering”

- **Control flow** (invokes/calls)
- **Data flow** (produces/consumes artifacts)
- “file paths[]”
- “AST”
- “analysis summary”
- “smell events[]”
- “report”

##### Practical “don’t overthink it” checklist (maximum fidelity fast)
To be very detailed without getting stuck:
##### two highlighted lanes inside `codesmel.js`
- “Threshold check (fast, uses summary)”
- “AST traversal (structural checks)”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% Context / Actors
  %% =======================
  Dev["Developer / CI Job"]:::actor
  Browser["Web Browser"]:::actor
  GitHost["Git Hosting (GitHub/GitLab)\n(optional remote URL)"]:::external
  LocalFS["Local Filesystem\n(local path input)"]:::external

  %% =======================
  %% System Boundary
  %% =======================
  subgraph "Repo-Health (Node.js Repository Analysis Tool)"
    direction TB

    %% -----------------------
    %% Web Presentation Layer
    %% -----------------------
    subgraph "Web Presentation"
      direction TB
      Server["server.js\nHTTP Endpoints + EJS Rendering"]:::web
      View["views/home.ejs\nRepo Submit + Results Page"]:::ui
    end

    %% -----------------------
    %% Analysis Engine (Modules)
    %% -----------------------
    subgraph "Analysis Engine (Pipeline)"
      direction TB

      Main["main.js\nOrchestrator (Pipeline Coordinator)"]:::engine

      subgraph "Repo Acquisition + Workspace"
        direction TB
        Workspace[("temp_repo/\nWorkspace / Temporary Repo Storage")]:::storage
        Acquire["Repo Acquisition\n(clone/fetch/unzip/prepare)"]:::engine
      end

      Crawler["crawler.js\nRepo File Walker (enumerate/filter)"]:::engine

      subgraph "Parsing + Metrics"
        direction TB
        Metrics["metricsEngine.js\nAST-based Metrics + Summary Builder"]:::engine
        AST["AST (per file)"]:::artifact
        Analysis["Summary Object\nanalysis"]:::artifact
      end

      subgraph "Smell Detection (codesmel.js)"
        direction TB
        Smells["codesmel.js\nSmell Rules Engine"]:::engine

        subgraph "Metadata / Threshold Checks (fast pass)"
          direction TB
          Thresholds["THRESHOLDS (Config)"]:::config
          ThresholdEngine["Threshold Rules\n(loc / cyclomatic / depth)"]:::engine
        end

        subgraph "AST Structural Traversal (syntax-aware)"
          direction TB
          ASTEngine["AST Traversal Rules\n(e.g., empty CatchClause)"]:::engine
          Loc["Location (file:line)\nnode.loc.start.line"]:::artifact
        end
      end

      Events["Smell Events[]"]:::artifact
      Report["Final Report\n(aggregated results)"]:::artifact
    end
  end

  %% =======================
  %% External interactions
  %% =======================
  Dev -->|"initiates_analysis"| Browser
  Browser -->|"submit_repo_target"| Server
  Server -->|"render_results"| Browser

  Dev -->|"run_via_CLI/script"| Main

  Server -->|"invoke_run(repo_target)"| Main

  %% Repo source options
  Main -->|"repo_target(url/path)"| Acquire
  Acquire -->|"clone/fetch"| GitHost
  Acquire -->|"read_local_repo"| LocalFS
  Acquire -->|"write_workspace"| Workspace

  %% Pipeline data flow
  Workspace -->|"repo_root"| Crawler
  Crawler -->|"file_paths[]"| Metrics
  Metrics -->|"parse_build"| AST
  Metrics -->|"compute_metrics"| Analysis

  %% Smell detection dual paths
  Analysis -->|"analysis.Cyclo.funs"| ThresholdEngine
  Thresholds -->|"config_values"| ThresholdEngine
  AST -->|"syntax_tree"| ASTEngine
  ASTEngine -->|"emit_location"| Loc

  ThresholdEngine -->|"emit_events"| Events
  ASTEngine -->|"emit_events"| Events

  %% Report assembly + UI
  Events -->|"aggregate"| Report
  Analysis -->|"include_summary"| Report
  Report -->|"return_report"| Main
  Main -->|"return_report"| Server
  Server -->|"render(view_model)"| View
  View -->|"HTML_response"| Browser

  %% Dependencies/config
  Package["package.json\nDependencies (Express/EJS/AST libs/etc.)"]:::config
  Package -.->|"runtime_deps"| Server
  Package -.->|"runtime_deps"| Main
  Package -.->|"runtime_deps"| Metrics
  Package -.->|"runtime_deps"| Smells

  %% =======================
  %% Click events (mapped components)
  %% =======================
  click Server "https://github.com/vinod-m-1/repo-health/blob/main/server.js"
  click View "https://github.com/vinod-m-1/repo-health/blob/main/views/home.ejs"
  click Main "https://github.com/vinod-m-1/repo-health/blob/main/main.js"
  click Crawler "https://github.com/vinod-m-1/repo-health/blob/main/crawler.js"
  click Metrics "https://github.com/vinod-m-1/repo-health/blob/main/metricsEngine.js"
  click Smells "https://github.com/vinod-m-1/repo-health/blob/main/codesmel.js"
  click Workspace "https://github.com/vinod-m-1/repo-health/tree/main/temp_repo/"
  click Package "https://github.com/vinod-m-1/repo-health/blob/main/package.json"

  %% =======================
  %% Styles
  %% =======================
  classDef actor fill:#E8F1FF,stroke:#2B5DB7,stroke-width:1.5px,color:#0B1F3A
  classDef external fill:#FFFFFF,stroke:#7A7A7A,stroke-width:1.5px,stroke-dasharray:5 4,color:#222
  classDef web fill:#E9F7EF,stroke:#1E8449,stroke-width:1.5px,color:#0B2E1A
  classDef ui fill:#FDF2E9,stroke:#B9770E,stroke-width:1.5px,color:#3A2406
  classDef engine fill:#F4ECF7,stroke:#6C3483,stroke-width:1.5px,color:#2B1034
  classDef storage fill:#EAF2F8,stroke:#1B4F72,stroke-width:1.5px,color:#0A2231
  classDef artifact fill:#FFF9E6,stroke:#B7950B,stroke-width:1.5px,color:#3A2F00
  classDef config fill:#FDEDEC,stroke:#922B21,stroke-width:1.5px,color:#3A0F0B
```
