# francisrox/password-strength-checker architecture

> Architecture diagram of the GitHub repository francisrox/password-strength-checker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/francisrox/password-strength-checker
- Repository: https://github.com/francisrox/password-strength-checker

## Overview

1. **Repository purpose**
   - This is a Chrome extension system for analyzing password strength in the browser and persisting credentials locally on the user’s machine.
   - The architecture is intentionally offline: there is no backend service, database, or cloud sync layer.

2. **Primary runtime boundaries**
   - The system spans three distinct runtimes:
     - **Chrome extension runtime** in the browser
     - **Python native host** running locally on the OS
     - **Local filesystem vault** where passwords are stored
   - The key security/architecture boundary is Chrome’s **Native Messaging** bridge between the extension and the Python process.

3. **Browser extension subsystem**
   - `password-checker-extension/` contains the user-facing browser components.
   - `manifest.json` wires together the extension entry points and permissions.
   - `contentScript.js` runs on web pages, detects password fields, and provides real-time analysis/UI feedback.
   - `background.js` acts as the extension’s coordinator for saving events and communicating with the native host.
   - `popup.html`, `popup.js`, and `styles.css` implement the extension popup and setup UI.

4. **Password analysis logic**
   - `utils/password_analyzer.js` is the local analysis engine used by the extension.
   - This is where password strength scoring, duplicate/reuse detection, and warning logic likely live.
   - Keeping this logic in the extension avoids any need to send password contents to external services.

5. **Form and page interaction flow**
   - The extension watches password inputs on arbitrary websites.
   - As the user types, the content script evaluates strength in real time and surfaces a visual warning/indicator on the page.
   - On form submission or password change, the extension prepares a record for local storage.

6. **Native messaging bridge**
   - The extension does not write to disk directly; instead it sends password data to the **background script**, which forwards it to the native host.
   - Native messaging is the central integration point that connects browser events to local file persistence.
   - This boundary is important for the diagram: browser-side code and filesystem-side code are separated by a process boundary and Chrome’s messaging protocol.

7. **Python native host subsystem**
   - `native-host/host.py` is the local service that receives messages from Chrome and writes/updates the vault.
   - `com.password_manager.host.json` is the native host registration manifest used by Chrome to locate and authorize the Python host.
   - `host.bat` and `register.bat` are Windows orchestration scripts for launching and registering the host.

8. **Local vault and storage model**
   - `vault/` is the persistence boundary for user data; the repo expects a local text-based password file inside it.
   - The README indicates a single file vault format (`passwords.txt`) with timestamped blocks including website URL, username, and password.
   - The design emphasizes local-only storage, duplicate prevention, and “smart updates” rather than a database schema.

9. **Setup and lifecycle scripts**
   - `INSTALL.bat` automates installation and host registration, making the environment reproducible on a new machine.
   - `CLEAN_FOR_SHARING.bat` is a privacy/ops tool that clears stored secrets before sharing the repo.
   - `check_all.bat`, `debug_native_host.bat`, and the README troubleshooting guides support operational diagnostics of the browser-to-host chain.

10. **Testing and manual verification**
   - `test-login.html`, `test_path.py`, and `test_vault.py` suggest lightweight validation of page detection, filesystem paths, and vault behavior.
   - These tests support the repo’s main risk areas: browser injection, native messaging setup, and write access to the local vault.

11. **Technology profile**
   - Front end: standard Chrome extension technologies, primarily JavaScript and HTML/CSS.
   - Host side: Python for the local native messaging process.
   - Platform tooling: Windows batch scripts are first-class citizens, so the repo is oriented toward Windows setup and execution.

12. **Most important architectural diagram**
   - A good diagram should show:
     - Web page password field
     - Content script injected into the page
     - Background script as the extension coordinator
     - Native messaging channel to the Python host
     - Python host writing to `vault/passwords.txt`
   - The diagram should also reflect that all analysis and storage remain local, with no external server dependencies.

