Core Modules in ZhuLinsen/daily_stock_analysis: Architecture and Implementation Guide

The eight core modules in daily_stock_analysis located under src/core/ provide a decoupled architecture for stock market analysis, covering pipeline orchestration, trading calendar logic, strategy execution, market profiling, configuration management, and historical backtesting.

The ZhuLinsen/daily_stock_analysis repository implements a modular Python architecture centered on the src/core/ package. These core modules form a self-contained engine for end-to-end stock analysis, from data ingestion and LLM-powered technical analysis to market scheduling and strategy evaluation according to the source code.

Pipeline Orchestration with pipeline.py

The pipeline.py module serves as the central orchestrator for the entire analysis workflow. It implements the StockAnalysisPipeline class, which coordinates data fetching, technical analysis, LLM processing, and notification services.

Key entry points include the fetch_and_save_stock_data method, which handles the end-to-end flow for individual stocks, and the pipeline initialization that prepares database connections, data fetchers, and analysis services.

from src.core.pipeline import StockAnalysisPipeline
from src.config import get_config

# Load configuration (reads .env, defaults, etc.)

cfg = get_config()

# Create the pipeline – it will initialise DB, fetchers, LLM, notification, etc.

pipeline = StockAnalysisPipeline(config=cfg, max_workers=4)

# Analyse a single A‑share stock (e.g., 600519) and retrieve the result.

success, error = pipeline.fetch_and_save_stock_data("600519")
if success:
    result = pipeline.analyzer.analyze_stock("600519")
    print(result.summary)
else:
    print(f"Failed to fetch data: {error}")

As implemented in src/core/pipeline.py, the pipeline deliberately depends only on services that expose clean interfaces, ensuring loose coupling between data sources and analysis logic.

Market Scheduling and Calendar Logic

The trading_calendar.py module abstracts market-specific holiday rules and timezone handling, providing a simple predicate interface for checking market status.

The is_market_open function checks whether a given market (e.g., "cn" for A-shares) is currently trading, while get_effective_trading_date handles date resolution across timezones. This module optionally supports the exchange-calendars library for extended market coverage.

from src.core.trading_calendar import is_market_open

if is_market_open("cn"):
    print("Chinese A‑share market is open today!")
else:
    print("Closed – no analysis for CN stocks.")

Located in src/core/trading_calendar.py, these utilities ensure the rest of the system works with a consistent "is today a trading day?" interface regardless of underlying exchange complexity.

Strategy and Market Intelligence

Four interconnected modules handle high-level market strategy and reporting:

Trading Strategy Selection (market_strategy.py)

The MarketStrategy class determines which markets to run and how to combine analysis results. It acts as the decision layer that filters stocks and routes them to the appropriate analysis pipelines.

Market Review Generation (market_review.py)

The market_review.py module executes the "big market recap" for A-share, HK, and US markets. The run_market_review helper generates comprehensive daily reports, while _get_market_review_text handles the underlying text construction.

from src.core.market_review import run_market_review
from src.config import get_config

cfg = get_config()
review_text = run_market_review(language=cfg.report_language)
print("--- Market Review ---")
print(review_text)

This functionality is exposed through src/core/market_review.py and typically runs after individual stock analysis completes.

Market Profile Analysis (market_profile.py)

The MarketProfile class generates statistical profiling information including sector rotation patterns and index performance metrics. This data feeds into the strategy layer to inform high-level trading decisions.

Configuration and Environment Management

Configuration is split across two specialized modules to separate runtime loading from constant definitions.

Runtime Configuration (config_manager.py)

The ConfigManager class loads and validates runtime settings, merging defaults, environment variables, and user-provided overrides. The get_config convenience function provides the global Config object used throughout the application.

As implemented in src/core/config_manager.py, this module creates the configuration singleton at startup and passes it to the pipeline and other services.

Configurable Constants Registry (config_registry.py)

The ConfigRegistry class provides a central registry for configurable constants, enabling hot-reloading and validation of configuration keys without restarting the analysis engine. This complements the ConfigManager by providing a mutable registry layer for dynamic settings.

Historical Backtesting Engine

The backtest_engine.py module provides deterministic historical analysis through the BacktestEngine class. Unlike the live pipeline, this harness replays historic data through the same analysis flow for strategy evaluation.

The run_backtest method executes the full pipeline over a specified date range, allowing researchers to validate strategy performance against historical market conditions.

from src.core.backtest_engine import BacktestEngine
from src.config import get_config

cfg = get_config()
engine = BacktestEngine(config=cfg, start_date="2024-03-01", end_date="2024-03-30")
summary = engine.run_backtest()
print(summary)

Found in src/core/backtest_engine.py, this module maintains consistency with live analysis by using identical service interfaces and configuration patterns.

Summary

• pipeline.py orchestrates the end-to-end analysis workflow through the StockAnalysisPipeline class and fetch_and_save_stock_data method.
• trading_calendar.py determines market availability via is_market_open and get_effective_trading_date.
• market_strategy.py contains the MarketStrategy class for high-level trading decisions.
• market_review.py generates daily recaps using run_market_review and _get_market_review_text.
• market_profile.py provides sector rotation analysis via the MarketProfile class.
• config_manager.py loads runtime configuration through ConfigManager and get_config.
• config_registry.py maintains the ConfigRegistry for hot-reloadable constants.
• backtest_engine.py enables historical testing with BacktestEngine and run_backtest.

Frequently Asked Questions

What is the primary responsibility of the pipeline module?

The pipeline.py module serves as the central orchestrator that coordinates data fetching, technical analysis, LLM processing, and notifications. It initializes all service dependencies including database connections and data fetchers, then executes the analysis flow through the StockAnalysisPipeline class.

How does the trading calendar handle different market holidays?

The trading_calendar.py module abstracts timezone conversion and exchange-specific schedules through the is_market_open function. It optionally integrates with the exchange-calendars library to handle complex holiday rules for A-share, HK, and US markets, providing a unified predicate interface to the rest of the system.

What is the difference between config_manager.py and config_registry.py?

The config_manager.py module handles runtime configuration loading and validation through ConfigManager, merging environment variables and file-based settings. The config_registry.py module provides the ConfigRegistry class for managing constant definitions and enabling hot-reloading of specific configuration keys without application restarts.

How does the backtest engine differ from the live pipeline?

While the pipeline.py module processes real-time data for active trading days, the backtest_engine.py module replays historical snapshots through an identical analysis flow. The BacktestEngine class uses the same service interfaces and configuration patterns as the live system, ensuring that strategy evaluations reflect actual production behavior over historical date ranges.

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