# notrambi/python-bruteforce-password-cracking architecture

> Architecture diagram of the GitHub repository notrambi/python-bruteforce-password-cracking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/notrambi/python-bruteforce-password-cracking
- Repository: https://github.com/notrambi/python-bruteforce-password-cracking

## Overview

##### Project type and purpose
- This is a small, open-source Python tool for brute-forcing passwords or PINs.
- It consists of two standalone scripts: one for numeric PINs and one for alphanumeric/symbolic passwords.
- Its purpose is educational: generate every combination up to a given length and compare against a target value.

##### File structure
- Top-level files:
- Alphanumeric Password bruteforce.py
- Numeric Password bruteforce.py
- README.md, LICENSE
- There are no subdirectories or dependencies beyond the standard Python runtime.
- Both scripts likely share the same high-level flow: read parameters, generate guesses, compare guess to target, report success.

##### README for additional insights
- Describes exponential time complexity.
- Encourages integration into other codebases—signaling an extensibility point.

##### Main components
a. User Interface (CLI module in each script)
- Parses command-line args: target password/PIN, character set options, max length.
b. Charset Generator
- Depending on script: digits only vs. alphanumeric+symbols.
- Produces an iterator/generator of candidate strings.
c. Brute Force Engine
- Drives the nested loops or recursive generation across lengths.
- Requests next candidate from Charset Generator.
d. Password Checker
- Compares each candidate to the user-supplied target.
- Stops iteration on match.
e. Output/Logger
- Prints found password, statistics (time elapsed, attempts).
- Could be extended to write to file or external monitoring.

##### Relationships & interactions
- CLI → configures Charset Generator & Brute Force Engine
- Brute Force Engine ↔ Charset Generator (iterates over guesses)
- Brute Force Engine → Password Checker → Output
- Optionally, Output → external log file or third-party integration

##### Architectural patterns & design principles
- Single-responsibility: each module (arg parsing, generation, checking, reporting) has one job.
- Stateless iteration: each guess is generated on demand, keeping memory use low.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% I/O Components
    CLI["CLI (arg parse)"]:::io
    Output["Output/Logger"]:::io
    ExternalIntegrator["External Integrator"]:::extension

    %% Extension Points Group
    subgraph "Extension Points"
        Generator["Charset Generator"]:::core
        Engine["Brute Force Engine"]:::core
    end

    %% Core Components
    Checker["Password Checker"]:::core

    %% Connections
    CLI -->|"configures"| Generator
    CLI -->|"configures"| Engine
    Generator -->|"next_guess"| Engine
    Engine -->|"guess"| Checker
    Checker -->|"comparison_result"| Engine
    Engine -->|"on_match"| Output
    Output -->|"optional logging"| ExternalIntegrator

    %% Notes
    NoteExp[/"Exponential time complexity\nStops on first match"/]:::note
    NoteExp --> Generator
    NoteExp --> Engine

    %% Click Events
    click CLI "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Alphanumeric Password bruteforce.py"
    click CLI "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Numeric Password bruteforce.py"
    click Generator "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Alphanumeric Password bruteforce.py"
    click Generator "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Numeric Password bruteforce.py"
    click Engine "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Alphanumeric Password bruteforce.py"
    click Engine "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Numeric Password bruteforce.py"
    click Checker "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Alphanumeric Password bruteforce.py"
    click Checker "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Numeric Password bruteforce.py"
    click Output "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Alphanumeric Password bruteforce.py"
    click Output "https://github.com/notrambi/python-bruteforce-password-cracking/blob/main/Numeric Password bruteforce.py"

    %% Styles
    classDef core fill:#cce5ff,stroke:#6699ff,color:#000;
    classDef io fill:#d4edda,stroke:#28a745,color:#000;
    classDef extension fill:#fff3cd,stroke:#ffcd39,color:#000;
    classDef note fill:#f8d7da,stroke:#f5c6cb,color:#000,stroke-dasharray: 5 5;
```
