# i3t4an/yaktrace architecture

> Architecture diagram of the GitHub repository i3t4an/yaktrace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/i3t4an/yaktrace
- Repository: https://github.com/i3t4an/yaktrace

## Overview

YakTrace is a local research tool that captures one locked historical feed window, repeats captures after hiding post sources, and produces a PDF dossier from differences between consecutive snapshots. The CLI owns authentication, group selection, window locking, hide/unhide actions, and workflow sequencing; the collector retrieves paged feeds, while the SQLite database stores capture evidence and builds the report model. The excerpts show the main module relationships, but do not expose the connector implementation or all report-model details.

Main entry points: [`YakTrace/src/cli.js`](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js) (Workflow CLI), [`YakTrace/src/SnapshotCollector.js`](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/SnapshotCollector.js) (Snapshot collector), [`YakTrace/src/AnalyticsDatabase.js`](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js) (SQLite evidence store), [`sidechat.js/dist/index.mjs`](https://github.com/i3t4an/yaktrace/blob/main/sidechat.js/dist/index.mjs) (Sidechat API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Capture workflow"]
  node_cli["Workflow CLI<br/>[cli.js]"]
  node_auth["Account authentication<br/>[cli.js]"]
  node_group["Group selection<br/>[cli.js]"]
  node_sourceactions["Source hide actions<br/>[cli.js]"]
end

subgraph group_collection["Feed collection"]
  node_connector["Sidechat API client<br/>[index.mjs]"]
  node_collector["Snapshot collector"]
  node_window["Fixed UTC window"]
end

subgraph group_evidence["Evidence store"]
  node_database[("SQLite evidence store")]
  node_snapshots["Snapshot records"]
  node_rawresponses["Raw feed responses"]
  node_diffs["Parent-child differences"]
  node_personal["Final self-post capture"]
end

subgraph group_reporting["Dossier reporting"]
  node_pdf["PDF dossier generator<br/>[PdfReport.js]"]
end

node_operator(("Operator"))
node_yikyak{{"YikYak service"}}

node_operator -->|"runs commands"| node_cli
node_cli -->|"authenticates"| node_auth
node_cli -->|"selects group"| node_group
node_cli -->|"hides and unhides"| node_sourceactions
node_cli -->|"starts captures"| node_collector
node_cli -->|"reads and clears"| node_database
node_cli -->|"generates report"| node_pdf
node_auth -->|"uses client"| node_connector
node_group -->|"fetches memberships"| node_connector
node_sourceactions -->|"changes hidden sources"| node_connector
node_collector -->|"fetches feed pages"| node_connector
node_collector -->|"filters by time"| node_window
node_collector -->|"records captures"| node_database
node_collector -->|"updates progress"| node_snapshots
node_collector -->|"saves page payloads"| node_rawresponses
node_database -->|"computes report groups"| node_diffs
node_database -->|"selects self posts"| node_personal
node_pdf -->|"loads report model"| node_database
node_connector -.->|"calls service"| node_yikyak

click node_cli "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js"
click node_auth "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js"
click node_group "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js"
click node_sourceactions "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js"
click node_connector "https://github.com/i3t4an/yaktrace/blob/main/sidechat.js/dist/index.mjs"
click node_collector "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/SnapshotCollector.js"
click node_window "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/SnapshotCollector.js"
click node_database "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js"
click node_snapshots "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js"
click node_rawresponses "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js"
click node_diffs "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js"
click node_personal "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js"
click node_pdf "https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/PdfReport.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_cli,node_auth,node_group,node_sourceactions toneBlue
class node_connector,node_collector,node_window toneAmber
class node_database,node_snapshots,node_rawresponses,node_diffs,node_personal toneMint
class node_pdf toneRose
class node_operator,node_yikyak toneIndigo
```

## Components

### Capture workflow

- [Workflow CLI](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js): `YakTrace/src/cli.js`
- [Account authentication](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js): `YakTrace/src/cli.js`
- [Group selection](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js): `YakTrace/src/cli.js`
- [Source hide actions](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/cli.js): `YakTrace/src/cli.js`

### Feed collection

- [Sidechat API client](https://github.com/i3t4an/yaktrace/blob/main/sidechat.js/dist/index.mjs): `sidechat.js/dist/index.mjs`
- [Snapshot collector](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/SnapshotCollector.js): `YakTrace/src/SnapshotCollector.js`
- [Fixed UTC window](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/SnapshotCollector.js): `YakTrace/src/SnapshotCollector.js`

### Evidence store

- [SQLite evidence store](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js): `YakTrace/src/AnalyticsDatabase.js`
- [Snapshot records](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js): `YakTrace/src/AnalyticsDatabase.js`
- [Raw feed responses](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js): `YakTrace/src/AnalyticsDatabase.js`
- [Parent-child differences](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js): `YakTrace/src/AnalyticsDatabase.js`
- [Final self-post capture](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/AnalyticsDatabase.js): `YakTrace/src/AnalyticsDatabase.js`

### Dossier reporting

- [PDF dossier generator](https://github.com/i3t4an/yaktrace/blob/main/YakTrace/src/PdfReport.js): `YakTrace/src/PdfReport.js`

### Other components

- **Operator**
- **YikYak service**

## Connections

- Operator → Workflow CLI: runs commands (evidence: `README.md`)
- Workflow CLI → Account authentication: authenticates (evidence: `YakTrace/src/cli.js`)
- Workflow CLI → Group selection: selects group (evidence: `YakTrace/src/cli.js`)
- Workflow CLI → Source hide actions: hides and unhides (evidence: `YakTrace/src/cli.js`)
- Workflow CLI → Snapshot collector: starts captures (evidence: `YakTrace/src/cli.js`)
- Workflow CLI → SQLite evidence store: reads and clears (evidence: `YakTrace/src/cli.js`)
- Workflow CLI → PDF dossier generator: generates report (evidence: `YakTrace/src/cli.js`)
- Account authentication → Sidechat API client: uses client (evidence: `YakTrace/src/cli.js`)
- Group selection → Sidechat API client: fetches memberships (evidence: `YakTrace/src/cli.js`)
- Source hide actions → Sidechat API client: changes hidden sources (evidence: `YakTrace/src/cli.js`)
- Snapshot collector → Sidechat API client: fetches feed pages (evidence: `YakTrace/src/SnapshotCollector.js`)
- Snapshot collector → Fixed UTC window: filters by time (evidence: `YakTrace/src/SnapshotCollector.js`)
- Snapshot collector → SQLite evidence store: records captures (evidence: `YakTrace/src/SnapshotCollector.js`)
- Snapshot collector → Snapshot records: updates progress (evidence: `YakTrace/src/SnapshotCollector.js`)
- Snapshot collector → Raw feed responses: saves page payloads (evidence: `YakTrace/src/SnapshotCollector.js`)
- SQLite evidence store → Parent-child differences: computes report groups (evidence: `YakTrace/src/AnalyticsDatabase.js`)
- SQLite evidence store → Final self-post capture: selects self posts (evidence: `YakTrace/src/AnalyticsDatabase.js`)
- PDF dossier generator → SQLite evidence store: loads report model (evidence: `YakTrace/src/PdfReport.js`)
- Sidechat API client → YikYak service: calls service