# atmoner/twitwork architecture

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

- Interactive diagram: https://gitdiagram.com/atmoner/twitwork
- Repository: https://github.com/atmoner/twitwork

## Overview

##### Project type and purpose
- From the README and file structure, TwitWork is an Electron‑based desktop application (Node.js + Chromium) for real‑time Twitter stream monitoring and graph‑based hashtag visualization. It connects directly to the Twitter Streaming API, filters tweets by keywords or mentions, builds a node/edge graph of hashtag relationships, and renders this in the UI.

##### File structure
Top‑level files and directories:
- package.json – Lists dependencies (Electron, Twitter client libs, graphing libs) and scripts (npm start).
- main.js – Electron “main” process entry point; sets up the BrowserWindow, menus, IPC channels, and application lifecycle.
- renderer.js & js/ folder – Frontend code running in the “renderer” process (the Chromium browser context). Responsible for DOM manipulation, user interactions, and graph rendering.
- css/ & index.html – UI styling and markup.
- lib/menu.js – Modular definition of the native application menu (File → Save, Edit API Key, Settings).
- lib/network.js – Encapsulates network logic: authentication with Twitter API, opening the streaming connection, filtering tweets, emitting events with tweet data.
- .github, SECURITY.md, LICENSE, README.md – Repo metadata and documentation.

##### Extract architectural insights from the README
- No remote backend; all logic runs locally in two Electron processes with direct Twitter API calls.
- Core features: keyword‐based streaming, hashtag extraction, dynamic graph updates, export/save functionality.
- Distribution targets: Windows, macOS, Linux binaries.

a. Electron Main Process (Node.js)
- Initializes app, window, menus (lib/menu.js).
- Manages IPC (inter‐process communication) with renderer.
- Handles file I/O (save/export).
b. Electron Renderer Process (Chromium)
- Renders index.html, applies CSS, runs renderer.js + js/* for UI.
- Receives tweet events from main or network module via IPC or direct require.
- Drives the graph visualization component.
c. Network Module (lib/network.js)
- Authenticates and opens Twitter Streaming API connection.
- Emits parsed tweet objects (with hashtags) back to main or renderer.
d. Data Flow & Storage
- In‐memory streaming data → graph data structure → UI updates.
- File system for saving session exports (JSON, CSV, image).
e. External Service
- Twitter Streaming API (via HTTPS / secure WebSockets).

##### Relationships and interactions
- The Main Process loads the UI and establishes IPC channels.
- Network Module (in main or renderer process) maintains the Twitter stream, pushes data to the Renderer via IPC or direct function calls.
- Renderer updates the graph in real time and listens for user actions from the menu (triggered by Main Process).
- Save/Export actions flow from Renderer → Main → File system.

##### Architectural patterns and design principles
- Process Separation: Clear boundary between Main (application logic, native OS integration) and Renderer (UI & visualization).
- Event‑Driven Communication: IPC channels carry “tweet‑received,” “start‑stream,” “stop‑stream,” “save‑file” events.
- Modularization: menu.js and network.js encapsulate distinct responsibilities.

##### Relevant technologies, frameworks, and libraries
- Electron (Chromium + Node.js)
- Node.js native modules for HTTP/HTTPS streaming
- Twitter API client library (in lib/network.js)
- D3.js or another graphing library (implied by js/*)
- HTML5/CSS3 for UI layout and styling

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Main Process"
        A1["Main Process / Node.js"]:::main
        MenuModule["Menu Module"]:::module
        IPCServer["IPC Server"]:::module
        NetModule["Network Module"]:::module
        FileSystem["File System"]:::storage
    end

    subgraph "Renderer Process"
        B1["Renderer Process / Chromium"]:::main
        UIComponents["UI Components"]:::module
        GraphRenderer["Graph Renderer"]:::module
        IPClient["IPC Client"]:::module
        Markup["index.html"]:::resource
        Styling["css/"]:::resource
        UIScripts["js/"]:::resource
    end

    ExternalAPI["Twitter Streaming API"]:::external
    Config["package.json"]:::resource

    ExternalAPI -->|"stream-tweets"| NetModule
    A1 -->|"initialize-app"| B1
    A1 --> Config
    NetModule -->|"tweet-received"| IPCServer
    IPCServer -->|"tweet-received"| IPClient
    IPClient --> UIComponents
    UIComponents --> GraphRenderer
    UIComponents -->|"save-file"| IPClient
    IPClient -->|"save-file"| IPCServer
    IPCServer --> FileSystem

    click A1 "https://github.com/atmoner/twitwork/blob/master/main.js"
    click MenuModule "https://github.com/atmoner/twitwork/blob/master/lib/menu.js"
    click NetModule "https://github.com/atmoner/twitwork/blob/master/lib/network.js"
    click B1 "https://github.com/atmoner/twitwork/blob/master/renderer.js"
    click UIScripts "https://github.com/atmoner/twitwork/tree/master/js/"
    click Markup "https://github.com/atmoner/twitwork/blob/master/index.html"
    click Styling "https://github.com/atmoner/twitwork/tree/master/css/"
    click Config "https://github.com/atmoner/twitwork/blob/master/package.json"

    classDef main fill:#D0E6FF,stroke:#0366d6,color:#000;
    classDef module fill:#DFFFE0,stroke:#228B22,color:#000;
    classDef external fill:#FFEFD5,stroke:#FF8C00,color:#000;
    classDef storage fill:#EFEFEF,stroke:#808080,color:#000;
    classDef resource fill:#FFF0F5,stroke:#C71585,color:#000;
```
