# a545996726-ctrl/cnequity architecture

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

- Interactive diagram: https://gitdiagram.com/a545996726-ctrl/cnequity
- Repository: https://github.com/a545996726-ctrl/cnequity

## Overview

CNEquity is a self-hosted China-market financial data lake: users configure and run collection or backfills, then query and inspect published Parquet datasets. The documented lifecycle runs source adapters through orchestration and validation into curated or derived data; research APIs, SQL, the read-only console, and MCP consume the lake. The graph keeps documented capabilities such as quality auditing, provenance, historical-universe/PIT semantics, and derivatives visible. Relationships not explicit in the sampled source are cited to the README rather than inferred from module names.

Main entry points: [`src/cnequity/orchestrator/engine.py`](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/orchestrator/engine.py) (Run orchestrator), [`src/cnequity/storage/parquet.py`](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/storage/parquet.py) (Curated Parquet lake), [`src/cnequity/query/reader.py`](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/query/reader.py) (Query layer), [`src/cnequity/cli/main.py`](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/cli/main.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and control"]
  node_cli["CLI<br/>[main.py]"]
  node_config["Configuration<br/>[loader.py]"]
  node_orchestrator["Run orchestrator<br/>[engine.py]"]
  node_steps["Collection steps"]
  node_adapters["Source adapters"]
end

subgraph group_data["Data lifecycle"]
  node_dataset_registry["Dataset registry<br/>[datasets.py]"]
  node_canonical["Canonical rows<br/>[canonical.py]"]
  node_raw_archive[("Raw archive<br/>[raw_archive.py]")]
  node_lake[("Curated Parquet lake<br/>[parquet.py]")]
  node_derived["Derived datasets"]
  node_revision_state[("Versions and run state<br/>[revisions.py]")]
end

subgraph group_research["Research and quality"]
  node_quality["Quality audits"]
  node_query["Query layer<br/>[reader.py]"]
  node_scan["Parquet scanning<br/>[parquet_scan.py]"]
  node_pit["PIT and universe rules<br/>[pit.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_console["Read-only console<br/>[app.py]"]
  node_mcp["Read-only MCP"]
end

node_researcher(("Researcher"))
node_sources(("Market data sources"))
node_python_sql(("Python and SQL users"))
node_browser(("Browser user"))

node_researcher -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts jobs"| node_orchestrator
node_orchestrator -->|"dispatches steps"| node_steps
node_steps -->|"collects through"| node_adapters
node_adapters -->|"fetches data"| node_sources
node_orchestrator -->|"uses dataset metadata"| node_dataset_registry
node_steps -->|"archives raw data"| node_raw_archive
node_orchestrator -->|"publishes validated batches"| node_lake
node_orchestrator -->|"runs quality checks"| node_quality
node_canonical -->|"uses dataset definitions"| node_dataset_registry
node_derived -->|"publishes derived data"| node_lake
node_orchestrator -->|"records versions"| node_revision_state
node_lake -->|"serves published data"| node_query
node_query -->|"scans Parquet"| node_scan
node_scan -->|"canonicalizes rows"| node_canonical
node_scan -->|"resolves revisions"| node_revision_state
node_query -->|"applies research semantics"| node_pit
node_python_sql -->|"queries datasets"| node_query
node_lake -->|"provides lake views"| node_console
node_browser -->|"views dashboard"| node_console
node_lake -->|"provides read-only data"| node_mcp

click node_cli "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/cli/main.py"
click node_config "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/config/loader.py"
click node_orchestrator "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/orchestrator/engine.py"
click node_steps "https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/steps"
click node_adapters "https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/adapters"
click node_dataset_registry "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/domain/datasets.py"
click node_canonical "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/domain/canonical.py"
click node_raw_archive "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/storage/raw_archive.py"
click node_lake "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/storage/parquet.py"
click node_derived "https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/derive"
click node_revision_state "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/storage/revisions.py"
click node_quality "https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/quality"
click node_query "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/query/reader.py"
click node_scan "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/query/parquet_scan.py"
click node_pit "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/domain/pit.py"
click node_console "https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/serve/app.py"
click node_mcp "https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/mcp_server"

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_cli,node_config,node_orchestrator,node_steps,node_adapters,node_python_sql,node_browser toneBlue
class node_dataset_registry,node_canonical,node_raw_archive,node_lake,node_derived,node_revision_state toneAmber
class node_quality,node_query,node_scan,node_pit toneMint
class node_console,node_mcp toneRose
class node_researcher,node_sources toneIndigo
```

## Components

### Collection and control

- [CLI](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/cli/main.py): `src/cnequity/cli/main.py`
- [Configuration](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/config/loader.py): `src/cnequity/config/loader.py`
- [Run orchestrator](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/orchestrator/engine.py): `src/cnequity/orchestrator/engine.py`
- [Collection steps](https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/steps): `src/cnequity/steps`
- [Source adapters](https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/adapters): `src/cnequity/adapters`

### Data lifecycle

- [Dataset registry](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/domain/datasets.py): `src/cnequity/domain/datasets.py`
- [Canonical rows](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/domain/canonical.py): `src/cnequity/domain/canonical.py`
- [Raw archive](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/storage/raw_archive.py): `src/cnequity/storage/raw_archive.py`
- [Curated Parquet lake](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/storage/parquet.py): `src/cnequity/storage/parquet.py`
- [Derived datasets](https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/derive): `src/cnequity/derive`
- [Versions and run state](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/storage/revisions.py): `src/cnequity/storage/revisions.py`

### Research and quality

- [Quality audits](https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/quality): `src/cnequity/quality`
- [Query layer](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/query/reader.py): `src/cnequity/query/reader.py`
- [Parquet scanning](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/query/parquet_scan.py): `src/cnequity/query/parquet_scan.py`
- [PIT and universe rules](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/domain/pit.py): `src/cnequity/domain/pit.py`

### User interfaces

- [Read-only console](https://github.com/a545996726-ctrl/cnequity/blob/main/src/cnequity/serve/app.py): `src/cnequity/serve/app.py`
- [Read-only MCP](https://github.com/a545996726-ctrl/cnequity/tree/main/src/cnequity/mcp_server): `src/cnequity/mcp_server`

### Other components

- **Researcher**
- **Market data sources**
- **Python and SQL users**
- **Browser user**

## Connections

- Researcher → CLI: runs commands (evidence: `README.md`)
- CLI → Configuration: loads settings
- CLI → Run orchestrator: starts jobs (evidence: `README.md`)
- Run orchestrator → Collection steps: dispatches steps (evidence: `src/cnequity/orchestrator/engine.py`)
- Collection steps → Source adapters: collects through (evidence: `README.md`)
- Source adapters → Market data sources: fetches data (evidence: `README.md`)
- Run orchestrator → Dataset registry: uses dataset metadata (evidence: `src/cnequity/orchestrator/engine.py`)
- Collection steps → Raw archive: archives raw data (evidence: `README.md`)
- Run orchestrator → Curated Parquet lake: publishes validated batches (evidence: `README.md`)
- Run orchestrator → Quality audits: runs quality checks (evidence: `README.md`)
- Canonical rows → Dataset registry: uses dataset definitions (evidence: `src/cnequity/domain/canonical.py`)
- Derived datasets → Curated Parquet lake: publishes derived data (evidence: `README.md`)
- Run orchestrator → Versions and run state: records versions (evidence: `README.md`)
- Curated Parquet lake → Query layer: serves published data (evidence: `README.md`)
- Query layer → Parquet scanning: scans Parquet (evidence: `src/cnequity/query/parquet_scan.py`)
- Parquet scanning → Canonical rows: canonicalizes rows (evidence: `src/cnequity/query/parquet_scan.py`)
- Parquet scanning → Versions and run state: resolves revisions (evidence: `src/cnequity/query/parquet_scan.py`)
- Query layer → PIT and universe rules: applies research semantics (evidence: `README.md`)
- Python and SQL users → Query layer: queries datasets (evidence: `README.md`)
- Curated Parquet lake → Read-only console: provides lake views (evidence: `src/cnequity/serve/app.py`)
- Browser user → Read-only console: views dashboard (evidence: `README.md`)
- Curated Parquet lake → Read-only MCP: provides read-only data (evidence: `README.md`)