# andersonvc/alpha-pulse architecture

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

- Interactive diagram: https://gitdiagram.com/andersonvc/alpha-pulse
- Repository: https://github.com/andersonvc/alpha-pulse

## Overview

##### Project type and purpose
- This is a backend‐focused data‐processing pipeline (an “agent system”) that automates retrieval, parsing, and structuring of SEC 8‐K filings using LLMs. It is not a full‐stack web app but rather a CLI/orchestrated workflow tool that integrates with external APIs (SEC EDGAR, Polygon, OpenAI).

##### File structure
- Top‐level scripts/ directory: contains executable entry points (`run_workflow`, `run_edgar_query`, etc.).
- src/alpha_pulse/:
- agent_workflows/: high-level workflow definitions (e.g., `doc_analyzer.py`, `parse_8k_502.py`).
- agents/: LLM-driven “agent” implementations specialized for EDGAR filings and news.
- clients/: low-level HTTP clients for SEC EDGAR and Polygon, plus rate limiting.
- graphs/: orchestration layer that ties clients and agents into end‐to‐end pipelines.
- storage/: persistence layer (DB clients, schema, publisher modules).
- tools/: utility functions for news and polygon-specific logic.
- types/: Pydantic/TypedDict definitions modeling filings and DB tables.
- Configuration: `requirements.txt`, `pyproject.toml`, `placeholder.env`.
- Tests in tests/: unit tests for agents, clients, storage.

##### README for additional insights
- Confirms key workflows: fetch 8‐K, parse items with LLM, output structured JSON.
- Mentions “agent system,” “LLM‐Powered Understanding,” “Automatic EDGAR Integration.”

