# etcbc/bhsa architecture

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

- Interactive diagram: https://gitdiagram.com/etcbc/bhsa
- Repository: https://github.com/etcbc/bhsa

## Overview

##### Project type and purpose
- This is an open-source data-centric toolset and repository (“bhsa”) that provides the Hebrew Bible with linguistic annotations in the Text-Fabric format.
- It bundles:
– A data storage layer of multiple versions of the BHSA data (MQL files, Text-Fabric feature files, YAML config)
– A data processing layer (Python programs and Jupyter notebooks) to generate, analyze, and transform the data
– A minimal web application (static search interface and a small Flask-style app)
– Extensive documentation and tutorials

##### File structure
- Top-level “storage” directories:
– source/ (raw ETCBC MQL exports)
– tf/ (Text-Fabric feature tables per version)
– shebanq/ (intermediate SQL dumps for the SHEBANQ site)
– yaml/ (configuration schemas for features)
- Data processing:
– programs/ (Python scripts + notebooks)
– primer/ (utility module + example notebooks)
– ner/ (named-entity config and sheets)
- Application layer:
– app/app.py (entry point of the static search server)
– app/config.yaml (app configuration)
– app/static/ (HTML/CSS/JS for browser UI)
- Documentation layer:
– docs/ + mkdocs.yml (feature docs, reference PDFs)
– tutorial/ (Jupyter notebooks illustrating TF API usage)
- UI prototypes:
– ui/ (example Python UI layouts)

##### README for additional insights
- Describes usage via the Text-Fabric library (tf.app.use) and the static web interface (“bhsa-search”).
- Mentions external dependencies: Text-Fabric and Python environment, Jupyter for notebooks.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Data Storage Layer
  subgraph "Data Storage"
    source[(source/)]:::storage
    tf[(tf/)]:::storage
    shebanq[(shebanq/)]:::storage
    yaml[(yaml/)]:::storage
  end

  %% Data Processing Layer
  subgraph "Data Processing"
    programs[programs/]:::processing
    primer[/ "primer/util.py + notebooks" /]:::processing
    ner_config["ner/config.yaml"]:::processing
    ner_sheets[ner/sheets/]:::processing
  end

  %% Application Layer
  subgraph "Application Layer"
    app_py["app/app.py"]:::application
    app_cfg["app/config.yaml"]:::application
    static["app/static/"]:::application
    browser(("User Browser")):::external
  end

  %% Documentation Layer
  subgraph "Documentation Layer"
    docs_src[docs/]:::docs
    mkdocs_cfg["mkdocs.yml"]:::docs
    tutorial[tutorial/]:::docs
  end

  %% UI Prototypes
  subgraph "UI Prototypes"
    ui["ui/"]:::processing
  end

  %% External Dependencies
  subgraph "External Dependencies"
    TextFabric(("Text-Fabric Library")):::external
    Python(("Python Runtime")):::external
    Jupyter(("Jupyter")):::external
  end

  %% Relationships
  source --> programs
  tf --> programs
  shebanq --> programs
  yaml --> programs
  programs --> tf
  primer --> tf
  ner_config --> programs
  ner_sheets --> programs
  TextFabric --> app_py
  Python --> app_py
  Jupyter --> programs
  app_cfg --> app_py
  app_py --> static
  app_py --> browser
  docs_src --> browser
  tutorial --> browser
  mkdocs_cfg --> docs_src

  %% Click Events
  click source "https://github.com/etcbc/bhsa/tree/master/source/"
  click tf "https://github.com/etcbc/bhsa/tree/master/tf/"
  click shebanq "https://github.com/etcbc/bhsa/tree/master/shebanq/"
  click yaml "https://github.com/etcbc/bhsa/tree/master/yaml/"
  click programs "https://github.com/etcbc/bhsa/tree/master/programs/"
  click primer "https://github.com/etcbc/bhsa/blob/master/primer/util.py"
  click ner_config "https://github.com/etcbc/bhsa/blob/master/ner/config.yaml"
  click ner_sheets "https://github.com/etcbc/bhsa/tree/master/ner/sheets/"
  click app_py "https://github.com/etcbc/bhsa/blob/master/app/app.py"
  click app_cfg "https://github.com/etcbc/bhsa/blob/master/app/config.yaml"
  click static "https://github.com/etcbc/bhsa/tree/master/app/static/"
  click docs_src "https://github.com/etcbc/bhsa/tree/master/docs/"
  click mkdocs_cfg "https://github.com/etcbc/bhsa/blob/master/mkdocs.yml"
  click tutorial "https://github.com/etcbc/bhsa/tree/master/tutorial/"
  click ui "https://github.com/etcbc/bhsa/tree/master/ui/"

  %% Styles
  classDef storage fill:#f9f,stroke:#333,stroke-width:1px;
  classDef processing fill:#ff9,stroke:#333,stroke-width:1px;
  classDef application fill:#9f9,stroke:#333,stroke-width:1px;
  classDef docs fill:#9cf,stroke:#333,stroke-width:1px;
  classDef external fill:#ccc,stroke:#333,stroke-width:1px,stroke-dasharray:5 5;
```
