# cclgroupltd/ccl_chromium_reader architecture

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

- Interactive diagram: https://gitdiagram.com/cclgroupltd/ccl_chromium_reader
- Repository: https://github.com/cclgroupltd/ccl_chromium_reader

## Overview

##### Project type and purpose
- This is an open-source Python library and toolkit (“ccl_chromium_reader”) for forensic extraction of data from Chromium/Chrome profile folders.
- It provides modular readers (cache, history, IndexedDB, LocalStorage, etc.), serialization/deserialization of on-disk formats, a high-level Facade (`ChromiumProfileFolder`), and several CLI/utility scripts.

##### File structure
- Top-level package: `ccl_chromium_reader/`
- Modules for each data store:
– ccl_chromium_cache.py (Cache API)
– ccl_chromium_filesystem.py (FileSystem API)
– ccl_chromium_history.py (History)
– ccl_chromium_indexeddb.py (IndexedDB)
– ccl_chromium_localstorage.py (Local Storage)
– ccl_chromium_sessionstorage.py (Session Storage)
– ccl_chromium_notifications.py, ccl_chromium_snss2.py, downloads, common utilities
- Subpackage `serialization_formats/` handles object deserialization (Pickle, Protobuf, V8, Blink).
- Subpackage `storage_formats/` wraps on-disk databases (LevelDB).
- `profile_folder_protocols.py` and `ccl_chromium_profile_folder.py` implement the Facade and common protocols.
- `tools_and_utilities/` folder: CLI scripts that invoke the library (dumpers and the audit tool).
- Project config: `pyproject.toml`, `requirements.txt`.

##### Extract insights from README
- Core façade: `ChromiumProfileFolder` lazily loads each data store.
- Two APIs per module: raw and wrapper API.
- CLI tools reuse modules for automated data dumps and audits.
- Dependencies are minimal (Python 3.10, optional Brotli).

a. Main Components
- External: Chromium Profile Folder (file system containing SQLite, LevelDB, cache, blobs)
- Data-Access Layer
– FileSystem API
– LevelDB wrapper (`storage_formats`)
– Shared-Proto-DB reads (downloads)
- Serialization Layer (`serialization_formats`)
– Protobuf, Pickle, V8, Blink deserializers
- Core Domain
– Individual store readers (cache, history, Local/Session Storage, notifications, SNSS)
– Common utilities (`common.py`, `download_common.py`)
- Facade Layer
– `ChromiumProfileFolder` (unified API, KeySearch)
- CLI/Tools Layer (`tools_and_utilities`)
– Scripts (dumpers, `ccl_chrome_audit.py`, benchmark)
b. Relationships and Data Flow
1. CLI script invokes Facade or individual store reader.
2. Facade calls the appropriate store reader module.
3. Store reader uses Data-Access Layer to read raw files/LevelDB stubs.
4. Serialization Layer decodes raw bytes into Python objects.
5. Data objects are wrapped in domain classes and returned to CLI or user code.
6. CLI writes output (console, CSV, files).
c. Architectural patterns and principles
- Layered architecture (Data-Access → Serialization → Domain → Facade → Presentation)
- Facade pattern (`ChromiumProfileFolder` unifies multiple modules)
- Adapter pattern (wrapping LevelDB, block-file cache)
- Separation of concerns: each module handles one store or one format.
d. Key technologies
- Python 3.10
- LevelDB (via direct file parsing)
- Protocol Buffers
- Chrome’s Pickle, V8, Blink serialization formats
- Standard library + optional Brotli

