# quansight-labs/ndindex architecture

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

- Interactive diagram: https://gitdiagram.com/quansight-labs/ndindex
- Repository: https://github.com/quansight-labs/ndindex

## Overview

##### Project type and purpose
- ndindex is an open-source Python library (no frontend / backend web layers) that provides a uniform API for representing and manipulating numpy array indices (slices, integers, ellipses, boolean/integer arrays, tuples).
- It focuses on correctness (full numpy semantics) and performance (via Cython modules), with supporting tooling for documentation (Sphinx), testing (pytest), and benchmarking (asv).

##### File structure
- Top‐level directories and files
- ndindex/              ← core Python modules and Cython `.pyx` files
- ndindex/tests/        ← pytest test suite
- benchmarks/           ← asv benchmarking scripts
- docs/                 ← Sphinx documentation sources and static assets
- .github/workflows/    ← CI/CD (GitHub Actions) definitions
- setup.py, pyproject.toml, setup.cfg  ← build & packaging
- versioneer.py         ← version management
- Key patterns
- Modular design: each index type (slice, tuple, etc.) is a separate module
- Cython acceleration: `_slice.pyx`, `_tuple.pyx`, `_crt.py` compile to C extensions
- Conventional Python package layout with tests and docs in sibling dirs
- Tooling/config
- pytest.ini, conftest.py for tests
- asv.conf.json for benchmarks
- Sphinx conf.py, Makefile for docs
- GitHub Actions workflows for test, docs preview, package publish

##### README for additional insights
- Emphasizes uniform API, correct numpy semantics, transformation utilities
- Points to online docs site
- No runtime services or external APIs—pure library

##### Main components and interactions
a. Components
1. API Layer (ndindex/*.py)
2. Core Cython Layer (ndindex/*.pyx & _crt.py → compiled extension modules)
3. Test Suite (ndindex/tests + pytest config)
4. Benchmark Suite (benchmarks/ + asv)
5. Documentation (docs/, Sphinx)
6. Build & Packaging (setup.py, pyproject.toml, versioneer)
7. CI/CD (GitHub Actions workflows)
8. External Dependencies (numpy, C compiler, Python)
b. Relationships & data flows
- Developer commits → CI triggers tests, style checks, type checks
- Build step compiles Cython modules → generates .so extension
- Package step bundles Python code + compiled extensions → publish to PyPI
- Docs build step pulls code + doc sources → renders HTML and deploys to docs site
- Benchmark step runs asv against compiled library → records performance metrics
c. Architectural patterns & principles
- Layered architecture: high-level Python API over low-level Cython primitives
- Separation of concerns: pure code vs. tests vs. docs vs. benchmarks
- GitOps/CI-driven delivery (GitHub Actions)
d. Key technologies
- Python 3.x, Cython, numpy
- pytest, asv
- Sphinx (reStructuredText, Makefile)
- GitHub Actions for CI/CD
- versioneer for automatic versioning

##### Elements
- Clear labels for each component (e.g., “API Layer”, “Cython Extensions”, “Test Suite”)
- Code → Build
- Build → Package → Publish
- Code → Docs Builder → Docs Site
- Code → Test Runner → Test Reports
- Code → Benchmark Runner → Metrics Store
- Notes or annotations for critical details (e.g., which modules are `.pyx` vs. `.py`)

##### Detailed capture of essential elements
- “ndindex/*.py” (API Layer)
- “ndindex/*.pyx, _crt.py” (Cython Layer)
- “ndindex/tests/” (Test Suite)
- “benchmarks/” (Benchmark Suite)
- “docs/” (Documentation Sources)
- “setup.py & versioneer.py” (Build & Packaging)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "ndindex Repository"
        direction TB
        subgraph "Code Modules"
            direction TB
            API["API Layer\n(ndindex/*.py)"]:::code
            Cython["Cython Layer\n(_slice.pyx, _tuple.pyx, _crt.py)"]:::code
        end
        subgraph "Tooling & Config"
            direction TB
            TestSuite["Test Suite\n(ndindex/tests/)"]:::tool
            Benchmark["Benchmark Suite\n(benchmarks/)"]:::tool
            Documentation["Documentation\n(docs/)"]:::tool
            BuildPack["Build & Packaging\n(setup.py, versioneer.py)"]:::tool
        end
    end

    Deps["External Dependencies\n(numpy, C compiler, Python)"]:::dep

    GH["GitHub Actions"]:::tool
    TestsWF["Tests Workflow"]:::tool
    DocsPrevWF["Docs Preview Workflow"]:::tool
    DocsWF["Docs Build Workflow"]:::tool
    PublishWF["Publish Package Workflow"]:::tool
    CircleCI["CircleCI CI Config"]:::tool

    PyPI["PyPI"]:::external
    PerfDash["Performance Dashboard"]:::external
    DocsHost["Docs Hosting"]:::external

    Deps --> BuildPack
    BuildPack -->|compiles| Cython
    BuildPack -->|packages| PublishWF
    API --> TestSuite
    Cython --> Benchmark
    API --> Documentation

    GH --> TestsWF
    GH --> DocsPrevWF
    GH --> DocsWF
    GH --> PublishWF
    GH --> CircleCI

    TestsWF --> TestSuite
    DocsWF --> Documentation
    PublishWF --> PyPI
    Benchmark --> PerfDash
    Documentation --> DocsHost

    click API "https://github.com/quansight-labs/ndindex/tree/main/ndindex/"
    click Cython "https://github.com/quansight-labs/ndindex/blob/main/ndindex/_slice.pyx"
    click TestSuite "https://github.com/quansight-labs/ndindex/tree/main/ndindex/tests/"
    click Benchmark "https://github.com/quansight-labs/ndindex/tree/main/benchmarks/"
    click Documentation "https://github.com/quansight-labs/ndindex/tree/main/docs/"
    click BuildPack "https://github.com/quansight-labs/ndindex/blob/main/setup.py"
    click TestsWF "https://github.com/quansight-labs/ndindex/blob/main/.github/workflows/tests.yml"
    click DocsPrevWF "https://github.com/quansight-labs/ndindex/blob/main/.github/workflows/docs-preview.yml"
    click DocsWF "https://github.com/quansight-labs/ndindex/blob/main/.github/workflows/docs.yml"
    click PublishWF "https://github.com/quansight-labs/ndindex/blob/main/.github/workflows/publish-package.yml"
    click CircleCI "https://github.com/quansight-labs/ndindex/blob/main/.circleci/config.yml"

    classDef code fill:#D0E4F5,stroke:#0366d6,color:#0366d6;
    classDef tool fill:#E6F4EA,stroke:#1B7A3D,color:#1B7A3D;
    classDef external fill:#FFEFD5,stroke:#D2691E,color:#D2691E;
    classDef dep fill:#FFF5E1,stroke:#DAA520,color:#DAA520;
```
