Main Components of the src Directory in Daily Stock Analysis

The src directory in ZhuLinsen/daily_stock_analysis contains ten specialized sub-packages—including core orchestration, business services, LLM agents, data repositories, Pydantic schemas, and notification handlers—that form a layered architecture for automated market analysis.

The src package serves as the heart of the Daily Stock Analysis system, implementing a clean separation of concerns across data acquisition, business logic, and AI-driven reporting. Understanding the main components of the src directory is essential for developers looking to extend functionality or debug the end-to-end analysis pipeline. Each sub-package owns a specific responsibility, from orchestrating trading-calendar logic to managing external API integrations.

Core Packages and Their Responsibilities

The source code is organized into distinct functional layers. Each package contains representative files that demonstrate the architectural patterns used throughout the repository.

Core Orchestration Layer

The core package orchestrates the end-to-end analysis pipeline. In src/core/pipeline.py, the StockAnalysisPipeline class coordinates data fetching, LLM analysis, and report generation. This layer also handles trading-calendar logic and market-strategy helpers that determine when analysis should trigger based on market hours.

Business Logic Services

The services package acts as the business-logic layer that communicates with data providers, repositories, and external APIs. The StockService class in src/services/stock_service.py provides methods like get_realtime_quote() for retrieving market data, while sibling modules handle search operations, social sentiment analysis, and back-testing simulations.

LLM Agent Framework

The agent directory implements an LLM-driven "Agent" framework where AI invokes tools and strategies during report generation. The core implementation in src/agent/strategies/strategy_agent.py defines how the system applies Chain-of-Thought reasoning to market data, utilizing skills that reuse the same business services available to the rest of the application.

Data Access Layer

The repositories package contains thin data-access objects for persisting and retrieving raw market data, snapshots, and analysis history. The StockRepo class in src/repositories/stock_repo.py abstracts database operations, typically using SQLite with SQLAlchemy, ensuring the business logic remains decoupled from storage implementation details.

Data Contracts and Schemas

The schemas package defines Pydantic models that validate JSON contracts throughout the system. In src/schemas/report_schema.py, the AnalysisResult model enforces the structure of final reports before they enter the notification pipeline, ensuring type safety for both internal payloads and external API responses.

Static Data and Utilities

The data package houses static lookup tables such as stock-code to name mappings in src/data/stock_mapping.py, supporting Chinese, US, and Hong Kong markets. The utils package provides helper functions like those in src/utils/data_processing.py that massage raw market data into analysis-ready formats.

Notification Infrastructure

The notification_sender package contains implementations for multiple output channels. While src/notification_sender/email_sender.py handles SMTP delivery, sibling modules support Feishu webhooks and Discord integration. Registration of new senders occurs in src/notification.py through the NotificationService.register_sender() method.

Configuration and Enumerations

Top-level files src/enums.py and src/config.py define global configuration handling and shared enumerations for report types, market identifiers, and analysis modes. These constants ensure consistency across the core, services, and agent layers.

Auxiliary Entry Points

The directory also includes miscellaneous entry points and utilities such as main.py for CLI execution, server.py for HTTP API deployment, src/md2img.py for rendering markdown reports to PNG images, and src/market_*.py modules for market-wide context analysis.

How the Components Interact

The system follows a strict dependency flow from entry points to final notification:

1. Entry points (main.py or server.py) read configuration from src/config.py and instantiate StockAnalysisPipeline from src/core/pipeline.py.

2. The pipeline coordinates multiple services (e.g., StockService, SearchService, SocialSentimentService) to gather market intelligence.

3. Each service delegates to a repository when persistence is required, abstracting SQL operations through classes like StockRepo.

4. Raw market data flows from the data package through utils for preprocessing before entering the analysis pipeline.

5. The Agent framework can be invoked for enriched AI analysis, where strategies defined in src/agent/strategies/strategy_agent.py utilize the same business services.

6. The final AnalysisResult validates against src/schemas/report_schema.py before dispatch through the appropriate notification_sender implementation.

Practical Implementation Examples

Running a Single-Stock Analysis

Instantiate the StockAnalysisPipeline to analyze individual securities:

from src.core.pipeline import StockAnalysisPipeline
from src.enums import ReportType

pipeline = StockAnalysisPipeline()
result = pipeline.analyze_stock(
    code="AAPL",
    report_type=ReportType.DAILY,
    query_id="demo-run",
)
print(result.summary)          # human-readable text

print(result.dashboard)        # structured JSON for UI

Source: The StockAnalysisPipeline class is defined in src/core/pipeline.py.

Accessing Stock Services Directly

Query real-time quotes without running the full pipeline:

from src.services.stock_service import StockService

service = StockService()
quote = service.get_realtime_quote("600519")
print(quote["current_price"], quote["change_percent"])

Source: Implementation lives in src/services/stock_service.py.

Extending Notification Channels

Add custom webhook support by extending the base sender class:

# src/notification_sender/custom_webhook_sender.py

class CustomWebhookSender(NotificationSender):
    def send(self, message: str) -> None:
        requests.post(self.webhook_url, json={"text": message})

Register the new sender in src/notification.py:

from .notification_sender.custom_webhook_sender import CustomWebhookSender
NotificationService.register_sender("custom", CustomWebhookSender)

Source: See the existing sender implementations in src/notification_sender/email_sender.py for the complete pattern.

Summary

• src/core/pipeline.py orchestrates the end-to-end analysis workflow and trading-calendar logic.
• src/services/ houses business-logic wrappers that interface with external data providers and APIs.
• src/agent/ contains the LLM framework with tools and strategies for AI-driven report generation.
• src/repositories/ provides database abstractions for persisting market data and analysis history.
• src/schemas/report_schema.py defines Pydantic models that enforce report structure and validation.
• src/notification_sender/ implements pluggable channels for delivering results via Feishu, Email, Discord, or custom webhooks.

Frequently Asked Questions

What is the entry point for running a stock analysis?

The primary entry points are main.py for CLI execution and server.py for HTTP API access, both located in the repository root. These scripts instantiate the StockAnalysisPipeline class from src/core/pipeline.py and pass configuration from src/config.py to begin the analysis workflow.

How does the agent directory differ from the services directory?

While src/services contains business-logic wrappers for external APIs and data providers, src/agent houses the LLM-driven Agent framework including tools and strategies that the AI invokes during report generation. The strategy_agent.py module specifically implements Chain-of-Thought reasoning capabilities that utilize the underlying services for data retrieval.

Where is market data persisted in this architecture?

Data persistence occurs through the repository pattern implemented in src/repositories/. The StockRepo class in src/repositories/stock_repo.py handles database operations using SQLite and SQLAlchemy, providing a clean abstraction that keeps business logic in src/services decoupled from storage implementation details.

How can I add a new notification channel to the system?

Create a new class extending NotificationSender in a file under src/notification_sender/, following the implementation pattern in src/notification_sender/email_sender.py. Then register your sender in src/notification.py using NotificationService.register_sender("channel_name", YourSenderClass) to make it available throughout the application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}