# twillot-app/twillot architecture

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

- Interactive diagram: https://gitdiagram.com/twillot-app/twillot
- Repository: https://github.com/twillot-app/twillot

## Overview

##### Project type and purpose
- This is a pnpm-workspace monorepo containing multiple browser extensions (exporter, multi-publish, x-bookmarks, x-bookmarks-automation) plus a shared utils package.
- The primary product (“Twillot”) is an AI-powered Chrome extension for managing, searching, and exporting X/Twitter bookmarks without needing a Premium account.

##### File structure
- Top-level folders:
– exporter, multi-publish, x-bookmarks, x-bookmarks-automation: four separate Chrome extensions built with SolidJS + Vite + TypeScript + Tailwind.
– packages/utils: shared helper modules (API clients, storage adapters, hooks, utilities).
– scripts & submit: build/deployment automation and data submission scripts (Python + JS).
– docs: API request/response specs, error flows.
- Notice each extension has these subcomponents:
– src/background (background service worker)
– src/contentScript
– src/devtools
– src/options, src/popup, src/newtab, src/sidepanel, etc.
– manifest.ts for Chrome manifest generation
– packaging configs: vite.config.ts, tsconfig.json, tailwind.config.cjs

##### Pull in README insights
- Core features: folder management, local sync, keyword search, AI smart categorization, media export.
- Tech stack: SolidJS for UI, Flowbite for components, create-chrome-ext starter, Vite for bundling, pnpm workspaces.
- External dependencies: Twitter API, AI categorization service, browser storage (IndexedDB or chrome.storage), ZIP library for media export.

a. Main components
1. Browser Host (Chrome)
2. Extension “Core”:
– Background Service Worker (fetching/syncing, messaging hub)
– Content Script (inject into twitter.com pages)
– DevTools Panel
– UI Pages: Popup, Options, New Tab, Side Panel
3. Shared Utils Layer (packages/utils)
4. External Services:
– Twitter REST API (bookmarks, tweets, media)
– AI Categorization Service (smart tagging)
5. Local Data Store: chrome.storage.local / IndexedDB
6. Build & CI/CD Pipeline (pnpm, vite, vitest, GitHub Actions)

b. Relationships & data flow
- Background ↔ Content Script: chrome.runtime messaging
- Background ↔ UI Pages (Popup/Options/...): chrome.runtime messaging + storage reads/writes
- Background → Twitter API / AI Service: HTTP calls initiated from SW (with fetch or xfetch util)
- UI Pages → Shared Utils: import hooks, API clients, types for data display & actions
- Data persistence: SW writes to chrome.storage.local or IndexedDB via utils/db
- Build: Each extension imports from packages/utils and is bundled via Vite → outputs in dist/

c. Architectural patterns & principles
- Monorepo with PNPM workspace → code reuse & consistent versions
- Separation of concerns: SW handles data orchestration; UI pages focus on view & user interactions
- Message-driven architecture within the extension (pub/sub over chrome.runtime)
- Component-based UI with SolidJS
- Shared services in packages/utils follow a library-centric design