##### Elements
- Blue for external services
- Green for client modules
- Yellow for agent/workflow modules
- Orange for storage/persistence
- Rectangles for code modules
- Clouds for external APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        SEC_API["SEC EDGAR API/RSS"]:::external
        POLY_API["Polygon News API"]:::external
        OPENAI_API["OpenAI API"]:::external
    end

    %% Data Acquisition Layer
    subgraph "Data Acquisition Layer"
        direction TB
        EdgarClient["EdgarClient"]:::clients
        FilingDownloader["FilingDownloader"]:::clients
        RateLimiterSEC["RateLimiter (SEC)"]:::clients
        PolygonClient["PolygonClient"]:::clients
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        RunWorkflow["run_workflow"]:::workflow
        RunEdgarQuery["run_edgar_query"]:::workflow
        RunNewsAgent["run_news_agent"]:::workflow
        Draw8KWorkflow["draw_8k_workflow"]:::workflow
        EdgarGraph["edgar_8k_workflow"]:::workflow
        NewsGraph["news_analysis_graph"]:::workflow
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        DocAnalyzer["doc_analyzer"]:::workflow
        Parse8K502["parse_8k_502"]:::workflow
        Item801Analyzer["item801_analyzer"]:::workflow
        Agent8KParser["agent_8k_parser"]:::agents
        Agent201["agent_8k_201_analyzer"]:::agents
        Agent202["agent_8k_202_analyzer"]:::agents
        Agent502["agent_8k_502_analyzer"]:::agents
        Agent801["agent_8k_801_analyzer"]:::agents
        Agent801Spec["agent_801_analyzer"]:::agents
        AgentNews["agent_news"]:::agents
        OpenAIRateLimiter["openai_limiter"]:::clients
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        BaseDBClient["base_db_client"]:::storage
        EdgarDBClient["edgar_db_client"]:::storage
        DBUtils["db_utils"]:::storage
        Publish502["publish_parsed_502"]:::storage
        Publish801["publish_parsed_801"]:::storage
        SchemaDefs["schema definitions"]:::storage
        DBCylinder(("Database")):::storage
    end

    %% Data Models
    subgraph "Data Models"
        direction TB
        DBTypes["DB Tables Types"]:::types
        Edgar8KTypes["EDGAR 8-K Types"]:::types
    end

    %% Connections
    RunWorkflow -->|invokes| EdgarGraph
    RunWorkflow -->|invokes| NewsGraph
    RunEdgarQuery -->|invokes| EdgarGraph
    RunNewsAgent -->|invokes| NewsGraph
    Draw8KWorkflow -->|visualizes| EdgarGraph

    EdgarGraph -->|fetches| EdgarClient
    EdgarGraph -->|fetches| FilingDownloader
    EdgarGraph -->|rate limits| RateLimiterSEC
    NewsGraph -->|fetches| PolygonClient

    EdgarClient -->|calls| SEC_API
    FilingDownloader -->|calls| SEC_API
    RateLimiterSEC -->|controls| SEC_API
    PolygonClient -->|calls| POLY_API

    EdgarGraph --> DocAnalyzer
    DocAnalyzer --> Parse8K502
    DocAnalyzer --> Item801Analyzer

    Parse8K502 --> Agent8KParser
    Parse8K502 --> Agent201
    Parse8K502 --> Agent202
    Parse8K502 --> Agent502

    Item801Analyzer --> Agent801
    Item801Analyzer --> Agent801Spec
    NewsGraph --> AgentNews

    Agent8KParser -->|LLM call| OpenAI_API
    Agent201 -->|LLM call| OpenAI_API
    Agent202 -->|LLM call| OpenAI_API
    Agent502 -->|LLM call| OpenAI_API
    Agent801 -->|LLM call| OpenAI_API
    Agent801Spec -->|LLM call| OpenAI_API
    AgentNews -->|LLM call| OpenAI_API
    OpenAIRateLimiter -->|controls| OPENAI_API

    Parse8K502 --> Publish502
    Item801Analyzer --> Publish801

    Publish502 --> BaseDBClient
    Publish801 --> BaseDBClient
    BaseDBClient --> EdgarDBClient
    BaseDBClient --> DBUtils
    EdgarDBClient --> SchemaDefs
    BaseDBClient --> DBCylinder

    DBTypes --> BaseDBClient
    Edgar8KTypes --> DocAnalyzer

    %% Click Events
    click EdgarClient "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/clients/edgar/edgar_client.py"
    click FilingDownloader "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/clients/edgar/filing_downloader.py"
    click RateLimiterSEC "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/clients/sec/rate_limiter.py"
    click PolygonClient "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/clients/polygon/polygon_client.py"
    click EdgarGraph "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/graphs/edgar_8k_workflow.py"
    click NewsGraph "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/graphs/news_analysis_graph.py"
    click RunWorkflow "https://github.com/andersonvc/alpha-pulse/tree/main/scripts/run_workflow"
    click RunEdgarQuery "https://github.com/andersonvc/alpha-pulse/tree/main/scripts/run_edgar_query"
    click RunNewsAgent "https://github.com/andersonvc/alpha-pulse/tree/main/scripts/run_news_agent"
    click Draw8KWorkflow "https://github.com/andersonvc/alpha-pulse/tree/main/scripts/draw_8k_workflow"
    click OpenAIRateLimiter "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/openai_limiter.py"
    click DocAnalyzer "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agent_workflows/doc_analyzer.py"
    click Parse8K502 "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agent_workflows/parse_8k_502.py"
    click Item801Analyzer "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agent_workflows/item801_analyzer.py"
    click Agent8KParser "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agents/edgar/agent_8k_parser.py"
    click Agent201 "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agents/edgar/agent_8k_201_analyzer.py"
    click Agent202 "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agents/edgar/agent_8k_202_analyzer.py"
    click Agent502 "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agents/edgar/agent_8k_502_analyzer.py"
    click Agent801 "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agents/edgar/agent_8k_801_analyzer.py"
    click Agent801Spec "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agents/edgar/agent_801_analyzer.py"
    click AgentNews "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/agents/polygon/agent_news.py"
    click BaseDBClient "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/storage/base_db_client.py"
    click EdgarDBClient "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/storage/edgar_db_client.py"
    click DBUtils "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/storage/db_utils.py"
    click Publish502 "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/storage/publishers/publish_parsed_502.py"
    click Publish801 "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/storage/publishers/publish_parsed_801.py"
    click SchemaDefs "https://github.com/andersonvc/alpha-pulse/blob/main/src/alpha_pulse/storage/schema.py"

    %% Styles
    classDef external fill:#daf3fc,stroke:#0a4c6e;
    classDef clients fill:#d4f8d4,stroke:#2d6a4f;
    classDef workflow fill:#fff3b0,stroke:#826000;
    classDef agents fill:#fff3b0,stroke:#826000;
    classDef storage fill:#ffd8a8,stroke:#a45b00;
    classDef types fill:#e2e2e2,stroke:#555555;
```
