# anshulgada/brave-tab-manager architecture

> Architecture diagram of the GitHub repository anshulgada/brave-tab-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anshulgada/brave-tab-manager
- Repository: https://github.com/anshulgada/brave-tab-manager

## Overview

##### Main Components
- CLI / Entry Point: The tool is triggered by the command-line. The main module (tabman/main.py) serves as the central entry point.
- Tab Capture & Retrieval Module: Components like tabman/tab_capture.py and tabman/content_fetcher.py are responsible for connecting to your Brave (or Chromium-based) browser via its remote debugging interface to retrieve information about open tabs.
- Categorization Module: The categorizer (tabman/categorizer.py) uses AI models (Google Gemini, Mistral, Ollama) for intelligently classifying and tagging tabs. This module encapsulates the decision logic and API calls.
- Content Processing & Search: Additional logic exists in modules like tabman/search.py, which support functions such as searching or filtering retrieved data.
- Saving / Data Persistence: The tabman/tab_saver.py module handles saving the output. It writes the tab data in JSON, Markdown, and maintains (appending to) a central all_tabs.md file. Note that the README mentions storing files in date-based subfolders under a configurable output directory.
- GUI Component: Although the core tool is a CLI, there is a graphical interface option under tabman/gui (with the module gui_main.py) that likely offers a visual presentation of the tab data.
- Configuration & Environment: The project uses a .env file (an example provided in tabman/.env.example) for secure storage of API keys and other configurable settings.

##### Relationships and Data Flow
- Following categorization, illustrate the flow to the Data Saver component, which writes and organizes the session to file (in JSON and Markdown formats).
- Optionally, include a branch that routes data to the GUI module for a graphical representation if the user chooses that interface.

##### Architectural Patterns & Design Principles
- Modularization: Emphasize the clear separation of concerns among different files (fetching tabs, categorization, saving data, UI rendering). Each module is dedicated to specific functionality.
- Extensibility: The design supports multiple language models (shown in the categorizer) and can easily incorporate changes or additions (e.g., new AI services) without major restructuring.
- Configuration Management: Use special components (via the .env file and command-line arguments) to manage API keys and environment variables securely.

##### Detail Key Technologies and Dependencies
- That the system utilizes libraries including openai, ollama, requests, playwright, python-dotenv, and others (as mentioned in the README).
- That these dependencies play roles in AI integration and browser interaction.

This comprehensive and modular approach will help you (or any principal software engineer) quickly grasp the design’s essentials and make it easier to maintain or extend the tool further in a real-world environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Interface (tabman/main.py)"]:::cli
        GUI["GUI Component (gui_main.py)"]:::module
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        subgraph "Tab Capture & Retrieval"
            TabCapture["Tab Capture (tab_capture.py)"]:::module
            ContentFetcher["Content Fetcher (content_fetcher.py)"]:::module
        end
        Categorizer["Categorization Engine (categorizer.py)"]:::module
        Search["Content Processing & Search (search.py)"]:::module
    end

    %% Data Persistence Layer
    subgraph "Data Persistence Layer"
        Saver["Data Persistence (tab_saver.py)"]:::module
    end

    %% Configuration
    subgraph "Configuration"
        Config["Configuration (.env)"]:::config
    end

    %% External Systems
    subgraph "External Systems"
        Brave["Brave Browser (Remote Debugging)"]:::external
        AIModels["AI Models (Gemini,Mistral,Ollama)"]:::external
    end

    %% Main Flow
    CLI --> TabCapture
    CLI --> ContentFetcher

    TabCapture --> Categorizer
    ContentFetcher --> Categorizer

    TabCapture --> Search
    ContentFetcher --> Search

    Categorizer --> Saver
    Search --> Saver

    %% Optional GUI branch
    Categorizer -->|"optional"| GUI

    %% External interactions
    TabCapture -.-> Brave
    ContentFetcher -.-> Brave

    Categorizer -.-> AIModels

    %% Configuration dependencies
    Config -.-> CLI
    Config -.-> TabCapture
    Config -.-> ContentFetcher
    Config -.-> Categorizer

    %% Click Events
    click CLI "https://github.com/anshulgada/brave-tab-manager/blob/main/tabman/main.py"
    click TabCapture "https://github.com/anshulgada/brave-tab-manager/blob/main/tabman/tab_capture.py"
    click ContentFetcher "https://github.com/anshulgada/brave-tab-manager/blob/main/tabman/content_fetcher.py"
    click Categorizer "https://github.com/anshulgada/brave-tab-manager/blob/main/tabman/categorizer.py"
    click Search "https://github.com/anshulgada/brave-tab-manager/blob/main/tabman/search.py"
    click Saver "https://github.com/anshulgada/brave-tab-manager/blob/main/tabman/tab_saver.py"
    click GUI "https://github.com/anshulgada/brave-tab-manager/blob/main/tabman/gui/gui_main.py"
    click Config "https://github.com/anshulgada/brave-tab-manager/blob/main/tabman/.env.example"

    %% Styles
    classDef cli fill:#ACE,stroke:#333,stroke-width:2px;
    classDef module fill:#CDE,stroke:#333,stroke-width:2px;
    classDef external fill:#FCA,stroke:#333,stroke-width:2px;
    classDef config fill:#EED,stroke:#333,stroke-width:2px;
```
