# justingore4/tiktok-live-tracker architecture

> Architecture diagram of the GitHub repository justingore4/tiktok-live-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justingore4/tiktok-live-tracker
- Repository: https://github.com/justingore4/tiktok-live-tracker

## Overview

TikTok Live Tracker is a local-only Chrome side-panel extension for capturing LIVE auction activity, mapping sales to imported inventory, reconciling stock, and saving stream reports. The main workflow runs from the tracker UI through the service worker: capture reads the visible dashboard, the user maps variations and manages inventory, and ending a session creates a report that can be reviewed or exported. The README documents presets, queues, health status, and report correction/export capabilities. Sampled excerpts confirm some storage and client behavior; links for unsampled subsystems reflect documented responsibilities, not inspected call sites.

Main entry points: [`extension/service-worker.js`](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/service-worker.js) (Service worker), [`extension/tagger/sidepanel.js`](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/sidepanel.js) (Tracker panel), [`extension/capture/content.js`](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/content.js) (Dashboard capture), [`extension/tagger/persistent-tagger-controller.js`](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/persistent-tagger-controller.js) (Tagging controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Auction capture"]
  node_capture_content["Dashboard capture<br/>[content.js]"]
  node_capture_schedule["Capture scheduling"]
  node_sale_locator["Sale detection"]
  node_variation_locator["Variation detection"]
  node_capture_client["Capture messaging<br/>[capture-client.js]"]
  node_health["Capture health"]
end

subgraph group_tagging["Inventory and tagging"]
  node_sidepanel["Tracker panel<br/>[sidepanel.js]"]
  node_tagger["Tagging controller"]
  node_mapping["Mapping workflow"]
  node_inventory_controller["Inventory import"]
  node_inventory_client["Inventory import client"]
  node_queue_client["Next-item queue"]
end

subgraph group_state["Session and state"]
  node_worker["Service worker<br/>[service-worker.js]"]
  node_session_client["Session client"]
  node_session_state["Stream session<br/>[stream-session.js]"]
  node_reconciliation["Sales reconciliation<br/>[reconciliation.js]"]
  node_reconciliation_store[("Reconciliation storage")]
  node_session_store[("Session storage")]
  node_queue_store[("Queue storage")]
end

subgraph group_reports["Reports"]
  node_report_client["Report client"]
  node_report_page["Report review<br/>[report-page.js]"]
  node_report_download["Report export"]
  node_report_pdf["PDF export<br/>[report-pdf.js]"]
  node_report_store[("Saved reports")]
end

subgraph group_integrations["External integrations"]
  node_dashboard["TikTok dashboard"]
  node_sheets[("Google Sheets")]
  node_chrome_storage[("Chrome storage")]
end

node_user(("Tracker user"))

node_user -->|"operates"| node_sidepanel
node_dashboard -->|"provides visible activity"| node_capture_content
node_capture_content -->|"schedules capture"| node_capture_schedule
node_capture_content -->|"detects sales"| node_sale_locator
node_capture_content -->|"detects variations"| node_variation_locator
node_capture_content -->|"reports observations"| node_capture_client
node_capture_client -->|"sends events"| node_worker
node_worker -->|"updates sales state"| node_reconciliation
node_sidepanel -->|"controls mapping"| node_tagger
node_tagger -->|"creates mapping"| node_mapping
node_tagger -->|"requests tracker state"| node_worker
node_sidepanel -->|"manages import"| node_inventory_controller
node_inventory_controller -->|"requests preview and confirm"| node_inventory_client
node_inventory_client -->|"sends import commands"| node_worker
node_worker -.->|"reads inventory"| node_sheets
node_sidepanel -->|"manages queued item"| node_queue_client
node_queue_client -->|"sends queue commands"| node_worker
node_worker -->|"starts and ends session"| node_session_state
node_sidepanel -->|"requests session actions"| node_session_client
node_session_client -->|"sends session commands"| node_worker
node_worker -->|"loads and saves session"| node_session_store
node_worker -->|"loads and saves state"| node_reconciliation_store
node_worker -->|"loads and saves queue"| node_queue_store
node_session_store -->|"reads and writes"| node_chrome_storage
node_reconciliation_store -->|"reads and writes"| node_chrome_storage
node_queue_store -->|"reads and writes"| node_chrome_storage
node_worker -->|"saves finalized reports"| node_report_store
node_report_store -->|"reads and writes"| node_chrome_storage
node_sidepanel -->|"opens report actions"| node_report_client
node_report_page -->|"requests report data"| node_report_client
node_report_client -->|"sends report commands"| node_worker
node_report_page -->|"exports report"| node_report_download
node_report_download -->|"creates PDF"| node_report_pdf
node_worker -->|"records capture status"| node_health

click node_worker "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/service-worker.js"
click node_capture_content "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/content.js"
click node_capture_schedule "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/capture-scheduler.js"
click node_sale_locator "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/sale-candidate-locator.js"
click node_variation_locator "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/bidding-variation-locator.js"
click node_capture_client "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/capture-client.js"
click node_sidepanel "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/sidepanel.js"
click node_tagger "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/persistent-tagger-controller.js"
click node_mapping "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/mapping-workflow.js"
click node_inventory_controller "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/inventory-import-controller.js"
click node_inventory_client "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/inventory-import-client.js"
click node_queue_client "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/next-item-queue-client.js"
click node_session_client "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/stream-session-client.js"
click node_session_state "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/stream-session.js"
click node_reconciliation "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/reconciliation.js"
click node_reconciliation_store "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/reconciliation-storage.js"
click node_session_store "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/stream-session-storage.js"
click node_queue_store "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/next-item-queue-storage.js"
click node_report_client "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/report/stream-report-client.js"
click node_report_page "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/report/report-page.js"
click node_report_download "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/report/report-downloads.js"
click node_report_pdf "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/report/report-pdf.js"
click node_report_store "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/stream-report-storage.js"
click node_health "https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/capture-health-reporter.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_capture_content,node_capture_schedule,node_sale_locator,node_variation_locator,node_capture_client,node_health,node_user toneBlue
class node_sidepanel,node_tagger,node_mapping,node_inventory_controller,node_inventory_client,node_queue_client toneAmber
class node_worker,node_session_client,node_session_state,node_reconciliation,node_reconciliation_store,node_session_store,node_queue_store toneMint
class node_report_client,node_report_page,node_report_download,node_report_pdf,node_report_store toneRose
class node_dashboard,node_sheets,node_chrome_storage toneIndigo
```

## Components

### Auction capture

- [Dashboard capture](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/content.js): `extension/capture/content.js`
- [Capture scheduling](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/capture-scheduler.js): `extension/capture/capture-scheduler.js`
- [Sale detection](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/sale-candidate-locator.js): `extension/capture/sale-candidate-locator.js`
- [Variation detection](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/bidding-variation-locator.js): `extension/capture/bidding-variation-locator.js`
- [Capture messaging](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/capture-client.js): `extension/capture/capture-client.js`
- [Capture health](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/capture/capture-health-reporter.js): `extension/capture/capture-health-reporter.js`

### Inventory and tagging

- [Tracker panel](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/sidepanel.js): `extension/tagger/sidepanel.js`
- [Tagging controller](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/persistent-tagger-controller.js): `extension/tagger/persistent-tagger-controller.js`
- [Mapping workflow](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/mapping-workflow.js): `extension/tagger/mapping-workflow.js`
- [Inventory import](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/inventory-import-controller.js): `extension/tagger/inventory-import-controller.js`
- [Inventory import client](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/inventory-import-client.js): `extension/tagger/inventory-import-client.js`
- [Next-item queue](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/next-item-queue-client.js): `extension/tagger/next-item-queue-client.js`

### Session and state

- [Service worker](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/service-worker.js): `extension/service-worker.js`
- [Session client](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/tagger/stream-session-client.js): `extension/tagger/stream-session-client.js`
- [Stream session](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/stream-session.js): `extension/shared/stream-session.js`
- [Sales reconciliation](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/reconciliation.js): `extension/shared/reconciliation.js`
- [Reconciliation storage](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/reconciliation-storage.js): `extension/shared/reconciliation-storage.js`
- [Session storage](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/stream-session-storage.js): `extension/shared/stream-session-storage.js`
- [Queue storage](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/next-item-queue-storage.js): `extension/shared/next-item-queue-storage.js`

### Reports

- [Report client](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/report/stream-report-client.js): `extension/report/stream-report-client.js`
- [Report review](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/report/report-page.js): `extension/report/report-page.js`
- [Report export](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/report/report-downloads.js): `extension/report/report-downloads.js`
- [PDF export](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/report/report-pdf.js): `extension/report/report-pdf.js`
- [Saved reports](https://github.com/justingore4/tiktok-live-tracker/blob/main/extension/shared/stream-report-storage.js): `extension/shared/stream-report-storage.js`

### External integrations

- **TikTok dashboard**
- **Google Sheets**
- **Chrome storage**

### Other components

- **Tracker user**

## Connections

- Tracker user → Tracker panel: operates
- TikTok dashboard → Dashboard capture: provides visible activity
- Dashboard capture → Capture scheduling: schedules capture
- Dashboard capture → Sale detection: detects sales
- Dashboard capture → Variation detection: detects variations
- Dashboard capture → Capture messaging: reports observations
- Capture messaging → Service worker: sends events
- Service worker → Sales reconciliation: updates sales state
- Tracker panel → Tagging controller: controls mapping
- Tagging controller → Mapping workflow: creates mapping
- Tagging controller → Service worker: requests tracker state
- Tracker panel → Inventory import: manages import
- Inventory import → Inventory import client: requests preview and confirm
- Inventory import client → Service worker: sends import commands
- Service worker → Google Sheets: reads inventory
- Tracker panel → Next-item queue: manages queued item
- Next-item queue → Service worker: sends queue commands
- Service worker → Stream session: starts and ends session
- Tracker panel → Session client: requests session actions
- Session client → Service worker: sends session commands
- Service worker → Session storage: loads and saves session
- Service worker → Reconciliation storage: loads and saves state
- Service worker → Queue storage: loads and saves queue
- Session storage → Chrome storage: reads and writes
- Reconciliation storage → Chrome storage: reads and writes
- Queue storage → Chrome storage: reads and writes
- Service worker → Saved reports: saves finalized reports
- Saved reports → Chrome storage: reads and writes
- Tracker panel → Report client: opens report actions
- Report review → Report client: requests report data
- Report client → Service worker: sends report commands
- Report review → Report export: exports report
- Report export → PDF export: creates PDF
- Service worker → Capture health: records capture status