# haskaomni/serenity architecture

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

- Interactive diagram: https://gitdiagram.com/haskaomni/serenity
- Repository: https://github.com/haskaomni/serenity

## Overview

Serenity Signal Dashboard collects X posts, derives ticker mentions, enriches them with daily prices, and presents a local research dashboard. Its separate stock-scorer skill analyzes the same SQLite snapshot. The sampled excerpts establish ingestion, API, UI, and scoring behavior; the README documents raw JSON storage and TradingView backfill, though the backfill wiring into the database is visible only in its own script.

Main entry points: [`scripts/ingest.py`](https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py) (X request fetch), [`scripts/fetch_tv_price.py`](https://github.com/haskaomni/serenity/blob/main/scripts/fetch_tv_price.py) (TradingView backfill), [`scripts/server.py`](https://github.com/haskaomni/serenity/blob/main/scripts/server.py) (HTTP API and static server), [`skills/serenity-stock-scorer/scripts/score_serenity_stock.py`](https://github.com/haskaomni/serenity/blob/main/skills/serenity-stock-scorer/scripts/score_serenity_stock.py) (Ticker signal scorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and enrichment"]
  node_ingestion["Ingestion commands<br/>[ingest.py]"]
  node_x_fetch["X request fetch<br/>[ingest.py]"]
  node_tweet_processing["Tweet and ticker extraction<br/>[ingest.py]"]
  node_yahoo_prices["Yahoo price sync<br/>[ingest.py]"]
  node_tv_backfill["TradingView backfill<br/>[fetch_tv_price.py]"]
  node_curl_files["Copied X requests"]
end

subgraph group_storage["Local data"]
  node_sqlite[("Serenity SQLite")]
  node_raw_json["Raw X JSON"]
end

subgraph group_dashboard["Dashboard"]
  node_http_server["HTTP API and static server<br/>[server.py]"]
  node_dashboard_ui["Dashboard UI<br/>[app.js]"]
  node_dashboard_page["Dashboard page and styles<br/>[index.html]"]
end

subgraph group_analysis["Signal analysis"]
  node_scorer["Ticker signal scorer"]
  node_skill_guidance["Scoring guidance<br/>[SKILL.md]"]
end

node_operator(("Operator"))
node_x{{"X GraphQL"}}
node_yahoo{{"Yahoo chart API"}}
node_tradingview{{"TradingView"}}
node_dashboard_user(("Dashboard user"))

node_operator -->|"runs commands"| node_ingestion
node_ingestion -->|"dispatches fetch"| node_x_fetch
node_x_fetch -->|"reads requests"| node_curl_files
node_x_fetch -->|"fetches pages"| node_x
node_x_fetch -->|"passes responses"| node_tweet_processing
node_tweet_processing -->|"stores posts and mentions"| node_sqlite
node_tweet_processing -->|"stores raw responses"| node_raw_json
node_ingestion -->|"dispatches prices"| node_yahoo_prices
node_yahoo_prices -->|"writes price bars"| node_sqlite
node_yahoo_prices -->|"requests chart data"| node_yahoo
node_operator -.->|"runs backfill"| node_tv_backfill
node_tv_backfill -.->|"requests candles"| node_tradingview
node_tv_backfill -.->|"writes price bars"| node_sqlite
node_dashboard_user -->|"uses dashboard"| node_dashboard_ui
node_dashboard_ui -->|"requests API"| node_http_server
node_http_server -->|"queries data"| node_sqlite
node_http_server -->|"serves page"| node_dashboard_page
node_scorer -->|"reads snapshot"| node_sqlite
node_operator -->|"scores ticker"| node_scorer
node_skill_guidance -.->|"guides scoring"| node_scorer

click node_ingestion "https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py"
click node_x_fetch "https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py"
click node_tweet_processing "https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py"
click node_yahoo_prices "https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py"
click node_tv_backfill "https://github.com/haskaomni/serenity/blob/main/scripts/fetch_tv_price.py"
click node_curl_files "https://github.com/haskaomni/serenity/tree/main/x_curl"
click node_http_server "https://github.com/haskaomni/serenity/blob/main/scripts/server.py"
click node_dashboard_ui "https://github.com/haskaomni/serenity/blob/main/dashboard/app.js"
click node_dashboard_page "https://github.com/haskaomni/serenity/blob/main/dashboard/index.html"
click node_scorer "https://github.com/haskaomni/serenity/blob/main/skills/serenity-stock-scorer/scripts/score_serenity_stock.py"
click node_skill_guidance "https://github.com/haskaomni/serenity/blob/main/skills/serenity-stock-scorer/SKILL.md"

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_ingestion,node_x_fetch,node_tweet_processing,node_yahoo_prices,node_tv_backfill,node_curl_files,node_tradingview,node_dashboard_user toneBlue
class node_sqlite,node_raw_json toneAmber
class node_http_server,node_dashboard_ui,node_dashboard_page,node_yahoo toneMint
class node_scorer,node_skill_guidance toneRose
class node_operator,node_x toneIndigo
```

## Components

### Collection and enrichment

- [Ingestion commands](https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py): `scripts/ingest.py`
- [X request fetch](https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py): `scripts/ingest.py`
- [Tweet and ticker extraction](https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py): `scripts/ingest.py`
- [Yahoo price sync](https://github.com/haskaomni/serenity/blob/main/scripts/ingest.py): `scripts/ingest.py`
- [TradingView backfill](https://github.com/haskaomni/serenity/blob/main/scripts/fetch_tv_price.py): `scripts/fetch_tv_price.py`
- [Copied X requests](https://github.com/haskaomni/serenity/tree/main/x_curl): `x_curl`

### Local data

- **Serenity SQLite**
- **Raw X JSON**

### Dashboard

- [HTTP API and static server](https://github.com/haskaomni/serenity/blob/main/scripts/server.py): `scripts/server.py`
- [Dashboard UI](https://github.com/haskaomni/serenity/blob/main/dashboard/app.js): `dashboard/app.js`
- [Dashboard page and styles](https://github.com/haskaomni/serenity/blob/main/dashboard/index.html): `dashboard/index.html`

### Signal analysis

- [Ticker signal scorer](https://github.com/haskaomni/serenity/blob/main/skills/serenity-stock-scorer/scripts/score_serenity_stock.py): `skills/serenity-stock-scorer/scripts/score_serenity_stock.py`
- [Scoring guidance](https://github.com/haskaomni/serenity/blob/main/skills/serenity-stock-scorer/SKILL.md): `skills/serenity-stock-scorer/SKILL.md`

### Other components

- **Operator**
- **X GraphQL**
- **Yahoo chart API**
- **TradingView**
- **Dashboard user**

## Connections

- Operator → Ingestion commands: runs commands
- Ingestion commands → X request fetch: dispatches fetch
- X request fetch → Copied X requests: reads requests
- X request fetch → X GraphQL: fetches pages
- X request fetch → Tweet and ticker extraction: passes responses
- Tweet and ticker extraction → Serenity SQLite: stores posts and mentions
- Tweet and ticker extraction → Raw X JSON: stores raw responses
- Ingestion commands → Yahoo price sync: dispatches prices
- Yahoo price sync → Serenity SQLite: writes price bars
- Yahoo price sync → Yahoo chart API: requests chart data
- Operator → TradingView backfill: runs backfill
- TradingView backfill → TradingView: requests candles
- TradingView backfill → Serenity SQLite: writes price bars
- Dashboard user → Dashboard UI: uses dashboard
- Dashboard UI → HTTP API and static server: requests API
- HTTP API and static server → Serenity SQLite: queries data
- HTTP API and static server → Dashboard page and styles: serves page
- Ticker signal scorer → Serenity SQLite: reads snapshot
- Operator → Ticker signal scorer: scores ticker
- Scoring guidance → Ticker signal scorer: guides scoring