How dropbox/zxcvbn works
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