##### Details
- Clear labels on every component (package or script name).
- Chromium Profile Folder at the bottom as the physical data source.
- Facade methods (e.g., `iter_local_storage()`, `iterate_history_records()`).

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI Layer
    subgraph "CLI / Tools Layer"
        CLI["tools_and_utilities/*"]:::cli
    end

    %% Facade Layer
    subgraph "Facade Layer"
        Facade["ChromiumProfileFolder"]:::facade
    end

    %% Domain Layer
    subgraph "Domain / Store Readers"
        Cache["Cache Store Reader"]:::domain
        History["History Store Reader"]:::domain
        IndexedDB["IndexedDB Store Reader"]:::domain
        LocalStorage["LocalStorage Store Reader"]:::domain
        SessionStorage["SessionStorage Store Reader"]:::domain
        Notifications["Notifications Store Reader"]:::domain
        SNSS2["SNSS2 Store Reader"]:::domain
        Common["Common Utilities"]:::domain
        DownloadUtil["Download-related Utilities"]:::domain
    end

    %% Data-Access Layer
    subgraph "Data-Access Layer"
        FSAPI["FileSystem API"]:::dataaccess
        LevelDB["LevelDB Wrapper"]:::dataaccess
        SharedProto["Shared-Proto-DB Downloads Adapter"]:::dataaccess
    end

    %% Serialization Layer
    subgraph "Serialization Layer"
        Blink["Blink Deserializer"]:::serialization
        Pickle["Chromium Pickle Deserializer"]:::serialization
        Protobuf["Protobuf Deserializer"]:::serialization
        V8["V8 Deserializer"]:::serialization
    end

    %% Physical Storage
    ChromiumDisk["Chromium Profile Folder"]:::storage

    %% Connections
    CLI -->|"invokes"| Facade
    CLI -->|"invokes store reader"| Cache
    CLI -->|"invokes store reader"| History
    CLI -->|"invokes store reader"| IndexedDB
    CLI -->|"invokes store reader"| LocalStorage
    CLI -->|"invokes store reader"| SessionStorage
    CLI -->|"invokes store reader"| Notifications
    CLI -->|"invokes store reader"| SNSS2

    Facade -->|"uses"| Cache
    Facade -->|"uses"| History
    Facade -->|"uses"| IndexedDB
    Facade -->|"uses"| LocalStorage
    Facade -->|"uses"| SessionStorage
    Facade -->|"uses"| Notifications
    Facade -->|"uses"| SNSS2
    Facade -->|"uses"| Common
    Facade -->|"uses"| DownloadUtil

    Cache -->|"reads via"| FSAPI
    History -->|"reads via"| FSAPI
    IndexedDB -->|"reads via"| LevelDB
    LocalStorage -->|"reads via"| LevelDB
    SessionStorage -->|"reads via"| LevelDB
    Notifications -->|"reads via"| SharedProto
    SNSS2 -->|"reads via"| SharedProto
    DownloadUtil -->|"reads via"| SharedProto

    Cache -->|"deserializes with"| Pickle
    History -->|"deserializes with"| Protobuf
    IndexedDB -->|"deserializes with"| V8
    LocalStorage -->|"deserializes with"| Blink
    SessionStorage -->|"deserializes with"| Blink
    Notifications -->|"deserializes with"| Protobuf
    SNSS2 -->|"deserializes with"| Protobuf

    FSAPI -->|"reads files from"| ChromiumDisk
    LevelDB -->|"reads LevelDB from"| ChromiumDisk
    SharedProto -->|"reads downloads from"| ChromiumDisk

    %% Click Events
    click FSAPI "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_filesystem.py"
    click LevelDB "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/storage_formats/ccl_leveldb.py"
    click SharedProto "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_shared_proto_db_downloads.py"
    click Blink "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/serialization_formats/ccl_blink_value_deserializer.py"
    click Pickle "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/serialization_formats/ccl_easy_chromium_pickle.py"
    click Protobuf "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/serialization_formats/ccl_protobuff.py"
    click V8 "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/serialization_formats/ccl_v8_value_deserializer.py"
    click Cache "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_cache.py"
    click History "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_history.py"
    click IndexedDB "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_indexeddb.py"
    click LocalStorage "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_localstorage.py"
    click SessionStorage "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_sessionstorage.py"
    click Notifications "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_notifications.py"
    click SNSS2 "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_snss2.py"
    click Common "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/common.py"
    click DownloadUtil "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/download_common.py"
    click Facade "https://github.com/cclgroupltd/ccl_chromium_reader/blob/master/ccl_chromium_reader/ccl_chromium_profile_folder.py"
    click CLI "https://github.com/cclgroupltd/ccl_chromium_reader/tree/master/tools_and_utilities/"

    %% Styles
    classDef dataaccess fill:#D0E8FF,stroke:#3399FF,color:#000;
    classDef serialization fill:#FFE0B2,stroke:#FF9900,color:#000;
    classDef domain fill:#DFF2BF,stroke:#66CC33,color:#000;
    classDef facade fill:#A3E4DB,stroke:#1ABC9C,color:#000;
    classDef cli fill:#E2D1F9,stroke:#8E44AD,color:#000;
    classDef storage fill:#F0F0F0,stroke:#888888,color:#000,stroke-dasharray: 5 5;
    class ChromiumDisk storage
```