d. Key technologies & libraries
- SolidJS + JSX (UI components)
- Flowbite (UI kit)
- Vite (bundler) + Vitest (tests)
- TypeScript (types across repos)
- create-chrome-ext (starter)
- chrome.storage.local, chrome.runtime APIs
- ZIP.js (media export)
- PNPM workspaces

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo Root"
        Pnpm["pnpm-workspace.yaml"]:::config
        PKG["package.json & CI (.github/)"]:::config
        Docs["docs/"]:::docs
        Scripts["scripts/"]:::script
        Submit["submit/"]:::script
    end

    subgraph "Shared Utils (packages/utils)"
        U1["api/twitter.ts"]:::utils
        U2["xfetch.ts"]:::utils
        U3["db/index.ts"]:::utils
        U4["hooks/useAuth.tsx"]:::utils
        U5["storage.ts"]:::utils
    end

    subgraph "Exporter Extension"
        EE_BW["Background SW"]:::sw
        EE_CS["Content Script"]:::scriptComp
        EE_DT["DevTools Panel"]:::ui
        EE_OP["Options UI"]:::ui
        EE_MAN["Manifest Generator"]:::config
    end

    subgraph "Multi-Publish Extension"
        MP_BW["Background SW"]:::sw
        MP_CS["Content Script"]:::scriptComp
        MP_DT["DevTools Panel"]:::ui
        MP_MH["Messaging Hub"]:::scriptComp
        MP_MAN["Manifest Generator"]:::config
    end

    subgraph "X-Bookmarks Extension"
        XB_BW["Background SW"]:::sw
        XB_CS["Content Script"]:::scriptComp
        XB_DT["DevTools Panel"]:::ui
        XB_PU["Popup UI"]:::ui
        XB_OP["Options UI"]:::ui
        XB_NT["New Tab UI"]:::ui
        XB_SP["Side Panel UI"]:::ui
        XB_MAN["Manifest Generator"]:::config
    end

    subgraph "X-Bookmarks-Automation Extension"
        XA_BW["Background SW"]:::sw
        XA_CS["Content Script"]:::scriptComp
        XA_DT["DevTools Panel"]:::ui
        XA_PU["Popup UI"]:::ui
        XA_MAN["Manifest Generator"]:::config
    end

    subgraph "External Services"
        TwitterAPI["Twitter REST API"]:::external
        AIService["AI Categorization Service"]:::external
    end

    Datastore["chrome.storage.local / IndexedDB"]:::datastore

    subgraph "Build & CI/CD Pipeline"
        B1["pnpm install"]:::build
        B2["vite build"]:::build
        B3["vitest"]:::build
        B4["GitHub Actions"]:::build
    end

    %% Relationships within extensions
    EE_CS <-->|"chrome.runtime.messaging"| EE_BW
    EE_OP -->|"chrome.runtime.sendMessage"| EE_BW
    EE_DT -->|"chrome.runtime.sendMessage"| EE_BW

    MP_CS <-->|"chrome.runtime.messaging"| MP_BW
    MP_MH -->|"internal pub/sub"| MP_BW
    MP_DT -->|"chrome.runtime.sendMessage"| MP_BW

    XB_CS <-->|"chrome.runtime.messaging"| XB_BW
    XB_PU -->|"chrome.runtime.sendMessage"| XB_BW
    XB_OP -->|"chrome.runtime.sendMessage"| XB_BW
    XB_NT -->|"chrome.runtime.sendMessage"| XB_BW
    XB_SP -->|"chrome.runtime.sendMessage"| XB_BW

    XA_CS <-->|"chrome.runtime.messaging"| XA_BW
    XA_PU -->|"chrome.runtime.sendMessage"| XA_BW
    XA_DT -->|"chrome.runtime.sendMessage"| XA_BW

    %% Shared Utils reuse
    EE_BW -->|imports| U1
    EE_BW -->|imports| U2
    EE_BW -->|imports| U3
    EE_BW -->|imports| U5
    EE_OP -->|imports hooks| U4

    MP_BW -->|imports| U1
    MP_BW -->|imports| U2
    MP_BW -->|imports| U3
    MP_MH -->|imports| U5

    XB_BW -->|imports| U1
    XB_BW -->|imports| U2
    XB_BW -->|imports| U3
    XB_PU -->|imports hooks| U4

    XA_BW -->|imports| U1
    XA_BW -->|imports| U2
    XA_PU -->|imports hooks| U4

    %% External and datastore interactions
    EE_BW -->|"HTTP fetch"| TwitterAPI
    EE_BW -->|"HTTP fetch"| AIService
    EE_BW -->|"storage write/read"| Datastore

    MP_BW -->|"HTTP fetch"| TwitterAPI
    MP_BW -->|"storage write/read"| Datastore

    XB_BW -->|"HTTP fetch"| TwitterAPI
    XB_BW -->|"storage write/read"| Datastore

    XA_BW -->|"HTTP fetch"| TwitterAPI
    XA_BW -->|"storage write/read"| Datastore

    %% Build pipeline relationships
    Pnpm --> B1
    PKG --> B1
    B1 --> B2
    B2 -->|builds dist for| EE_BW
    B2 -->|builds dist for| MP_BW
    B2 -->|builds dist for| XB_BW
    B2 -->|builds dist for| XA_BW
    B2 --> B3
    B3 --> B4

    %% Click Events
    click Pnpm "https://github.com/twillot-app/twillot/blob/main/pnpm-workspace.yaml"
    click PKG "https://github.com/twillot-app/twillot/blob/main/package.json"
    click PKG "https://github.com/twillot-app/twillot/tree/main/.github/"
    click Docs "https://github.com/twillot-app/twillot/tree/main/docs/"
    click Scripts "https://github.com/twillot-app/twillot/tree/main/scripts/"
    click Submit "https://github.com/twillot-app/twillot/tree/main/submit/"
    click U1 "https://github.com/twillot-app/twillot/blob/main/packages/utils/api/twitter.ts"
    click U2 "https://github.com/twillot-app/twillot/blob/main/packages/utils/xfetch.ts"
    click U3 "https://github.com/twillot-app/twillot/blob/main/packages/utils/db/index.ts"
    click U4 "https://github.com/twillot-app/twillot/blob/main/packages/utils/hooks/useAuth.tsx"
    click U5 "https://github.com/twillot-app/twillot/blob/main/packages/utils/storage.ts"
    click EE_BW "https://github.com/twillot-app/twillot/blob/main/exporter/src/background/index.ts"
    click EE_CS "https://github.com/twillot-app/twillot/blob/main/exporter/src/contentScript/index.ts"
    click EE_DT "https://github.com/twillot-app/twillot/blob/main/exporter/src/devtools/index.tsx"
    click EE_OP "https://github.com/twillot-app/twillot/blob/main/exporter/src/options/index.tsx"
    click EE_MAN "https://github.com/twillot-app/twillot/blob/main/exporter/src/manifest.ts"
    click MP_BW "https://github.com/twillot-app/twillot/blob/main/multi-publish/src/background/index.ts"
    click MP_CS "https://github.com/twillot-app/twillot/blob/main/multi-publish/src/contentScript/index.ts"
    click MP_DT "https://github.com/twillot-app/twillot/blob/main/multi-publish/src/devtools/index.tsx"
    click MP_MH "https://github.com/twillot-app/twillot/blob/main/multi-publish/src/messaging.ts"
    click MP_MAN "https://github.com/twillot-app/twillot/blob/main/multi-publish/src/manifest.ts"
    click XB_BW "https://github.com/twillot-app/twillot/blob/main/x-bookmarks/src/background/index.ts"
    click XB_CS "https://github.com/twillot-app/twillot/blob/main/x-bookmarks/src/contentScript/index.ts"
    click XB_DT "https://github.com/twillot-app/twillot/blob/main/x-bookmarks/src/devtools/index.tsx"
    click XB_PU "https://github.com/twillot-app/twillot/blob/main/x-bookmarks/src/popup/index.tsx"
    click XB_OP "https://github.com/twillot-app/twillot/blob/main/x-bookmarks/src/options/index.tsx"
    click XB_NT "https://github.com/twillot-app/twillot/blob/main/x-bookmarks/src/newtab/index.tsx"
    click XB_SP "https://github.com/twillot-app/twillot/blob/main/x-bookmarks/src/sidepanel/index.tsx"
    click XB_MAN "https://github.com/twillot-app/twillot/blob/main/x-bookmarks/src/manifest.ts"
    click XA_BW "https://github.com/twillot-app/twillot/blob/main/x-bookmarks-automation/src/background/index.ts"
    click XA_CS "https://github.com/twillot-app/twillot/blob/main/x-bookmarks-automation/src/contentScript/index.ts"
    click XA_DT "https://github.com/twillot-app/twillot/blob/main/x-bookmarks-automation/src/devtools/index.tsx"
    click XA_PU "https://github.com/twillot-app/twillot/blob/main/x-bookmarks-automation/src/popup/index.tsx"
    click XA_MAN "https://github.com/twillot-app/twillot/blob/main/x-bookmarks-automation/src/manifest.ts"

    classDef config fill:#f9f,stroke:#333,stroke-width:1px
    classDef docs fill:#ff9,stroke:#333,stroke-width:1px
    classDef script fill:#9ff,stroke:#333,stroke-width:1px
    classDef utils fill:#cfc,stroke:#333,stroke-width:1px
    classDef sw fill:#fcf,stroke:#333,stroke-width:1px
    classDef scriptComp fill:#cff,stroke:#333,stroke-width:1px
    classDef ui fill:#ffc,stroke:#333,stroke-width:1px
    classDef external fill:#fcc,stroke:#333,stroke-width:1px
    classDef datastore fill:#ccf,stroke:#333,stroke-width:1px
    classDef build fill:#efe,stroke:#333,stroke-width:1px
```