Main entry points: [`password-checker-extension/contentScript.js`](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/contentScript.js) (Content Script), [`native-host/host.py`](https://github.com/francisrox/password-strength-checker/blob/main/native-host/host.py) (Host Process), [`password-checker-extension/manifest.json`](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/manifest.json) (Manifest), [`password-checker-extension/background.js`](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/background.js) (Background)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Page"]
  node_password_field["Password Field<br/>page input"]
end

subgraph group_ext["Chrome Extension"]
  node_content_script["Content Script<br/>extension script<br/>[contentScript.js]"]
  node_analyzer["Password Analyzer<br/>analysis engine"]
  node_background["Background<br/>extension coordinator<br/>[background.js]"]
  node_popup_ui["Popup UI<br/>extension ui<br/>[popup.html]"]
  node_popup_logic["Popup Logic<br/>ui script<br/>[popup.js]"]
  node_manifest["Manifest<br/>extension config<br/>[manifest.json]"]
end

subgraph group_host["Native Host"]
  node_native_bridge{{"Native Bridge<br/>chrome messaging"}}
  node_host_py["Host Process<br/>python service<br/>[host.py]"]
  node_host_manifest["Host Manifest<br/>native config"]
  node_host_batch["Host Batch<br/>launcher script<br/>[host.bat]"]
  node_register_batch["Register Batch<br/>installer script<br/>[register.bat]"]
end

subgraph group_vault["Local Vault"]
  node_passwords_txt["Passwords File<br/>vault file<br/>[.gitkeep]"]
end

subgraph group_ops["Setup & Diagnostics"]
  node_install_script["Install Script<br/>setup script<br/>[INSTALL.bat]"]
  node_clean_script["Clean Script<br/>ops script"]
  node_diagnostics["Diagnostics<br/>troubleshooting<br/>[DIAGNOSTIC.md]"]
  node_test_vault["Vault Test<br/>[test_vault.py]"]
end

node_password_field -->|"typed input"| node_content_script
node_content_script -->|"score password"| node_analyzer
node_content_script -->|"save event"| node_background
node_background -->|"native message"| node_native_bridge
node_native_bridge -->|"receive payload"| node_host_py
node_host_py -->|"write update"| node_passwords_txt
node_manifest -->|"injects"| node_content_script
node_manifest -->|"registers"| node_background
node_manifest -->|"opens"| node_popup_ui
node_popup_ui -->|"driven by"| node_popup_logic
node_host_manifest -->|"authorizes"| node_host_py
node_host_batch -->|"launches"| node_host_py
node_register_batch -->|"installs"| node_host_manifest
node_install_script -->|"orchestrates"| node_register_batch
node_clean_script -->|"clears"| node_passwords_txt
node_diagnostics -.->|"troubleshoots"| node_native_bridge
node_test_vault -.->|"verifies"| node_passwords_txt

click node_content_script "https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/contentScript.js"
click node_analyzer "https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/utils/password_analyzer.js"
click node_background "https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/background.js"
click node_popup_ui "https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/popup.html"
click node_popup_logic "https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/popup.js"
click node_manifest "https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/manifest.json"
click node_host_py "https://github.com/francisrox/password-strength-checker/blob/main/native-host/host.py"
click node_host_manifest "https://github.com/francisrox/password-strength-checker/blob/main/native-host/com.password_manager.host.json"
click node_host_batch "https://github.com/francisrox/password-strength-checker/blob/main/native-host/host.bat"
click node_register_batch "https://github.com/francisrox/password-strength-checker/blob/main/native-host/register.bat"
click node_passwords_txt "https://github.com/francisrox/password-strength-checker/blob/main/vault/.gitkeep"
click node_install_script "https://github.com/francisrox/password-strength-checker/blob/main/INSTALL.bat"
click node_clean_script "https://github.com/francisrox/password-strength-checker/blob/main/CLEAN_FOR_SHARING.bat"
click node_diagnostics "https://github.com/francisrox/password-strength-checker/blob/main/DIAGNOSTIC.md"
click node_test_vault "https://github.com/francisrox/password-strength-checker/blob/main/test_vault.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_password_field toneBlue
class node_content_script,node_analyzer,node_background,node_popup_ui,node_popup_logic,node_manifest toneAmber
class node_native_bridge,node_host_py,node_host_manifest,node_host_batch,node_register_batch toneMint
class node_passwords_txt toneRose
class node_install_script,node_clean_script,node_diagnostics,node_test_vault toneIndigo
```

## Components

### Web Page

Arbitrary websites where password fields are detected and analyzed.

- **Password Field**: page input · A password input on a visited website that triggers analysis and save flows.

### Chrome Extension

Browser-side runtime that analyzes password strength and coordinates saves.

- [Content Script](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/contentScript.js): extension script · Injected page script that watches inputs, evaluates strength, and shows feedback. · `password-checker-extension/contentScript.js`
- [Password Analyzer](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/utils/password_analyzer.js): analysis engine · Local scoring and reuse/warning logic used by the extension. · `password-checker-extension/utils/password_analyzer.js`
- [Background](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/background.js): extension coordinator · Extension background process that receives events and forwards save requests to the host. · `password-checker-extension/background.js`
- [Popup UI](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/popup.html): extension ui · Popup and setup interface for the user-facing extension controls. · `password-checker-extension/popup.html`
- [Popup Logic](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/popup.js): ui script · Script behind the popup and setup screens. · `password-checker-extension/popup.js`
- [Manifest](https://github.com/francisrox/password-strength-checker/blob/main/password-checker-extension/manifest.json): extension config · Declares extension entry points, permissions, and runtime wiring. · `password-checker-extension/manifest.json`

### Native Host

Local Python process reached through Chrome Native Messaging.

- **Native Bridge**: chrome messaging · The Chrome native messaging boundary between extension and local host.
- [Host Process](https://github.com/francisrox/password-strength-checker/blob/main/native-host/host.py): python service · Python native host that receives messages from Chrome and updates storage. · `native-host/host.py`
- [Host Manifest](https://github.com/francisrox/password-strength-checker/blob/main/native-host/com.password_manager.host.json): native config · Chrome native-host registration manifest for locating and authorizing the Python host. · `native-host/com.password_manager.host.json`
- [Host Batch](https://github.com/francisrox/password-strength-checker/blob/main/native-host/host.bat): launcher script · Windows wrapper for launching the native host. · `native-host/host.bat`
- [Register Batch](https://github.com/francisrox/password-strength-checker/blob/main/native-host/register.bat): installer script · Windows script for registering the native host with Chrome. · `native-host/register.bat`

### Local Vault

Filesystem boundary for persisted credentials.

- [Passwords File](https://github.com/francisrox/password-strength-checker/blob/main/vault/.gitkeep): vault file · Local text vault storing timestamped website, username, and password entries. · `vault/.gitkeep`

### Setup & Diagnostics

Windows scripts, troubleshooting docs, and lightweight verification helpers.

- [Install Script](https://github.com/francisrox/password-strength-checker/blob/main/INSTALL.bat): setup script · Automates installation and native host registration on a new machine. · `INSTALL.bat`
- [Clean Script](https://github.com/francisrox/password-strength-checker/blob/main/CLEAN_FOR_SHARING.bat): ops script · Removes stored secrets before sharing the repository. · `CLEAN_FOR_SHARING.bat`
- [Diagnostics](https://github.com/francisrox/password-strength-checker/blob/main/DIAGNOSTIC.md): troubleshooting · Operational guides and batch helpers for checking the extension-to-host chain. · `DIAGNOSTIC.md`
- [Vault Test](https://github.com/francisrox/password-strength-checker/blob/main/test_vault.py): test · Validation helper for vault behavior and write paths. · `test_vault.py`

## Connections

- Password Field → Content Script: typed input · The content script observes password fields on pages and reacts in real time.
- Content Script → Password Analyzer: score password · The injected script uses local analysis to rate strength and detect reuse.
- Content Script → Background: save event · On submission or change, the content script hands off a credential record.
- Background → Native Bridge: native message · The background script forwards credential data across the Chrome native messaging boundary.
- Native Bridge → Host Process: receive payload · The local Python host reads messages coming from the browser extension.
- Host Process → Passwords File: write update · The host appends or updates the local vault file.
- Manifest → Content Script: injects · The manifest wires the page script into supported websites.
- Manifest → Background: registers · The manifest declares the background coordinator.
- Manifest → Popup UI: opens · The manifest exposes the popup and setup UI.
- Popup UI → Popup Logic: driven by · Popup markup is controlled by its companion script.
- Host Manifest → Host Process: authorizes · Chrome uses the native-host manifest to locate and permit the Python host.
- Host Batch → Host Process: launches · Windows wrapper starts the host process locally.
- Register Batch → Host Manifest: installs · Registration script places the native host manifest for Chrome.
- Install Script → Register Batch: orchestrates · Installation automates host registration and setup steps.
- Clean Script → Passwords File: clears · Sharing cleanup removes persisted credentials from the vault.
- Diagnostics → Native Bridge: troubleshoots · Diagnostics focus on the browser-to-host integration boundary.
- Vault Test → Passwords File: verifies · The vault test checks local persistence and access behavior.
