# bdfsaraiva/parshift architecture

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

- Interactive diagram: https://gitdiagram.com/bdfsaraiva/parshift
- Repository: https://github.com/bdfsaraiva/parshift

## Overview

**ParShift** is an **open-source Python package/library** (published to PyPI) for analyzing **conversational sequences** using **Gibson’s participation shift framework**. It is *not* a running service or distributed system; the “architecture” is primarily:
- A **Python API surface** (functions/classes users call)
- **Internal modules** that implement parsing/annotation, statistics, and plotting
- **Developer toolchain**: tests, docs site, CI, packaging/release automation

##### Core package (`parshift/`)

- `parshift/__init__.py`

- `parshift/annotation.py`
Likely handles **input normalization and annotation** of conversational data into participation-shift labels/structures (based on the tests and CSV fixtures under `tests/data`).

- `parshift/statistics.py`
Computes **metrics/statistical summaries** on annotated conversations.

- `parshift/plotting.py`
Generates **visualizations** of shifts/metrics (this often depends on the outputs of `annotation` and/or `statistics`).

- `parshift/oo_parshift.py`
Indicates an **object-oriented API** (a “main class” / orchestrator). Architecturally, this is usually the “high-level workflow” component that composes:
- `annotation` (prepare/label data)
- `statistics` (compute measures)

- `parshift/py.typed`
Signals **PEP 561 typing support** (typed library). Include this as a quality/interop note (optional) rather than a functional component.

##### Tests (`tests/`)
- `tests/test_*.py`, `tests/conftest.py`, `tests/data/*.csv`
This is the **verification suite**. It also reveals implied domain objects:
- Inputs: conversation data in CSV/DF forms
- Required columns: e.g., `id`, `target`, `reply` etc. (as indicated by fixture names like `conv_missing_id.csv`)

##### Documentation site (`docs/`)
- `docs/mkdocs.yml`, `docs/docs/*.md`
A **MkDocs** documentation system (with images). This is a separate “Documentation build” component.

##### Build/Release configuration (top-level)
- `pyproject.toml`
**Packaging/build configuration** (dependencies, build backend, dev extras, tooling config).

##### CI/CD (`.github/workflows/`)
- `tests.yml` → test runs
- `cov.yml` → coverage reporting (Codecov)
- `docs.yml` → docs build/deploy to GitHub Pages
- `publish.yml` → publish to PyPI

These are critical to include as the “delivery pipeline” part of the architecture.

##### Library “runtime” architecture (user → API → modules)

**Actors & inputs**
- Actor: *Researcher / analyst / developer (Python user)*
- Inputs: *CSV files / pandas DataFrames* (inferred from tests/data and naming like `df_good.csv`)

**Core components**
- API façade: `parshift` (via `__init__.py`)
- High-level OO interface: `oo_parshift.py` (main orchestrator)
- Functional modules:
- `annotation.py`
- `statistics.py`
- `plotting.py`

**Outputs**
- Annotated conversation structures / labeled sequences
- Statistical results/tables
- Plots/figures

- User code → `parshift` API
- `parshift` API → (either) `oo_parshift` (OO workflow) and/or direct calls to `annotation/statistics/plotting`
- `oo_parshift` → `annotation`
- `oo_parshift` → `statistics`
- `oo_parshift` → `plotting`
- `annotation` → produces “annotated conversation” artifact → consumed by `statistics` and `plotting`

- “Conversation table (CSV/DF)” → “Validated/normalized conversation”
- “Normalized conversation” → “Participation-shift annotations”
- “Annotations” → “Metrics” and “Visualizations”

##### Delivery/tooling architecture (repo → CI → docs/PyPI)
This is the second “system” view: how the package is validated and shipped.

**Components**
- GitHub repository
- GitHub Actions workflows:
- Tests
- Coverage → Codecov
- Docs build → GitHub Pages
- Publish → PyPI
- Artifact outputs:
- Python distribution (wheel/sdist) on PyPI
- Hosted docs website

**Key flows**
- Push/PR → `tests.yml` (pytest)
- Push/PR → `cov.yml` → Codecov
- Push/tag → `publish.yml` → PyPI
- Push/main → `docs.yml` → GitHub Pages (MkDocs)

##### Container (Level 2)
- ParShift library (the package)
- Documentation site (MkDocs → GitHub Pages)
- CI/CD pipeline (GitHub Actions)
- PyPI distribution channel
- Codecov (coverage service)

##### Component (Level 3) inside ParShift
- OO orchestrator (`oo_parshift`)
- Annotation engine (`annotation`)
- Statistics engine (`statistics`)
- Plotting subsystem (`plotting`)
- Public API façade (`__init__`)

