# dropbox/zxcvbn architecture

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

- Interactive diagram: https://gitdiagram.com/dropbox/zxcvbn
- Repository: https://github.com/dropbox/zxcvbn

## Overview

##### Project type and purpose
- This is an open-source JavaScript library (zxcvbn) for password strength estimation.
- It ships as (a) a set of CoffeeScript modules in src/, (b) pre-built browser bundle in dist/, (c) data generation scripts in data-scripts/, and (d) demo and test harnesses.

##### File structure
- Top-level modules:
- src/           – CoffeeScript source of the core algorithm, broken into:
– adjacency_graphs.coffee  (keyboard‐pattern graphs)
– frequency_lists.coffee   (word, name, password frequency dictionaries)
– matching.coffee         (pattern matching engine)
– scoring.coffee          (guess‐count scoring logic)
– time_estimates.coffee   (translate guesses to crack‐time estimates)
– feedback.coffee         (verbal feedback generation)
– main.coffee             (entry point, orchestrates modules)
- data-scripts/  – Python and Coffee scripts that read raw data in data/ and output generated CoffeeScript data files.
- data/          – Raw text data (word lists, name lists, password lists).
- dist/          – Bundled, minified JavaScript (zxcvbn.js + map) for browser and Node use.
- demo/          – A self-contained HTML/JS demo showing zxcvbn usage with RequireJS/Mustache.
- test/          – Mocha tests for matching and scoring modules.
- build/config – manifest files (.travis.yml, .zuul.yml, package.json, bower.json) and CI integration.

##### Extract key architecture insights from README
- Build pipeline: CoffeeScript → browserify → uglifyify → exorcist → dist/zxcvbn.js
- Supports multiple module loaders (CommonJS, AMD, global).
- Data-scripts generate parts of the algorithm’s static dictionaries before build.

##### Main components
a. Core library modules
– Pattern matching (matching.coffee)
– Frequency data (frequency_lists.coffee)
– Adjacency graphs (adjacency_graphs.coffee)
– Scoring engine (scoring.coffee)
– Time estimation (time_estimates.coffee)
– Feedback generator (feedback.coffee)
– Orchestrator (main.coffee)
b. Data generation pipeline
– Raw data in data/ → data-scripts (Python/Coffee) → generated data modules → incorporated into src/
c. Build toolchain
– CoffeeScript compiler, Browserify, Uglifyify, Exorcist → dist/zxcvbn.js + map
d. Integration/consumption points
– Node/CommonJS
– AMD/RequireJS
– Global window.zxcvbn
e. Demo & Tests
– demo/index.html loads zxcvbn.js via RequireJS, presents UI
– test/ runs automated unit tests against modules

##### Relationships and interactions
- Data-scripts must run first to populate data modules.
- src modules import frequency and graph modules.
- main.coffee invokes matching → scoring → time_estimates → feedback.
- Build pipeline bundles all generated and source modules into single dist file.
- Consumers (browser, Node, AMD) load the dist or require individual modules.

##### Architectural patterns and principles
- Modular pipeline: each concern in its own module.
- Data generation separated from algorithm logic.
- Pluggable module loading (UMD pattern).
- Single responsibility within each CoffeeScript file.
- Immutable static dictionaries bundled at build time.

##### Essential elements to capture
- Offline data generation
- Modular code organization
- Build toolchain flow
- UMD compatibility
- Runtime algorithm pipeline and its subcomponents

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Offline Data Generation"
        rawData(("Raw Data")):::datastore
        dataScripts["Data Generation Scripts"]:::datascripts
        rawData --> dataScripts
        dataScripts --> genData["Generated Data Modules"]:::datastore
    end

    subgraph "Core Algorithm Modules"
        adjacency["Adjacency Graphs Module"]:::algorithm
        frequency["Frequency Data Module"]:::algorithm
        matching["Pattern Matching Module"]:::algorithm
        scoring["Scoring Engine Module"]:::algorithm
        timeEst["Time Estimation Module"]:::algorithm
        feedback["Feedback Generator Module"]:::algorithm
        orchestrator["Core Orchestrator (main.coffee)"]:::algorithm
    end

    genData --> adjacency
    genData --> frequency
    adjacency --> orchestrator
    frequency --> orchestrator
    orchestrator --> matching
    matching --> scoring
    scoring --> timeEst
    timeEst --> feedback

    subgraph "Build Pipeline"
        csComp["CoffeeScript Compiler"]:::build
        browserify["Browserify"]:::build
        uglify["Uglifyify"]:::build
        exorcist["Exorcist"]:::build
        csComp --> browserify --> uglify --> exorcist --> bundle
    end

    subgraph "Distribution"
        bundle["zxcvbn.js (bundle)"]:::output
        map["zxcvbn.js.map"]:::output
    end

    feedback --> csComp
    orchestrator --> csComp
    exorcist --> bundle
    bundle --> map

    subgraph "Consumers"
        node["Node/CommonJS"]:::consumer
        amd["AMD/RequireJS"]:::consumer
        global["Global window.zxcvbn"]:::consumer
    end

    bundle --> node
    bundle --> amd
    bundle --> global

    subgraph "Demo & Tests"
        demo["Demo Application"]:::demo
        tests["Automated Tests"]:::tests
    end

    global --> demo
    bundle --> tests

    click adjacency "https://github.com/dropbox/zxcvbn/blob/master/src/adjacency_graphs.coffee"
    click frequency "https://github.com/dropbox/zxcvbn/blob/master/src/frequency_lists.coffee"
    click matching "https://github.com/dropbox/zxcvbn/blob/master/src/matching.coffee"
    click scoring "https://github.com/dropbox/zxcvbn/blob/master/src/scoring.coffee"
    click timeEst "https://github.com/dropbox/zxcvbn/blob/master/src/time_estimates.coffee"
    click feedback "https://github.com/dropbox/zxcvbn/blob/master/src/feedback.coffee"
    click orchestrator "https://github.com/dropbox/zxcvbn/blob/master/src/main.coffee"
    click dataScripts "https://github.com/dropbox/zxcvbn/tree/master/data-scripts/"
    click rawData "https://github.com/dropbox/zxcvbn/tree/master/data/"
    click bundle "https://github.com/dropbox/zxcvbn/blob/master/dist/zxcvbn.js"
    click map "https://github.com/dropbox/zxcvbn/blob/master/dist/zxcvbn.js.map"
    click tests "https://github.com/dropbox/zxcvbn/blob/master/test/test-matching.coffee"

    classDef algorithm fill:#cfe2ff,stroke:#084298
    classDef datastore fill:#d1e7dd,stroke:#0f5132
    classDef datascripts fill:#d1e7dd,stroke:#0f5132
    classDef build fill:#ffe5d9,stroke:#d9480f
    classDef output fill:#fff3cd,stroke:#856404
    classDef consumer fill:#e2e3e5,stroke:#6c757d
    classDef demo fill:#f5e1ff,stroke:#6f42c1
    classDef tests fill:#f8d7da,stroke:#842029
```
