# subbajandyala/stockanalyser architecture

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

- Interactive diagram: https://gitdiagram.com/subbajandyala/stockanalyser
- Repository: https://github.com/subbajandyala/stockanalyser

## Overview

This repository is a small Python stock-screening application centered around a single package, `screener`, with `app.py` as the top-level entry point. The codebase is organized more by analysis capability than by UI or service layers.

1. **Entry point and orchestration**
   - `app.py` is the likely coordinator for running screening jobs or exposing a simple CLI/script workflow.
   - It probably pulls together data retrieval, technical analysis, and strategy-specific screeners from the `screener` package.

2. **Domain package: `screener/`**
   - The main business logic lives in `screener`.
   - This package appears to represent a stock-analysis domain with reusable technical utilities plus separate screening strategies.

3. **Market data / stock universe layer**
   - `screener/stocks.py` likely handles stock symbol lists, watchlists, or market universe selection.
   - This is the boundary where the app decides which instruments to evaluate before any technical logic runs.

4. **Technical-analysis core**
   - `screener/technical.py` is the shared indicator/analytics layer.
   - It likely computes common series used by multiple screeners, such as moving averages, trend signals, or support/resistance related values.
   - This module is the main internal dependency for the strategy modules.

5. **Strategy-specific screeners**
   - `screener/ma50_support.py`, `screener/ma_crossover.py`, and `screener/ma_retracement.py` look like three distinct screening rules built around moving averages.
   - Each module likely encapsulates one interpretation of price action:
     - 50-day moving average support behavior
     - moving-average crossover signals
     - retracement relative to a moving-average trend
   - This separation suggests a modular strategy design where each screener can be run independently or combined by `app.py`.

6. **News integration**
   - `screener/news.py` indicates a second signal source beyond technicals.
   - Its role is probably to fetch or summarize headlines and attach qualitative context to a stock scan.
   - Architecturally, this is an auxiliary enrichment layer rather than the core decision engine.

7. **Data flow through the application**
   - Typical flow is: select symbols in `stocks.py` → load/analyze price data in `technical.py` → apply one or more moving-average screeners → optionally enrich with `news.py` → return or print results from `app.py`.
   - The main output is likely a ranked or filtered set of candidate stocks rather than persisted state.

8. **Package boundary and reuse**
   - The `screener` package acts as the internal API boundary for the application.
   - Shared technical logic is centralized, while strategy files remain small and purpose-specific, which keeps the architecture easy to extend with more screens.

9. **Testing**
   - The `test/` directory shows that analysis logic is intended to be testable as pure Python functions or small units.
   - Given the modular layout, tests likely focus on indicator calculations and screener decision rules rather than full end-to-end system behavior.

10. **Automation / CI**
   - `.github/workflows/static.yml` suggests GitHub Actions is used for automated validation, likely static checks or linting.
   - This points to a lightweight, repository-level delivery model with no separate deployment infrastructure visible in the tree.

11. **Dependencies and runtime**
   - `requirements.txt` indicates a standard Python runtime with external packages for data analysis, technical indicators, or data access.
   - The architecture is therefore dependency-light and script/package oriented, not a microservice or web framework architecture.

12. **Overall shape**
   - The system is best described as a modular Python stock-screener:
     - one orchestration script,
     - one reusable analysis package,
     - multiple strategy modules,
     - optional news enrichment,
     - tests and CI around the core logic.
   - An architecture diagram should emphasize the flow from symbol selection to analysis to screening results, with `technical.py` and the moving-average strategy modules as the central computational core.

