# brumm/tako architecture

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

- Interactive diagram: https://gitdiagram.com/brumm/tako
- Repository: https://github.com/brumm/tako

## Overview

##### Project type and purpose
- This is a browser extension (Chrome and Firefox) named “Tako” whose purpose is to inject an inline, expandable GitHub file tree with file preview directly into GitHub repository pages.
- It uses React components to render the UI, content scripts to inject that UI into GitHub pages, and a background script to handle persistent state (e.g., tokens) and messaging.

##### File structure
- Top-level files:
- package.json, webpack.config.js – build and dependency configuration
- media/ – extension logo, screenshots
- README.md, TODO.txt, LICENSE
- src/:
- entry-background.js → background entry point
- entry-content-script.js → content-script entry point
- background.js → background logic (token storage, messaging listeners)
- api.js, github-relative-time.js, queryClient.js, storage.js, utils.js – utility layers for networking, caching, storage
- import-extension-assets.js, template.html.ejs – build-time asset injection
- components/ – pure React UI components (App, Listing, Preview, Error boundaries, etc.)
- constants.js, hooks.js
- webpack.config.js builds two output bundles (background & content script) plus EJS-templated HTML for packaging.

##### README for additional insights
- Confirms it is injected into GitHub repos in dev and production mode
- Build commands produce zipped extension packages for Chrome/Firefox

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Browser Host"
        direction TB
        BgEntry["Background Script Bundle"]:::extension
        BgLogic["Background Logic"]:::extension
        CsEntry["Content Script Bundle"]:::extension
        chromeStorage["chrome.storage"]:::storage
    end

    subgraph "React UI Layer"
        direction TB
        App["App (src/components/App.js)"]:::ui
        GEB["GlobalErrorBoundary"]:::ui
        ITEB["InvalidTokenErrorBoundary"]:::ui
        RepoTree["RepoFileTree"]:::ui
        Listing["Listing"]:::ui
        Preview["Preview"]:::ui
        NodeC["Node"]:::ui
        Loading["Loading"]:::ui
        Placeholder["Placeholder"]:::ui
        Logo["TakoLogo"]:::ui
        AskToken["AskForToken"]:::ui
        ReEnter["ReEnterOnInvalidToken"]:::ui
        PrependPort["PrependPortal"]:::ui
        ErrorRpt["ErrorReport"]:::ui
        Checker["CheckerPattern"]:::ui
        RootComp["Root (DOM mount wrapper)"]:::ui
        Icons["icons"]:::ui
        Styled["styled"]:::ui
    end

    subgraph "Data Layer"
        direction TB
        API["api.js"]:::data
        Cache["queryClient.js"]:::data
        StorageAb["storage.js"]:::data
        RelTime["github-relative-time.js"]:::data
        Utils["utils.js"]:::data
        Hooks["hooks.js"]:::data
        Const["constants.js"]:::data
    end

    ExtGitHubPage["GitHub Repo Page DOM"]:::external
    ExtGitHubAPI["GitHub REST API"]:::external
    subgraph "Build & Packaging"
        direction TB
        Manifest["package.json & webpack.config.js"]:::pipeline
        AssetInjector["import-extension-assets.js & template.html.ejs"]:::pipeline
        Assets["media/"]:::pipeline
    end

    %% Interactions
    CsEntry -->|"injects UI"| ExtGitHubPage
    CsEntry -->|mounts| RootComp
    RootComp -->|wraps| GEB
    GEB -->|catches errors| ITEB
    ITEB -->|renders| App
    App --> RepoTree
    RepoTree --> Listing
    RepoTree --> Preview
    Listing -->|renders| NodeC
    Listing -->|renders| Loading
    Listing -->|renders| Placeholder
    RepoTree -->|portal| PrependPort
    App --> Logo
    App --> AskToken
    App --> ReEnter
    App --> ErrorRpt
    App --> Checker
    App --> Icons
    App --> Styled

    RepoTree -->|uses| Cache
    Preview -->|uses| Cache
    Cache -->|fetches via api.js| API
    API -->|GET /repos/:owner/:repo/contents| ExtGitHubAPI

    AskToken -->|"chrome.runtime.sendMessage(tokenRequest)"| BgLogic
    ReEnter -->|"chrome.runtime.sendMessage(tokenRequest)"| BgLogic
    BgLogic -->|reads/writes| chromeStorage
    StorageAb -->|abstraction| chromeStorage
    BgLogic -->|responds with token| App

    Const --> API
    Utils --> API
    Hooks --> App
    RelTime --> App

    Manifest -->|bundles| BgEntry
    Manifest -->|bundles| CsEntry
    AssetInjector -->|injects assets| Assets
    Manifest -->|includes| AssetInjector
    Assets -->|packaged into| BgEntry
    Assets -->|packaged into| CsEntry

    %% External Systems
    ExtGitHubPage -.->|user interacts| ExtGitHubPage
    ExtGitHubAPI -.->|external service| ExtGitHubAPI

    %% Styles
    classDef extension fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef ui fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    classDef data fill:#ffe0b2,stroke:#ef6c00,color:#e65100
    classDef storage fill:#d1c4e9,stroke:#5e35b1,color:#311b92
    classDef external fill:#eeeeee,stroke:#757575,color:#424242
    classDef pipeline fill:#f0f4c3,stroke:#9e9d24,color:#827717

    %% Click Events
    click BgEntry "https://github.com/brumm/tako/blob/master/src/entry-background.js"
    click BgLogic "https://github.com/brumm/tako/blob/master/src/background.js"
    click CsEntry "https://github.com/brumm/tako/blob/master/src/entry-content-script.js"
    click App "https://github.com/brumm/tako/blob/master/src/components/App.js"
    click GEB "https://github.com/brumm/tako/blob/master/src/components/GlobalErrorBoundary.js"
    click ITEB "https://github.com/brumm/tako/blob/master/src/components/InvalidTokenErrorBoundary.js"
    click RepoTree "https://github.com/brumm/tako/blob/master/src/components/RepoFileTree.js"
    click Listing "https://github.com/brumm/tako/blob/master/src/components/Listing.js"
    click Preview "https://github.com/brumm/tako/blob/master/src/components/Preview.js"
    click NodeC "https://github.com/brumm/tako/blob/master/src/components/Node.js"
    click Loading "https://github.com/brumm/tako/blob/master/src/components/Loading.js"
    click Placeholder "https://github.com/brumm/tako/blob/master/src/components/Placeholder.js"
    click Logo "https://github.com/brumm/tako/blob/master/src/components/TakoLogo.js"
    click AskToken "https://github.com/brumm/tako/blob/master/src/components/AskForToken.js"
    click ReEnter "https://github.com/brumm/tako/blob/master/src/components/ReEnterOnInvalidToken.js"
    click PrependPort "https://github.com/brumm/tako/blob/master/src/components/PrependPortal.js"
    click ErrorRpt "https://github.com/brumm/tako/blob/master/src/components/ErrorReport.js"
    click Checker "https://github.com/brumm/tako/blob/master/src/components/CheckerPattern.js"
    click RootComp "https://github.com/brumm/tako/blob/master/src/components/Root.js"
    click Icons "https://github.com/brumm/tako/blob/master/src/components/icons.js"
    click Styled "https://github.com/brumm/tako/blob/master/src/components/styled.js"
    click API "https://github.com/brumm/tako/blob/master/src/api.js"
    click Cache "https://github.com/brumm/tako/blob/master/src/queryClient.js"
    click StorageAb "https://github.com/brumm/tako/blob/master/src/storage.js"
    click RelTime "https://github.com/brumm/tako/blob/master/src/github-relative-time.js"
    click Utils "https://github.com/brumm/tako/blob/master/src/utils.js"
    click Hooks "https://github.com/brumm/tako/blob/master/src/hooks.js"
    click Const "https://github.com/brumm/tako/blob/master/src/constants.js"
    click Manifest "https://github.com/brumm/tako/blob/master/package.json"
    click Manifest "https://github.com/brumm/tako/blob/master/webpack.config.js"
    click AssetInjector "https://github.com/brumm/tako/blob/master/src/import-extension-assets.js"
    click AssetInjector "https://github.com/brumm/tako/blob/master/src/template.html.ejs"
    click Assets "https://github.com/brumm/tako/tree/master/media/"
```
