# Main Components of the src Directory in Daily Stock Analysis

> Explore the src directory in ZhuLinsen/daily_stock_analysis. Discover its ten sub-packages like core orchestration, LLM agents, and data repositories forming a layered architecture for automated market analysis.

- Repository: [mumu/daily_stock_analysis](https://github.com/ZhuLinsen/daily_stock_analysis)
- Tags: internals
- Published: 2026-04-30

---

**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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/notification.py) through the `NotificationService.register_sender()` method.

### Configuration and Enumerations

Top-level files [`src/enums.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/enums.py) and [`src/config.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/main.py) for CLI execution, [`server.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/server.py) for HTTP API deployment, [`src/md2img.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/main.py) or [`server.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/server.py)) read configuration from [`src/config.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/config.py) and instantiate `StockAnalysisPipeline` from [`src/core/pipeline.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/agent/strategies/strategy_agent.py) utilize the same business services.

6. The final `AnalysisResult` validates against [`src/schemas/report_schema.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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:

```python
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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/core/pipeline.py).

### Accessing Stock Services Directly

Query real-time quotes without running the full pipeline:

```python
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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/services/stock_service.py).

### Extending Notification Channels

Add custom webhook support by extending the base sender class:

```python

# 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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/notification.py):

```python
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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/notification_sender/email_sender.py) for the complete pattern.

## Summary

- **[`src/core/pipeline.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/main.py) for CLI execution and [`server.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/server.py) for HTTP API access, both located in the repository root. These scripts instantiate the `StockAnalysisPipeline` class from [`src/core/pipeline.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/core/pipeline.py) and pass configuration from [`src/config.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/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`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/notification_sender/email_sender.py). Then register your sender in [`src/notification.py`](https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/src/notification.py) using `NotificationService.register_sender("channel_name", YourSenderClass)` to make it available throughout the application.