# borisbabic/browser_cookie3 architecture

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

- Interactive diagram: https://gitdiagram.com/borisbabic/browser_cookie3
- Repository: https://github.com/borisbabic/browser_cookie3

## Overview

##### Project type and purpose
- This is an open-source Python library & CLI tool (“browser_cookie3”) that exposes functions (and a command‐line interface) to load cookies from various web browsers into a Python http.cookiejar.CookieJar.

##### File structure
- Top level:
- .github/workflows/* → CI for testing on Linux & Windows
- setup.py, MANIFEST.in, release.nix → packaging & deployment
- README(.md), LICENSE, CHANGELOG.md
- Core package:
- browser_cookie3/__init__.py → public API & factory functions (chrome(), firefox(), load(), etc.)
- browser_cookie3/__main__.py → CLI entrypoint (console script “browser-cookie”)
- Tests: tests/ and tests/utils/ → unit tests for each browser loader, path-finding, driver/version detection, user-agent helpers

##### README for additional insights
- Lists supported browsers & platforms
- Describes two usage patterns:
a) Python API: import browser_cookie3; cj = browser_cookie3.chrome()
b) CLI: browser-cookie --chrome domain name

##### Main components & interactions
a. Components:
- Client (Python script or CLI)
- CLI wrapper (browser_cookie3.__main__)
- Core Library (browser_cookie3 package)
– Browser-specific loader modules (ChromeLoader, FirefoxLoader, etc.)
– Profile & path discovery logic (cross-platform)
– Decryption helper (e.g., Windows CryptUnprotectData, macOS keychain, Linux decryption)
– SQLite/TXT parser
– CookieJar builder
- External dependencies:
– File System (browser cookie store files)
– OS-specific encryption APIs
– Python stdlib sqlite3, http.cookiejar
- Consumer HTTP client (requests or urllib2)

b. Relationships & data flow:
1. User invokes Python API or CLI.
2. CLI → calls Core Library .load() or browser-specific function.
3. Library → discovers cookie file path(s) via path-finder.
4. Library → if encrypted, calls decryption helper.
5. Library → opens SQLite DB or TXT, queries cookie table or parses text.
6. Library → populates CookieJar object.
7. Library → returns CookieJar to Client.
8. Client → HTTP client uses CookieJar to attach cookies to outgoing requests.

c. Architectural patterns / design principles:
- Strategy pattern: one loader per browser, all implement a common interface
- Factory functions: chrome(), firefox(), load() select appropriate strategy
- Single responsibility: separate modules for path discovery, decryption, DB parsing
- Cross-platform abstraction: OS-branching inside path/discovery and decryption layers

d. Key technologies & libraries:
- Python 3.x
- sqlite3 (built-in)
- http.cookiejar
- platform & os modules (path discovery)
- ctypes / win32crypt (Windows decryption)
- keyring or subprocess to call macOS keychain
- tab-delimited TXT parser for W3m/Lynx

##### Essential elements to capture
- Labels for each component & module
- Library core vs. browser-specific strategies
- Data stores vs. code modules
- OS APIs vs. application code

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Layer
    Client["Client (Python script or CLI)"]:::consumer
    CLI["CLI Wrapper (__main__.py)"]:::library
    API["Factory API & Public API<br/>(load(), chrome(), firefox())"]:::library

    %% Strategy Layer
    subgraph "Browser Loader Strategy"
        direction TB
        Loader["ChromeLoader Module<br/>(+ others)"]:::library
    end

    %% Core Modules
    PD["Path Discovery Module"]:::library
    DEC["Decryption Module"]:::library
    SP["SQLite/TXT Parser Module"]:::library
    CJ["CookieJar Builder"]:::library

    %% External Systems
    FSFile["Browser Cookie File<br/>(SQLite / TXT)"]:::external_file
    OS["OS Crypto APIs"]:::external

    %% HTTP Client
    HC["HTTP Client<br/>(requests/urllib2)"]:::consumer

    %% CI & Packaging
    subgraph "CI & Packaging"
        direction TB
        CI1[".github/workflows/test_linux.yml"]:::external
        CI2[".github/workflows/test_windows.yml"]:::external
        Setup["setup.py"]:::external
        Manifest["MANIFEST.in"]:::external
        Release["release.nix"]:::external
    end

    %% Data Flow
    Client -->|"invoke CLI"| CLI
    CLI -->|"calls load()/chrome()"| API
    API -->|"selects strategy"| Loader
    Loader -->|"query path"| PD
    PD -->|"locate cookie file"| FSFile
    FSFile -->|"encrypted? decrypt"| DEC
    OS -->|"decrypt API"| DEC
    DEC -->|"provide decrypted file"| SP
    FSFile -->|"read DB/TXT"| SP
    SP -->|"parse cookies"| CJ
    CJ -->|"return CookieJar"| Client
    Client -->|"attach cookies"| HC

    %% Click Events
    click CLI "https://github.com/borisbabic/browser_cookie3/blob/master/browser_cookie3/__main__.py"
    click API "https://github.com/borisbabic/browser_cookie3/blob/master/browser_cookie3/__init__.py"
    click CI1 "https://github.com/borisbabic/browser_cookie3/blob/master/.github/workflows/test_linux.yml"
    click CI2 "https://github.com/borisbabic/browser_cookie3/blob/master/.github/workflows/test_windows.yml"
    click Setup "https://github.com/borisbabic/browser_cookie3/blob/master/setup.py"
    click Manifest "https://github.com/borisbabic/browser_cookie3/blob/master/MANIFEST.in"
    click Release "https://github.com/borisbabic/browser_cookie3/blob/master/release.nix"

    %% Styles
    classDef library fill:#BBDEFB,stroke:#2196F3,color:#0D47A1
    classDef external fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef external_file fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
    classDef consumer fill:#FFE0B2,stroke:#FB8C00,color:#E65100
```