Main entry points: [`app.py`](https://github.com/subbajandyala/stockanalyser/blob/main/app.py) (app.py), [`screener/technical.py`](https://github.com/subbajandyala/stockanalyser/blob/main/screener/technical.py) (Technical), [`test`](https://github.com/subbajandyala/stockanalyser/tree/main/test) (test), [`screener/ma50_support.py`](https://github.com/subbajandyala/stockanalyser/blob/main/screener/ma50_support.py) (MA50 Support)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry"]
  node_app["app.py<br/>orchestrator<br/>[app.py]"]
end

subgraph group_core["Screener"]
  node_pkg["screener"]
  node_stocks["Stocks<br/>universe selection<br/>[stocks.py]"]
  node_technical["Technical<br/>indicator core<br/>[technical.py]"]
  node_ma50["MA50 Support<br/>screening strategy<br/>[ma50_support.py]"]
  node_cross["MA Crossover<br/>screening strategy<br/>[ma_crossover.py]"]
  node_retrace["Retracement<br/>screening strategy<br/>[ma_retracement.py]"]
  node_news["News<br/>signal enrichment<br/>[news.py]"]
end

subgraph group_quality["Quality"]
  node_tests["test"]
  node_ci["CI<br/>automation<br/>[static.yml]"]
  node_deps["Deps<br/>runtime dependencies<br/>[requirements.txt]"]
end

node_app -->|"uses"| node_pkg
node_app -->|"selects"| node_stocks
node_app -->|"analyzes"| node_technical
node_app -->|"runs"| node_ma50
node_app -->|"runs"| node_cross
node_app -->|"runs"| node_retrace
node_app -->|"enriches"| node_news
node_stocks -->|"feeds"| node_technical
node_technical -->|"supplies signals"| node_ma50
node_technical -->|"supplies signals"| node_cross
node_technical -->|"supplies signals"| node_retrace
node_ma50 -->|"returns"| node_app
node_cross -->|"returns"| node_app
node_retrace -->|"returns"| node_app
node_news -->|"returns"| node_app
node_tests -.->|"covers"| node_technical
node_tests -.->|"covers"| node_ma50
node_tests -.->|"covers"| node_cross
node_tests -.->|"covers"| node_retrace
node_ci -.->|"validates"| node_tests
node_ci -.->|"installs"| node_deps

click node_app "https://github.com/subbajandyala/stockanalyser/blob/main/app.py"
click node_pkg "https://github.com/subbajandyala/stockanalyser/tree/main/screener"
click node_stocks "https://github.com/subbajandyala/stockanalyser/blob/main/screener/stocks.py"
click node_technical "https://github.com/subbajandyala/stockanalyser/blob/main/screener/technical.py"
click node_ma50 "https://github.com/subbajandyala/stockanalyser/blob/main/screener/ma50_support.py"
click node_cross "https://github.com/subbajandyala/stockanalyser/blob/main/screener/ma_crossover.py"
click node_retrace "https://github.com/subbajandyala/stockanalyser/blob/main/screener/ma_retracement.py"
click node_news "https://github.com/subbajandyala/stockanalyser/blob/main/screener/news.py"
click node_tests "https://github.com/subbajandyala/stockanalyser/tree/main/test"
click node_ci "https://github.com/subbajandyala/stockanalyser/blob/main/.github/workflows/static.yml"
click node_deps "https://github.com/subbajandyala/stockanalyser/blob/main/requirements.txt"

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_app toneBlue
class node_pkg,node_stocks,node_technical,node_ma50,node_cross,node_retrace,node_news toneAmber
class node_tests,node_ci,node_deps toneMint
```

## Components

### Entry

Top-level orchestration and runtime entrypoint.

- [app.py](https://github.com/subbajandyala/stockanalyser/blob/main/app.py): orchestrator · Runs screening workflows and coordinates the main analysis flow. · `app.py`

### Screener

Reusable stock-analysis package and screening strategies.

- [screener](https://github.com/subbajandyala/stockanalyser/tree/main/screener): package · Internal package boundary for stock analysis and screeners. · `screener`
- [Stocks](https://github.com/subbajandyala/stockanalyser/blob/main/screener/stocks.py): universe selection · Defines the market universe or symbol lists to evaluate. · `screener/stocks.py`
- [Technical](https://github.com/subbajandyala/stockanalyser/blob/main/screener/technical.py): indicator core · Shared technical-analysis calculations used by multiple strategies. · `screener/technical.py`
- [MA50 Support](https://github.com/subbajandyala/stockanalyser/blob/main/screener/ma50_support.py): screening strategy · Screens for 50-day moving-average support behavior. · `screener/ma50_support.py`
- [MA Crossover](https://github.com/subbajandyala/stockanalyser/blob/main/screener/ma_crossover.py): screening strategy · Screens for moving-average crossover signals. · `screener/ma_crossover.py`
- [Retracement](https://github.com/subbajandyala/stockanalyser/blob/main/screener/ma_retracement.py): screening strategy · Screens for pullbacks or retracements within a moving-average trend. · `screener/ma_retracement.py`
- [News](https://github.com/subbajandyala/stockanalyser/blob/main/screener/news.py): signal enrichment · Adds headline or news context to technical screening results. · `screener/news.py`

### Quality

Tests and automation around the core logic.

- [test](https://github.com/subbajandyala/stockanalyser/tree/main/test): test suite · Validates analysis and screening behavior at the unit level. · `test`
- [CI](https://github.com/subbajandyala/stockanalyser/blob/main/.github/workflows/static.yml): automation · GitHub Actions workflow for static checks and validation. · `.github/workflows/static.yml`
- [Deps](https://github.com/subbajandyala/stockanalyser/blob/main/requirements.txt): runtime dependencies · Python package requirements for analysis and data access. · `requirements.txt`

## Connections

- app.py → screener: uses · Main entrypoint depends on the screener package.
- app.py → Stocks: selects · Chooses which symbols or universe to screen.
- app.py → Technical: analyzes · Coordinates shared technical calculations for screening.
- app.py → MA50 Support: runs · Invokes the MA50 support strategy.
- app.py → MA Crossover: runs · Invokes the moving-average crossover strategy.
- app.py → Retracement: runs · Invokes the retracement strategy.
- app.py → News: enriches · Optionally augments results with news context.
- Stocks → Technical: feeds · Provides the candidate symbols for analysis.
- Technical → MA50 Support: supplies signals · Shared indicator output supports this strategy.
- Technical → MA Crossover: supplies signals · Shared indicator output supports this strategy.
- Technical → Retracement: supplies signals · Shared indicator output supports this strategy.
- MA50 Support → app.py: returns · Produces screened candidates for the runner.
- MA Crossover → app.py: returns · Produces screened candidates for the runner.
- Retracement → app.py: returns · Produces screened candidates for the runner.
- News → app.py: returns · Provides contextual output for presentation.
- test → Technical: covers · Exercises indicator and analysis logic.
- test → MA50 Support: covers · Exercises strategy decision rules.
- test → MA Crossover: covers · Exercises strategy decision rules.
- test → Retracement: covers · Exercises strategy decision rules.
- CI → test: validates · Automated workflow runs repository checks.
- CI → Deps: installs · Workflow relies on declared Python dependencies.