# billyany/worldquant architecture

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

- Interactive diagram: https://gitdiagram.com/billyany/worldquant
- Repository: https://github.com/billyany/worldquant

## Overview

##### Project Type & Purpose
- Type: A CLI-driven open-source factor-mining tool (no GUI, no web frontend/backend).
- Purpose:
– Read user credentials, run two “digging” steps to generate candidate factors.
– Validate (“check”) factors.
– Submit approved factors to an external service (platform.worldquantbrain.com).

##### File Structure
Top-level files:
- digging_1step.py, digging_2step.py: two sequential factor-mining stages.
- check.py: factor-verification logic.
- submit_alpha.py: submission workflow.
- machine_lib.py: core library functions (data loading, processing, API calls).
- config.py: global configuration (paths, constants, API endpoints).
- fields.py: definitions of data fields & schemas.
- requirements.txt: dependencies.
- user_info.txt (runtime): holds username/password for API authentication.

##### Extract Insights from README
- Workflow:
1. Install deps.
2. Populate user_info.txt.
3. Run digging_1step → digging_2step → check → submit_alpha.
- External dependency: platform.worldquantbrain.com API.

##### Main Components & Their Interactions
a. Components
– CLI Launcher (user’s shell)
– Config Module (config.py, fields.py)
– Core Library (machine_lib.py)
– Digging Stage 1 (digging_1step.py)
– Digging Stage 2 (digging_2step.py)
– Check Stage (check.py)
– Submission Stage (submit_alpha.py)
– External Service (WorldQuantBrain API)
– Data Store (local files: user_info.txt, intermediate factor files)
b. Relationships / Data Flow
1. User invokes digging_1step → loads config, fields → uses machine_lib to fetch/preprocess data → outputs intermediate factors.
2. digging_2step reads previous output → refines factors → writes results.
3. check.py loads results → runs validation routines → marks pass/fail.
4. submit_alpha.py reads validated factors & user_info.txt → authenticates via machine_lib against external API → submits.
c. Architectural Patterns
– Modular scripting: each stage is a separate script with clearly defined input/output.
– Shared library (machine_lib) and config for reuse.
– File-based chaining between stages.
– Single external integration point (REST API).
d. Key Technologies / Libraries
– Python 3.x
– requests (for HTTP calls)
– pandas / numpy (likely for data processing, per requirements.txt)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Scripts
    subgraph "CLI Scripts"
        S1["digging_1step.py"]:::script
        S2["digging_2step.py"]:::script
        S3["check.py"]:::script
        S4["submit_alpha.py"]:::script
    end

    %% Core Modules
    subgraph "Core Modules"
        Config["config.py"]:::lib
        Fields["fields.py"]:::lib
        Library["machine_lib.py"]:::lib
    end

    %% Data Stores
    Data1[("factors_step1.csv")]:::datastore
    Data2[("factors_step2.csv")]:::datastore
    DataV[("validated_factors.csv")]:::datastore
    UserInfo[("user_info.txt")]:::datastore

    %% External Service
    Ext("WorldQuantBrain API"):::external

    %% Project Files
    subgraph "Project Files"
        Req["requirements.txt"]:::misc
        Readme["README.md"]:::misc
        Lic["LICENSE"]:::misc
        Changelog["CHANGE_LOG.md"]:::misc
        Gitignore[".gitignore"]:::misc
    end

    %% Workflow Sequence
    S1 -->|"1"| Data1
    Data1 -->|"2"| S2
    S2 -->|"3"| Data2
    Data2 -->|"4"| S3
    S3 -->|"5"| DataV
    DataV -->|"6"| S4
    UserInfo -->|"7"| S4
    S4 -->|"8"| Ext

    %% Module Dependencies
    Config --> S1
    Config --> S2
    Config --> S3
    Config --> S4
    Fields --> S1
    Fields --> S2
    Fields --> S3
    Fields --> S4
    Library --> S1
    Library --> S2
    Library --> S3
    Library --> S4

    %% Click Events
    click Config "https://github.com/billyany/worldquant/blob/master/config.py"
    click Fields "https://github.com/billyany/worldquant/blob/master/fields.py"
    click Library "https://github.com/billyany/worldquant/blob/master/machine_lib.py"
    click S1 "https://github.com/billyany/worldquant/blob/master/digging_1step.py"
    click S2 "https://github.com/billyany/worldquant/blob/master/digging_2step.py"
    click S3 "https://github.com/billyany/worldquant/blob/master/check.py"
    click S4 "https://github.com/billyany/worldquant/blob/master/submit_alpha.py"
    click Req "https://github.com/billyany/worldquant/blob/master/requirements.txt"
    click Readme "https://github.com/billyany/worldquant/blob/master/README.md"
    click Lic "https://github.com/billyany/worldquant/tree/master/LICENSE"
    click Changelog "https://github.com/billyany/worldquant/blob/master/CHANGE_LOG.md"
    click Gitignore "https://github.com/billyany/worldquant/blob/master/.gitignore"

    %% Styles
    classDef script fill:#AEDFF7,stroke:#333,stroke-width:1px;
    classDef lib fill:#FFE699,stroke:#333,stroke-width:1px;
    classDef datastore fill:#D5E8D4,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#F8CECC,stroke:#333,stroke-width:1px;
    classDef misc fill:#E1D5E7,stroke:#333,stroke-width:1px;
```