That “component inside package” level is the most valuable for maintainers/users.

##### Be explicit about boundaries
- **Runtime boundary**: “User environment (local Python runtime / notebook / Colab)”
- **Repo/DevOps boundary**: “GitHub (CI + docs + release)”

This avoids conflating “how it runs” with “how it’s shipped”.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Context / Runtime Boundary
%% =========================
subgraph "Runtime Boundary: User Environment (Local Python / Notebook / Colab)"
direction TB

User(["Python user\nResearcher / Analyst / Developer"]):::actor

InputData[/"Conversation dataset\n(CSV files / pandas DataFrames)"/]:::artifact

subgraph "ParShift Python Package (parshift/)"
direction TB

API["Public API façade\n(parshift/__init__.py)"]:::api
OOWorkflow["OO workflow / orchestrator\n(oo_parshift)"]:::core
Annotation["Annotation engine\n(input validation + participation-shift labeling)"]:::core
Statistics["Statistics engine\n(metrics computation)"]:::core
Plotting["Plotting subsystem\n(visualization)"]:::core
Typed["Typing marker\n(py.typed, PEP 561)"]:::meta

end

Annotated[/"Annotated conversation\n(participation-shift labels)"/]:::artifact
Metrics[/"Metrics summary\n(tables / aggregates)"/]:::artifact
Figures[/"Plots / Figures"/]:::artifact

%% Runtime flows
User -->|"imports/calls"| API
InputData -->|"provided_as"| API

API -->|"calls"| OOWorkflow
API -->|"direct_calls"| Annotation
API -->|"direct_calls"| Statistics
API -->|"direct_calls"| Plotting

OOWorkflow -->|"validates+labels"| Annotation
Annotation -->|"produces"| Annotated

OOWorkflow -->|"computes"| Statistics
Annotated -->|"consumed_by"| Statistics
Statistics -->|"produces"| Metrics

OOWorkflow -->|"renders"| Plotting
Annotated -->|"consumed_by"| Plotting
Metrics -->|"optional_input"| Plotting
Plotting -->|"produces"| Figures

Typed -.->|"type_info"| API

end

%% =========================
%% Dev/Repo/Delivery Boundary
%% =========================
subgraph "DevOps Boundary: Repository + CI/CD + Publishing"
direction TB

Repo["GitHub repository"]:::repo

subgraph "Build/Config"
direction TB
PyProject["pyproject.toml\n(packaging/build config)"]:::config
end

subgraph "CI: GitHub Actions Workflows (.github/workflows/)"
direction TB
WTests["tests.yml\n(run pytest)"]:::ci
WCov["cov.yml\n(coverage reporting)"]:::ci
WDocs["docs.yml\n(build+deploy docs)"]:::ci
WPublish["publish.yml\n(build+publish to PyPI)"]:::ci
end

subgraph "Verification Suite (tests/)"
direction TB
TestsDir["tests/ (suite)"]:::test
Conftest["conftest.py\n(fixtures)"]:::test
TAnn["test_annotation.py"]:::test
TOO["test_oo_parshift.py"]:::test
TPlot["test_plotting.py"]:::test
TStats["test_statistics.py"]:::test
TestData["tests/data/\n(CSV fixtures)"]:::artifact
end

subgraph "Documentation (docs/ MkDocs)"
direction TB
DocsDir["docs/"]:::docs
MkdocsYml["mkdocs.yml"]:::docs
DocsContent["docs/docs/\n(Markdown pages)"]:::docs
DocsIndex["index.md"]:::docs
DocsRef["reference.md"]:::docs
DocsDev["dev.md"]:::docs
DocsImages["images/"]:::docs
end

Codecov[("Codecov")]:::external
PyPI[("PyPI\n(parshift distribution)")]:::external
GHPages[("GitHub Pages\n(MkDocs site)")]:::external

%% DevOps flows (dashed)
Repo -.->|"uses_config"| PyProject
Repo -.->|"triggers"| WTests
Repo -.->|"triggers"| WCov
Repo -.->|"triggers"| WDocs
Repo -.->|"triggers"| WPublish

WTests -.->|"runs"| TestsDir
TestsDir -.->|"loads_fixtures"| Conftest
TestsDir -.->|"uses_data"| TestData
WTests -.->|"executes"| TAnn
WTests -.->|"executes"| TOO
WTests -.->|"executes"| TPlot
WTests -.->|"executes"| TStats

WCov -.->|"uploads_coverage"| Codecov

