# davep/braindrop architecture

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

- Interactive diagram: https://gitdiagram.com/davep/braindrop
- Repository: https://github.com/davep/braindrop

## Overview

##### Main Components

a) Client Application Layer:
- Terminal UI Interface (built with Textual)
- Command System
- Screen Management
- Widget Components

b) Core Service Layer:
- Raindrop.io API Integration
- Wayback Machine Integration
- Data Management
- Configuration Handling

c) External Services:
- Raindrop.io API
- Wayback Machine API

**User Interface Layer**

**Core Application Layer**

**External Services Layer**

##### Component Relationships

a) User Interface Components:
- Screens (main.py, help.py, token_input.py, etc.)
- Widget dependencies (raindrops_view.py, raindrop_details.py)
- Link command handlers to UI elements

b) Service Integration:
- Data flow between Raindrop.io API client (raindrop/api.py)
- Wayback Machine integration (wayback/api.py)
- Configuration and token management flow

##### Specific Implementation Details

a) Application Structure:
- Command pattern implementation (app/commands/)
- Screen management system (app/screens/)
- Widget hierarchy (app/widgets/)
- Data management (app/data/)

b) API Integration:
- Raindrop.io authentication flow
- Bookmark management operations
- Wayback Machine integration

##### Key Architectural Patterns

Highlight:
- Command Pattern (commands_provider.py)
- MVC-like structure (screens, widgets, data)
- Service-oriented integration (api.py)

##### Important Notes

- Read-only nature of current implementation
- Planned features (create/edit/delete) as future additions

Remember to include:
- Token management flow
- Collection and tag management
- Search functionality
- Help system integration
- Configuration management

This will provide a comprehensive view of how the terminal-based client interacts with the bookmarking service while maintaining a clear separation of concerns between UI, application logic, and external services.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI["User Interface Layer"]
        direction TB
        MainScreen["Main Screen"]:::ui
        HelpScreen["Help Screen"]:::ui
        TokenScreen["Token Input Screen"]:::ui
        SearchScreen["Search Screen"]:::ui
        WaybackScreen["Wayback Checker"]:::ui
        
        subgraph Widgets["Widget Components"]
            direction TB
            RaindropDetails["Raindrop Details"]:::ui
            RaindropsView["Raindrops View"]:::ui
            Navigation["Navigation"]:::ui
        end
    end

    subgraph Core["Core Application Layer"]
        direction TB
        App["Core Application"]:::core
        
        subgraph Commands["Command System"]
            direction TB
            CmdProvider["Command Provider"]:::core
            CollectionCmd["Collections Commands"]:::core
            TagsCmd["Tags Commands"]:::core
            MainCmd["Main Commands"]:::core
            BaseCmd["Base Command"]:::core
            CmdMessages["Commands Messages"]:::core
        end
        
        subgraph Data["Data Management"]
            direction TB
            Config["Configuration"]:::data
            TokenMgmt["Token Management"]:::data
            LocalStorage["Local Storage"]:::data
            ExitState["Exit State"]:::data
        end
        
        subgraph Integration["Service Integration"]
            direction TB
            RaindropAPI["Raindrop API Client"]:::integration
            CollectionHandler["Collection Handler"]:::integration
            TagHandler["Tag Handler"]:::integration
            UserHandler["User Handler"]:::integration
            WaybackAPI["Wayback API Client"]:::integration
        end
    end

    subgraph External["External Services"]
        direction TB
        RaindropIO["Raindrop.io API"]:::external
        WaybackMachine["Wayback Machine API"]:::external
    end

    %% Relationships
    MainScreen --> RaindropsView
    MainScreen --> RaindropDetails
    MainScreen --> Navigation
    App --> MainScreen
    App --> HelpScreen
    App --> TokenScreen
    App --> SearchScreen
    App --> WaybackScreen
    
    CmdProvider --> CollectionCmd
    CmdProvider --> TagsCmd
    CmdProvider --> MainCmd
    BaseCmd --> CmdMessages
    
    Integration --> RaindropIO
    WaybackAPI --> WaybackMachine
    
    App --> CmdProvider
    App --> Data
    App --> Integration

    %% Click Events
    click MainScreen "https://github.com/davep/braindrop/blob/main/src/braindrop/app/screens/main.py"
    click HelpScreen "https://github.com/davep/braindrop/blob/main/src/braindrop/app/screens/help.py"
    click TokenScreen "https://github.com/davep/braindrop/blob/main/src/braindrop/app/screens/token_input.py"
    click SearchScreen "https://github.com/davep/braindrop/blob/main/src/braindrop/app/screens/search_input.py"
    click WaybackScreen "https://github.com/davep/braindrop/blob/main/src/braindrop/app/screens/wayback_checker.py"
    click RaindropDetails "https://github.com/davep/braindrop/blob/main/src/braindrop/app/widgets/raindrop_details.py"
    click RaindropsView "https://github.com/davep/braindrop/blob/main/src/braindrop/app/widgets/raindrops_view.py"
    click Navigation "https://github.com/davep/braindrop/blob/main/src/braindrop/app/widgets/navigation.py"
    click CmdProvider "https://github.com/davep/braindrop/blob/main/src/braindrop/app/commands/commands_provider.py"
    click CollectionCmd "https://github.com/davep/braindrop/blob/main/src/braindrop/app/commands/collections.py"
    click TagsCmd "https://github.com/davep/braindrop/blob/main/src/braindrop/app/commands/tags.py"
    click MainCmd "https://github.com/davep/braindrop/blob/main/src/braindrop/app/commands/main.py"
    click Config "https://github.com/davep/braindrop/blob/main/src/braindrop/app/data/config.py"
    click TokenMgmt "https://github.com/davep/braindrop/blob/main/src/braindrop/app/data/token.py"
    click LocalStorage "https://github.com/davep/braindrop/blob/main/src/braindrop/app/data/local.py"
    click ExitState "https://github.com/davep/braindrop/blob/main/src/braindrop/app/data/exit_state.py"
    click RaindropAPI "https://github.com/davep/braindrop/blob/main/src/braindrop/raindrop/api.py"
    click CollectionHandler "https://github.com/davep/braindrop/blob/main/src/braindrop/raindrop/collection.py"
    click TagHandler "https://github.com/davep/braindrop/blob/main/src/braindrop/raindrop/tag.py"
    click UserHandler "https://github.com/davep/braindrop/blob/main/src/braindrop/raindrop/user.py"
    click WaybackAPI "https://github.com/davep/braindrop/blob/main/src/braindrop/wayback/api.py"
    click App "https://github.com/davep/braindrop/blob/main/src/braindrop/app/braindrop.py"
    click BaseCmd "https://github.com/davep/braindrop/blob/main/src/braindrop/app/messages/base_command.py"
    click CmdMessages "https://github.com/davep/braindrop/blob/main/src/braindrop/app/messages/commands.py"

    %% Styles
    classDef ui fill:#2374ab
    classDef core fill:#48a9a6
    classDef data fill:#757575
    classDef integration fill:#4caf50
    classDef external fill:#ff9800
    
    %% Legend
    subgraph Legend
        direction TB
        UI_Component["UI Component"]:::ui
        Core_Component["Core Component"]:::core
        Data_Component["Data Component"]:::data
        Integration_Component["Integration Component"]:::integration
        External_Component["External Service"]:::external
    end
```
