# prielkrishtal/filingbot architecture

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

- Interactive diagram: https://gitdiagram.com/prielkrishtal/filingbot
- Repository: https://github.com/prielkrishtal/filingbot

## Overview

FilingBot turns SEC Form 4 filings into classified insider-trading alerts and offers Telegram users report-based Q&A. The documented pipeline runs from scheduled EDGAR polling and XML parsing, through persisted filings and LLM classification, to optional 10-Q enrichment and Telegram notification; the bot also supports on-demand RAG Q&A. The sampled code shows ingestion, classification, notification, shared persistence, and Redis Streams. Enrichment and vector indexing are documented capabilities but their implementation is not present in the supplied tree, so those links are documented rather than source-verified.

Main entry points: [`workers/classification/main.py`](https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/main.py) (Classification worker), [`ingestion/edgar_poller.py`](https://github.com/prielkrishtal/filingbot/blob/main/ingestion/edgar_poller.py) (EDGAR poller), [`core/database/models.py`](https://github.com/prielkrishtal/filingbot/blob/main/core/database/models.py) (PostgreSQL), [`core/redis_client.py`](https://github.com/prielkrishtal/filingbot/blob/main/core/redis_client.py) (Redis Streams)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Filing ingestion"]
  node_scheduler["Poll scheduler<br/>[main.py]"]
  node_poller["EDGAR poller<br/>[edgar_poller.py]"]
  node_parser["Form 4 parser<br/>[form4_parser.py]"]
  node_rate_limit["Request throttling<br/>[rate_limiter.py]"]
  node_ingest_handler["Filing persistence<br/>[main.py]"]
end

subgraph group_classification["Signal classification"]
  node_classifier_worker["Classification worker<br/>[main.py]"]
  node_history["Insider history<br/>[history_service.py]"]
  node_classifier["LLM classifier<br/>[classifier.py]"]
  node_prompts["Classification prompts<br/>[prompts.py]"]
end

subgraph group_enrichment["Report enrichment"]
  node_enrichment_worker["10-Q enrichment"]
  node_vector_store[("Company report index")]
end

subgraph group_delivery["Alerts and Q&amp;A"]
  node_notification_worker["Notification worker<br/>[main.py]"]
  node_message_builder["Alert formatting<br/>[message_builder.py]"]
  node_telegram_bot["Telegram bot<br/>[commands.py]"]
end

subgraph group_shared["Shared infrastructure"]
  node_database[("PostgreSQL<br/>[models.py]")]
  node_redis["Redis Streams<br/>[redis_client.py]"]
  node_schemas["Filing schemas<br/>[filing.py]"]
  node_enums["Domain enums<br/>[enums.py]"]
  node_config["Service configuration<br/>[config.py]"]
  node_logging["Structured logging<br/>[logging_config.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_ticker_directory["Ticker directory"]
end

node_sec(("SEC EDGAR"))
node_telegram_users(("Telegram users"))
node_telegram_service["Telegram API"]
node_groq["Groq API"]

node_scheduler -->|"polls"| node_poller
node_poller -->|"fetches filings"| node_sec
node_poller -->|"throttles requests"| node_rate_limit
node_poller -->|"parses XML"| node_parser
node_poller -->|"returns filings"| node_schemas
node_ingest_handler -->|"requests filings"| node_poller
node_ingest_handler -->|"stores filings"| node_database
node_ingest_handler -->|"publishes raw"| node_redis
node_classifier_worker -->|"consumes raw"| node_redis
node_classifier_worker -->|"loads and updates"| node_database
node_classifier_worker -->|"loads history"| node_history
node_history -->|"queries filings"| node_database
node_classifier_worker -->|"classifies filing"| node_classifier
node_classifier -->|"uses prompts"| node_prompts
node_classifier -.->|"requests classification"| node_groq
node_classifier_worker -->|"publishes classified"| node_redis
node_classifier_worker -->|"validates filing"| node_schemas
node_classifier_worker -->|"sets pipeline status"| node_enums
node_enrichment_worker -.->|"indexes reports"| node_vector_store
node_enrichment_worker -.->|"downloads 10-Q"| node_sec
node_notification_worker -->|"consumes classified"| node_redis
node_notification_worker -->|"loads users and filing"| node_database
node_notification_worker -->|"builds alert"| node_message_builder
node_notification_worker -->|"sends messages"| node_telegram_service
node_telegram_users -.->|"asks questions"| node_telegram_bot
node_telegram_bot -.->|"queries report index"| node_vector_store
node_telegram_bot -->|"reads user data"| node_database
node_telegram_bot -->|"looks up tickers"| node_ticker_directory
node_telegram_service -->|"delivers alerts"| node_telegram_users
node_db_session -->|"configures connection"| node_config
node_database -->|"uses base model"| node_db_session
node_redis -->|"configures client"| node_config
node_redis -->|"logs events"| node_logging
node_poller -->|"loads SEC settings"| node_config
node_schemas -->|"uses domain enums"| node_enums
node_database -->|"stores statuses"| node_enums

click node_scheduler "https://github.com/prielkrishtal/filingbot/blob/main/ingestion/main.py"
click node_poller "https://github.com/prielkrishtal/filingbot/blob/main/ingestion/edgar_poller.py"
click node_parser "https://github.com/prielkrishtal/filingbot/blob/main/ingestion/form4_parser.py"
click node_rate_limit "https://github.com/prielkrishtal/filingbot/blob/main/ingestion/rate_limiter.py"
click node_ingest_handler "https://github.com/prielkrishtal/filingbot/blob/main/ingestion/main.py"
click node_classifier_worker "https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/main.py"
click node_history "https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/history_service.py"
click node_classifier "https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/classifier.py"
click node_prompts "https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/prompts.py"
click node_enrichment_worker "https://github.com/prielkrishtal/filingbot/tree/main/workers/enrichment"
click node_vector_store "https://github.com/prielkrishtal/filingbot/tree/main/workers/enrichment"
click node_notification_worker "https://github.com/prielkrishtal/filingbot/blob/main/workers/notification/main.py"
click node_message_builder "https://github.com/prielkrishtal/filingbot/blob/main/workers/notification/message_builder.py"
click node_telegram_bot "https://github.com/prielkrishtal/filingbot/blob/main/telegram_bot/handlers/commands.py"
click node_database "https://github.com/prielkrishtal/filingbot/blob/main/core/database/models.py"
click node_redis "https://github.com/prielkrishtal/filingbot/blob/main/core/redis_client.py"
click node_schemas "https://github.com/prielkrishtal/filingbot/blob/main/core/schemas/filing.py"
click node_enums "https://github.com/prielkrishtal/filingbot/blob/main/core/schemas/enums.py"
click node_config "https://github.com/prielkrishtal/filingbot/blob/main/core/config.py"
click node_logging "https://github.com/prielkrishtal/filingbot/blob/main/core/logging_config.py"
click node_db_session "https://github.com/prielkrishtal/filingbot/blob/main/core/database/session.py"
click node_ticker_directory "https://github.com/prielkrishtal/filingbot/blob/main/core/ticker_directory.py"

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_scheduler,node_poller,node_parser,node_rate_limit,node_ingest_handler,node_telegram_users toneBlue
class node_classifier_worker,node_history,node_classifier,node_prompts toneAmber
class node_enrichment_worker,node_vector_store,node_telegram_service,node_groq toneMint
class node_notification_worker,node_message_builder,node_telegram_bot toneRose
class node_database,node_redis,node_schemas,node_enums,node_config,node_logging,node_db_session,node_ticker_directory,node_sec toneIndigo
```

## Components

### Filing ingestion

- [Poll scheduler](https://github.com/prielkrishtal/filingbot/blob/main/ingestion/main.py): `ingestion/main.py`
- [EDGAR poller](https://github.com/prielkrishtal/filingbot/blob/main/ingestion/edgar_poller.py): `ingestion/edgar_poller.py`
- [Form 4 parser](https://github.com/prielkrishtal/filingbot/blob/main/ingestion/form4_parser.py): `ingestion/form4_parser.py`
- [Request throttling](https://github.com/prielkrishtal/filingbot/blob/main/ingestion/rate_limiter.py): `ingestion/rate_limiter.py`
- [Filing persistence](https://github.com/prielkrishtal/filingbot/blob/main/ingestion/main.py): `ingestion/main.py`

### Signal classification

- [Classification worker](https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/main.py): `workers/classification/main.py`
- [Insider history](https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/history_service.py): `workers/classification/history_service.py`
- [LLM classifier](https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/classifier.py): `workers/classification/classifier.py`
- [Classification prompts](https://github.com/prielkrishtal/filingbot/blob/main/workers/classification/prompts.py): `workers/classification/prompts.py`

### Report enrichment

- [10-Q enrichment](https://github.com/prielkrishtal/filingbot/tree/main/workers/enrichment): `workers/enrichment`
- [Company report index](https://github.com/prielkrishtal/filingbot/tree/main/workers/enrichment): `workers/enrichment`

### Alerts and Q&A

- [Notification worker](https://github.com/prielkrishtal/filingbot/blob/main/workers/notification/main.py): `workers/notification/main.py`
- [Alert formatting](https://github.com/prielkrishtal/filingbot/blob/main/workers/notification/message_builder.py): `workers/notification/message_builder.py`
- [Telegram bot](https://github.com/prielkrishtal/filingbot/blob/main/telegram_bot/handlers/commands.py): `telegram_bot/handlers/commands.py`

### Shared infrastructure

- [PostgreSQL](https://github.com/prielkrishtal/filingbot/blob/main/core/database/models.py): `core/database/models.py`
- [Redis Streams](https://github.com/prielkrishtal/filingbot/blob/main/core/redis_client.py): `core/redis_client.py`
- [Filing schemas](https://github.com/prielkrishtal/filingbot/blob/main/core/schemas/filing.py): `core/schemas/filing.py`
- [Domain enums](https://github.com/prielkrishtal/filingbot/blob/main/core/schemas/enums.py): `core/schemas/enums.py`
- [Service configuration](https://github.com/prielkrishtal/filingbot/blob/main/core/config.py): `core/config.py`
- [Structured logging](https://github.com/prielkrishtal/filingbot/blob/main/core/logging_config.py): `core/logging_config.py`
- [Database sessions](https://github.com/prielkrishtal/filingbot/blob/main/core/database/session.py): `core/database/session.py`
- [Ticker directory](https://github.com/prielkrishtal/filingbot/blob/main/core/ticker_directory.py): `core/ticker_directory.py`

### Other components

- **SEC EDGAR**
- **Telegram users**
- **Telegram API**
- **Groq API**

## Connections

- Poll scheduler → EDGAR poller: polls (evidence: `ingestion/main.py`)
- EDGAR poller → SEC EDGAR: fetches filings (evidence: `README.md`)
- EDGAR poller → Request throttling: throttles requests (evidence: `ingestion/edgar_poller.py`)
- EDGAR poller → Form 4 parser: parses XML (evidence: `ingestion/edgar_poller.py`)
- EDGAR poller → Filing schemas: returns filings (evidence: `ingestion/edgar_poller.py`)
- Filing persistence → EDGAR poller: requests filings (evidence: `ingestion/main.py`)
- Filing persistence → PostgreSQL: stores filings (evidence: `ingestion/main.py`)
- Filing persistence → Redis Streams: publishes raw (evidence: `ingestion/main.py`)
- Classification worker → Redis Streams: consumes raw (evidence: `workers/classification/main.py`)
- Classification worker → PostgreSQL: loads and updates (evidence: `workers/classification/main.py`)
- Classification worker → Insider history: loads history (evidence: `workers/classification/main.py`)
- Insider history → PostgreSQL: queries filings (evidence: `workers/classification/history_service.py`)
- Classification worker → LLM classifier: classifies filing (evidence: `workers/classification/main.py`)
- LLM classifier → Classification prompts: uses prompts (evidence: `workers/classification/classifier.py`)
- LLM classifier → Groq API: requests classification (evidence: `README.md`)
- Classification worker → Redis Streams: publishes classified (evidence: `workers/classification/main.py`)
- Classification worker → Filing schemas: validates filing (evidence: `workers/classification/main.py`)
- Classification worker → Domain enums: sets pipeline status (evidence: `workers/classification/main.py`)
- 10-Q enrichment → Company report index: indexes reports (evidence: `README.md`)
- 10-Q enrichment → SEC EDGAR: downloads 10-Q (evidence: `README.md`)
- Notification worker → Redis Streams: consumes classified (evidence: `workers/notification/main.py`)
- Notification worker → PostgreSQL: loads users and filing (evidence: `workers/notification/main.py`)
- Notification worker → Alert formatting: builds alert (evidence: `workers/notification/main.py`)
- Notification worker → Telegram API: sends messages (evidence: `workers/notification/main.py`)
- Telegram users → Telegram bot: asks questions (evidence: `README.md`)
- Telegram bot → Company report index: queries report index (evidence: `README.md`)
- Telegram bot → PostgreSQL: reads user data (evidence: `telegram_bot/handlers/commands.py`)
- Telegram bot → Ticker directory: looks up tickers (evidence: `telegram_bot/handlers/commands.py`)
- Telegram API → Telegram users: delivers alerts (evidence: `README.md`)
- Database sessions → Service configuration: configures connection (evidence: `core/database/session.py`)
- PostgreSQL → Database sessions: uses base model (evidence: `core/database/models.py`)
- Redis Streams → Service configuration: configures client (evidence: `core/redis_client.py`)
- Redis Streams → Structured logging: logs events (evidence: `core/redis_client.py`)
- EDGAR poller → Service configuration: loads SEC settings (evidence: `ingestion/edgar_poller.py`)
- Filing schemas → Domain enums: uses domain enums (evidence: `core/schemas/filing.py`)
- PostgreSQL → Domain enums: stores statuses (evidence: `core/database/models.py`)