WDocs -.->|"builds_with"| DocsDir
DocsDir -.->|"configured_by"| MkdocsYml
DocsDir -.->|"renders"| DocsContent
DocsContent -.->|"includes"| DocsIndex
DocsContent -.->|"includes"| DocsRef
DocsContent -.->|"includes"| DocsDev
DocsContent -.->|"assets"| DocsImages
WDocs -.->|"deploys_to"| GHPages

WPublish -.->|"builds_from"| PyProject
WPublish -.->|"publishes_to"| PyPI

end

%% =========================
%% Click events (from mapping)
%% =========================
click API "https://github.com/bdfsaraiva/parshift/blob/main/parshift/__init__.py"
click Annotation "https://github.com/bdfsaraiva/parshift/blob/main/parshift/annotation.py"
click Statistics "https://github.com/bdfsaraiva/parshift/blob/main/parshift/statistics.py"
click Plotting "https://github.com/bdfsaraiva/parshift/blob/main/parshift/plotting.py"
click OOWorkflow "https://github.com/bdfsaraiva/parshift/blob/main/parshift/oo_parshift.py"
click Typed "https://github.com/bdfsaraiva/parshift/blob/main/parshift/py.typed"

click TestsDir "https://github.com/bdfsaraiva/parshift/tree/main/tests/"
click Conftest "https://github.com/bdfsaraiva/parshift/blob/main/tests/conftest.py"
click TAnn "https://github.com/bdfsaraiva/parshift/blob/main/tests/test_annotation.py"
click TOO "https://github.com/bdfsaraiva/parshift/blob/main/tests/test_oo_parshift.py"
click TPlot "https://github.com/bdfsaraiva/parshift/blob/main/tests/test_plotting.py"
click TStats "https://github.com/bdfsaraiva/parshift/blob/main/tests/test_statistics.py"
click TestData "https://github.com/bdfsaraiva/parshift/tree/main/tests/data/"

click DocsDir "https://github.com/bdfsaraiva/parshift/tree/main/docs/"
click MkdocsYml "https://github.com/bdfsaraiva/parshift/blob/main/docs/mkdocs.yml"
click DocsContent "https://github.com/bdfsaraiva/parshift/tree/main/docs/docs/"
click DocsIndex "https://github.com/bdfsaraiva/parshift/blob/main/docs/docs/index.md"
click DocsRef "https://github.com/bdfsaraiva/parshift/blob/main/docs/docs/reference.md"
click DocsDev "https://github.com/bdfsaraiva/parshift/blob/main/docs/docs/dev.md"
click DocsImages "https://github.com/bdfsaraiva/parshift/tree/main/docs/docs/images/"

click PyProject "https://github.com/bdfsaraiva/parshift/blob/main/pyproject.toml"

click WTests "https://github.com/bdfsaraiva/parshift/blob/main/.github/workflows/tests.yml"
click WCov "https://github.com/bdfsaraiva/parshift/blob/main/.github/workflows/cov.yml"
click WDocs "https://github.com/bdfsaraiva/parshift/blob/main/.github/workflows/docs.yml"
click WPublish "https://github.com/bdfsaraiva/parshift/blob/main/.github/workflows/publish.yml"

%% Also map boundaries/dirs for navigation
click Repo "https://github.com/bdfsaraiva/parshift/tree/main/.github/workflows/"
click API "https://github.com/bdfsaraiva/parshift/tree/main/parshift/"
click DocsDir "https://github.com/bdfsaraiva/parshift/tree/main/docs/"
click TestsDir "https://github.com/bdfsaraiva/parshift/tree/main/tests/"

%% =========================
%% Styles
%% =========================
classDef actor fill:#1e3a8a,stroke:#0b1f4b,color:#ffffff,stroke-width:1.5px
classDef api fill:#0ea5e9,stroke:#075985,color:#062a3a,stroke-width:1.5px
classDef core fill:#a7f3d0,stroke:#047857,color:#064e3b,stroke-width:1.5px
classDef meta fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1.2px,stroke-dasharray: 4 3
classDef artifact fill:#fde68a,stroke:#b45309,color:#3b2f0b,stroke-width:1.5px
classDef repo fill:#f3f4f6,stroke:#374151,color:#111827,stroke-width:1.5px
classDef config fill:#fef3c7,stroke:#92400e,color:#3b2f0b,stroke-width:1.5px
classDef ci fill:#fbcfe8,stroke:#9d174d,color:#4a0d28,stroke-width:1.5px
classDef test fill:#ddd6fe,stroke:#5b21b6,color:#2e1065,stroke-width:1.5px
classDef docs fill:#c7d2fe,stroke:#3730a3,color:#1e1b4b,stroke-width:1.5px
classDef external fill:#ffffff,stroke:#111827,color:#111827,stroke-width:1.5px,stroke-dasharray: 6 4
```
