# Architecture overview

This document explains the `excelminer` pipeline and how the workbook graph is built.

## End-to-end pipeline

```mermaid
flowchart TD
    A[analyze_workbook()] --> B[AnalysisContext + WorkbookGraph]
    B --> C{Backends in order}
    C --> D[OOXMLZipBackend
sheets/defined names
connections + sources]
    C --> E[VbaZipBackend
VBA modules]
    C --> F[PowerQueryZipBackend
Power Query + sources]
    C --> G[PivotZipBackend
pivot caches + tables]
    C --> H[CalamineBackend
cell blocks]
    C --> I[OpenpyxlBackend
formula cells]
    C --> J[ComBackend
optional COM enrichment]
    D --> K[Shared WorkbookGraph]
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    K --> L[BackendReports]
    K --> M{post_analysis_distillation?}
    M -->|True| N[distill_graph()
formula groups + pruning]
    M -->|False| O[Skip]
    N --> P[Final graph + reports]
    O --> P
```

## Graph-centric view

The `WorkbookGraph` is a normalized graph of artifacts. Each backend discovers
nodes and adds edges to describe relationships.

```mermaid
flowchart LR
    Sheet[Sheet] -->|contains| FormulaCell[FormulaCell]
    Sheet -->|contains| CellBlock[CellBlock]
    Sheet -->|contains| PivotTable[PivotTable]
    Sheet -->|scoped_to| DefinedName[DefinedName]
    PivotTable -->|uses_cache| PivotCache[PivotCache]
    PivotCache -->|uses_connection| Connection[Connection]
    Connection -->|uses_source| Source[Source]
    PowerQuery[PowerQuery] -->|uses_source| Source
    PowerQuery -->|uses_connection| Connection
    PowerQuery -->|has_script| MScript[MScript]
    Chart[Chart] -->|uses_defined_name| DefinedName
    FormulaCell -->|member_of| FormulaGroup[FormulaGroup]
```

## Logical gates and guards

Key control points that influence the pipeline:

- **Options gates**: each backend checks `AnalysisOptions` flags (`include_*`).
- **File-type gates**: backends validate suffixes and ZIP structure (OOXML).
- **Limits gates**: `max_sheets`, `max_cells_per_sheet`, and sampling limits bound work.
- **Post-analysis**: `post_analysis_distillation` toggles grouping/pruning.

## Backend responsibilities (quick map)

| Backend | Primary artifacts | Notes |
| --- | --- | --- |
| `OOXMLZipBackend` | Sheets, defined names, charts, connections, sources | Structural pass; builds graph backbone. |
| `VbaZipBackend` | VBA project node | Extracts VBA module text when available. |
| `PowerQueryZipBackend` | Power Query nodes + scripts + sources | Parses `xl/queries/*.xml` plus mashup container hints. |
| `PivotZipBackend` | Pivot tables + caches | Links to connections when possible. |
| `CalamineBackend` | Cell blocks | Uses pandas + calamine for used-range scanning. |
| `OpenpyxlBackend` | Formula cells | Captures formulas and basic dependencies. |
| `ComBackend` | Enrichment | Optional Windows-only COM automation. |
