# browsh-org/browsh architecture

> Architecture diagram of the GitHub repository browsh-org/browsh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/browsh-org/browsh
- Repository: https://github.com/browsh-org/browsh

## Overview

##### Main Components Identification

a) Web Extension (webext/)
- Firefox integration layer
- DOM manipulation and rendering
- Graphics and text processing

b) Interfacer (interfacer/)
- Core application logic
- TTY handling
- Firefox communication
- Raw text server

c) Firefox Browser
- Headless instance
- Web page processing
- JavaScript execution

**┌─────────────────┐**
- Client Layer  │ (Terminal/Browser)
- ┬────────┘

**┌────────┴────────┐**
- Interfacer     │ (Go Implementation)
- ┬────────┘

**┌────────┴────────┐**
- Web Extension  │ (Firefox Extension)
- ┬────────┘

**┌────────┴────────┐**
- Headless Firefox│
- ┬────────┘

**┌────────┴────────┐**
- Web Content    │
- ┘

##### Component Details

For each major component, include these specific elements:

Web Extension Component:
- Background Scripts (src/background/)
- DOM Handlers (src/dom/)
- Graphics Builder
- Text Builder
- TTY Grid System

Interfacer Component:
- Command Processing
- Firefox Management
- TTY Interface
- Raw Text Server
- Configuration Management

##### Data Flow Indicators

- User input flow from terminal/browser to the interfacer
- Communication between interfacer and web extension
- Web content rendering pipeline
- Text conversion and formatting flow

##### Technical Details

Annotations for:
- Go-based backend services
- JavaScript-based extension components
- Firefox integration points
- WebSocket/Native messaging channels
- Text rendering pipeline

##### Implementation Notes

- The separation between the terminal interface and web processing
- The role of the web extension in converting web content to text
- The communication flow between components
- The configuration and state management system

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph CL[Client Layer]
        Terminal["Terminal Client"]
        Browser["Browser Client"]
    end

    %% Interfacer Layer
    subgraph IL[Interfacer Layer]
        MainEntry["Main Entry Point"]:::entry
        Config["Configuration Management"]:::config
        TTY["TTY Interface"]:::tty
        RawText["Raw Text Server"]:::server
        FFManager["Firefox Management"]:::firefox
        Comms["Communication Layer"]:::comms
        
        subgraph Input["Input Processing"]
            InputBox["Input Box"]:::input
            InputCursor["Input Cursor"]:::input
            InputScroll["Input Scroll"]:::input
            InputMulti["Multiline Input"]:::input
        end
        
        FrameBuilder["Frame Builder"]:::frame
    end

    %% Web Extension Layer
    subgraph WE[Web Extension Layer]
        WEManager["Web Extension Manager"]:::webext
        
        subgraph DOM["DOM Processing"]
            DOMHandler["DOM Handler System"]:::dom
            GraphicsBuilder["Graphics Builder"]:::graphics
            TextBuilder["Text Builder"]:::text
            TTYGrid["TTY Grid System"]:::grid
        end
    end

    %% Firefox Layer
    subgraph FL[Firefox Layer]
        HeadlessFF["Headless Firefox"]
        WebContent["Web Content"]
    end

    %% Relationships
    Terminal & Browser --> MainEntry
    MainEntry --> Config
    MainEntry --> TTY
    MainEntry --> RawText
    MainEntry --> FFManager
    MainEntry --> Comms
    
    Comms <--> WEManager
    
    FFManager --> HeadlessFF
    HeadlessFF --> WebContent
    
    WEManager --> DOMHandler
    DOMHandler --> GraphicsBuilder
    DOMHandler --> TextBuilder
    TextBuilder --> TTYGrid
    
    Input --> FrameBuilder
    FrameBuilder --> TTY
    
    %% Styles
    classDef entry fill:#1f77b4
    classDef config fill:#2ca02c
    classDef tty fill:#d62728
    classDef server fill:#9467bd
    classDef firefox fill:#8c564b
    classDef comms fill:#e377c2
    classDef input fill:#7f7f7f
    classDef frame fill:#bcbd22
    classDef webext fill:#17becf
    classDef dom fill:#ff7f0e
    classDef graphics fill:#ffbb78
    classDef text fill:#98df8a
    classDef grid fill:#ff9896

    %% Click Events
    click MainEntry "https://github.com/browsh-org/browsh/blob/master/interfacer/cmd/browsh/main.go"
    click Config "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/config.go"
    click TTY "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/tty.go"
    click RawText "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/raw_text_server.go"
    click FFManager "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/firefox.go"
    click Comms "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/comms.go"
    click InputBox "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/input_box.go"
    click InputCursor "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/input_cursor.go"
    click InputScroll "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/input_scroll.go"
    click InputMulti "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/input_multiline.go"
    click FrameBuilder "https://github.com/browsh-org/browsh/blob/master/interfacer/src/browsh/frame_builder.go"
    click WEManager "https://github.com/browsh-org/browsh/blob/master/webext/src/background/manager.js"
    click DOMHandler "https://github.com/browsh-org/browsh/tree/master/webext/src/dom/"
    click GraphicsBuilder "https://github.com/browsh-org/browsh/blob/master/webext/src/dom/graphics_builder.js"
    click TextBuilder "https://github.com/browsh-org/browsh/blob/master/webext/src/dom/text_builder.js"
    click TTYGrid "https://github.com/browsh-org/browsh/blob/master/webext/src/dom/tty_grid.js"
```
