# debug-js/debug architecture

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

- Interactive diagram: https://gitdiagram.com/debug-js/debug
- Repository: https://github.com/debug-js/debug

## Overview

##### Project Type and Purpose
- This is a JavaScript library (an npm package) that provides a minimalist debugging utility for both Node.js and web browsers. It is _not_ a full-stack application but an open-source tool intended to be incorporated into other projects.

##### High-Level Architecture Analysis
- Entry Point: `src/index.js`
- Environment-specific implementations:
- `src/browser.js` – Browser behavior (uses `localStorage.debug`, `console.error`/`%c` styling)
- Public API: the `debug(...)` function factory that returns a namespaced logger instance
- Tests: `test.js`, `test.node.js` (verify behavior in each environment)
- Build & CI: `package.json`, `karma.conf.js` (browser tests), `.travis.yml`

##### Main Components
A. Public API Layer
- Component: debug factory (`index.js`)
- Inputs: namespace string, options overrides
- Outputs: debug function instance (bound `log` method)

B. Environment Detector
- Component: common logic that decides “Node” vs. “Browser” path
- Decision based on availability of `process` object & presence of `window`

C. Node.js Implementation
- Reads `process.env.DEBUG`
- Uses `util.format`, `util.inspect`, `console.error` writing to `stderr`
- Adds millisecond diff using internal timestamp state

D. Browser Implementation
- Reads/writes `localStorage.debug`
- Persists enabled namespaces across page reloads

E. Common Utilities
- Namespace parsing & wildcard matching
- Formatter definitions (`%o`, `%O`, `%s`, `%d`, `%j`, custom formatters)

F. Consumer Code
- Your application modules that `require('debug')('namespace')`
- Interact with your own Node servers or browser UIs

##### Relationships & Data Flows
- Consumer calls `debug('app:module')` → enters Public API
- API consults Environment Detector → routes to either Node or Browser implementation
- Implementation reads configuration (`DEBUG` env or `localStorage.debug`) → determines if enabled
- Formatted messages flow out to `stderr` or browser console
- Tests exercise this end-to-end chain

##### Architectural Patterns & Principles
- Strategy Pattern: separate Node vs. Browser “strategies” behind a common interface
- Factory Pattern: `debug(namespace)` produces a bound logger instance
- Single Responsibility: each module (`common.js`, `node.js`, `browser.js`) has a focused role
- Dependency Injection (optional): override `debug.log` on a per-namespace basis

- Clear component labels: e.g., “Debug Factory (index.js)”, “Node Strategy (node.js)”, “Browser Strategy (browser.js)”, “Common Utils”
- From Consumer → Debug Factory → Environment Detector → [Node Strategy] or [Browser Strategy]
- From Strategies → External Dependencies (env vars or localStorage)
- From Strategies → Console / stderr
- Blue for public API & detection
- Green for implementations
- Orange for utilities
- Gray for external systems

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Consumer Layer"
        Consumer["Consumer Code\n(require 'debug')"]
    end

    subgraph "API & Detection Layer"
        APIDebug["Debug Factory"]:::public
        Detector["Env Detector & Shared Logic"]:::public
    end

    subgraph "Implementation Layer"
        NodeStrategy["Node Strategy"]:::implementation
        BrowserStrategy["Browser Strategy"]:::implementation
    end

    subgraph "External Dependencies"
        ProcEnv["process.env.DEBUG"]:::external
        Util["util"]:::external
        SupportsColor["supports-color"]:::externalOpt
        LocalStorage["localStorage.debug"]:::external
        Console["console.error"]:::external
    end

    subgraph "Tests"
        TestAll["Test Suite (Env-Agnostic)"]:::external
        TestNode["Test Suite (Node.js Specific)"]:::external
    end

    subgraph "Config & CI"
        Package["npm package.json"]:::external
        Karma["Browser Tests\n(karma.conf.js)"]:::external
        Travis["CI Config\n(.travis.yml)"]:::external
    end

    Consumer -->|"calls"| APIDebug
    APIDebug -->|"consults"| Detector
    Detector -->|"if Node"| NodeStrategy
    Detector -->|"if Browser"| BrowserStrategy
    NodeStrategy -->|"reads"| ProcEnv
    NodeStrategy -->|"requires"| Util
    NodeStrategy -.->|"optional"| SupportsColor
    NodeStrategy -->|"writes to stderr via"| Console
    BrowserStrategy -->|"reads/writes"| LocalStorage
    BrowserStrategy -->|"logs via"| Console
    TestAll -->|"tests both"| NodeStrategy
    TestAll -->|"tests both"| BrowserStrategy
    TestNode -->|"tests Node"| NodeStrategy
    Package -->|"defines scripts"| TestAll
    Karma -->|"runs browser tests"| TestAll
    Travis -->|"CI pipeline"| Package

    click APIDebug "https://github.com/debug-js/debug/blob/master/src/index.js"
    click Detector "https://github.com/debug-js/debug/blob/master/src/common.js"
    click NodeStrategy "https://github.com/debug-js/debug/blob/master/src/node.js"
    click BrowserStrategy "https://github.com/debug-js/debug/blob/master/src/browser.js"
    click TestAll "https://github.com/debug-js/debug/blob/master/test.js"
    click TestNode "https://github.com/debug-js/debug/blob/master/test.node.js"
    click Package "https://github.com/debug-js/debug/blob/master/package.json"
    click Karma "https://github.com/debug-js/debug/blob/master/karma.conf.js"
    click Travis "https://github.com/debug-js/debug/blob/master/.travis.yml"

    classDef public fill:#ccf,stroke:#333,stroke-width:1px
    classDef implementation fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-width:1px
    classDef externalOpt fill:#eee,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
