# shreyanmitra/tabalchi architecture

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

- Interactive diagram: https://gitdiagram.com/shreyanmitra/tabalchi
- Repository: https://github.com/shreyanmitra/tabalchi

## Overview

1. **What this repository is**
   - Tabalchi is primarily a **Python library for tabla composition parsing, playback, notation export, generation, and transcription**.
   - It also includes a **minimal browser UI** (`index.html`) and a **Python backend shim** (`Tabalchi/web_backend.py`) for serving or wiring the UI to library capabilities.

2. **Core input format**
   - The main artifact is a **`.tabla` file**, which the README says is **JSON-compatible** and describes a composition.
   - These files define things like **composition type**, **taal**, **speed**, **jati**, **playing style**, and nested musical structure such as `mainTheme`, `paltas`, and `tihai`.

3. **Central parsing and domain layer**
   - `Tabalchi/main.py` appears to be the heart of the library, centered on **`BolParser`**.
   - Parsing converts a `.tabla` document into a domain model made of **`Bol`**, **`Beat`**, **`Phrase`**, and supporting musical classes.
   - The parser also handles syntax rules like beat separators, grouped phrases, and inference markers described in the README.

4. **Musical metadata model**
   - The repository models tabla-specific concepts explicitly:
     - **`Taal`** for rhythmic cycles
     - **`Jati`** for subdivision pattern
     - **`Speed` / `SpeedClasses`** for tempo handling
     - **`BeatRange`** for beat-interval logic
     - **`CompositionType`** for validating composition schemas
   - This is the main abstraction boundary between raw text input and musical behavior.

5. **Playback and audio subsystem**
   - The playback path runs from parsed `Bol` down to **`Beat` → `Phrase` → `Sound`**.
   - `Sound` and `Fetcher` provide the audio material for individual bols/phrases, and the README indicates the project ships with **recorded tabla samples** in the `recordings/` directory.
   - Playback is therefore **sample-based**, not MIDI-based.

6. **Audio dependencies and external tools**
   - The README makes **`ffmpeg`** important for audio handling, especially tempo-adjusted playback.
   - It also mentions **`acoustid-fingerprinter`** for transcription-related workflows.
   - These are system-level dependencies that materially affect how the audio pipeline functions.

7. **Notation export path**
   - The same parsed `Bol` can be rendered into textual notation through the abstract **`Notation`** layer.
   - Concrete notation formats include **`Bhatkande`** and **`Paluskar`**.
   - So the output path is: `.tabla` → parser/domain model → notation renderer → `.txt`/`.pdf`-style output files.

8. **Generation subsystem**
   - `CompositionGenerator` is a separate capability for **creating compositions from parameters** such as type, taal, speed class, jati, and school.
   - The README shows it can use either:
     - a **local model/endpoint** first, or
     - a **hosted Hugging Face-backed flow**
   - This makes generation an optional AI-assisted subsystem, not part of the core parser.

9. **Transcription subsystem**
   - `AudioToBolConvertor` is the reverse pipeline: **audio recording → bol transcription**.
   - This likely depends on the audio tooling above and sits as a distinct feature next to parsing/playback rather than inside them.

10. **Web/UI layer**
   - `index.html` is the standalone front-end entrypoint, and `.github/workflows/pages.yml` deploys it to **GitHub Pages**.
   - `Tabalchi/web_backend.py` suggests a thin backend used to bridge browser interactions to Python-side parsing, playback, or generation.
   - Architecturally, this is separate from the package’s core library and looks like an optional presentation layer.

11. **Packaging and distribution**
   - The repo is packaged as a Python distribution using **`pyproject.toml`**, **`setup.py`**, and **`MANIFEST.in`**.
   - This indicates the same codebase serves both as an importable library and as a published package.

12. **Build and release automation**
   - `.github/workflows/publish.yml` handles **PyPI release publishing** from GitHub Actions.
   - The workflow is connected to release creation and validates the built package before upload.
   - This is the main CI/CD boundary for distribution.

13. **Key data/assets**
   - `template.tabla` is the reference composition template and likely the simplest input artifact for the parser.
   - `recordings/*.m4a` are essential runtime assets for sound playback, and they are part of the repository rather than fetched dynamically.

14. **Architecture summary**
   - The dominant flow is: **`.tabla` composition spec → parser/domain model → either playback, notation export, generation, or transcription**.
   - The repo therefore has three clear layers:
     1. **Core library and musical model**
     2. **Audio/sample handling**
     3. **UI/distribution tooling** via GitHub Pages and PyPI

Main entry points: [`Tabalchi/main.py`](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py) (Musical model), [`Tabalchi/web_backend.py`](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/web_backend.py) (Web backend), [`.github/workflows/publish.yml`](https://github.com/shreyanmitra/tabalchi/blob/main/.github/workflows/publish.yml) (Publish workflow), [`index.html`](https://github.com/shreyanmitra/tabalchi/blob/main/index.html) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_template_tabla["Template<br/>tabla spec<br/>[template.tabla]"]
  node_main_module["Main module<br/>library module<br/>[main.py]"]
  node_bol_parser["Bol Parser<br/>[main.py]"]
  node_musical_model{{"Musical model<br/>domain model<br/>[main.py]"}}
  node_notation_export["Notation export<br/>renderer<br/>[main.py]"]
  node_playback_pipeline["Playback<br/>sample audio<br/>[main.py]"]
  node_generator["Generator<br/>composition AI<br/>[main.py]"]
  node_transcription["Transcription<br/>audio to bol<br/>[main.py]"]
end

subgraph group_audio["Audio assets"]
  node_recordings[("Samples<br/>audio assets")]
end

subgraph group_ui["Web UI"]
  node_web_backend["Web backend<br/>bridge module<br/>[web_backend.py]"]
  node_index_html["Browser UI<br/>frontend<br/>[index.html]"]
end

subgraph group_packaging["Packaging"]
  node_pyproject["Build config<br/>package metadata<br/>[pyproject.toml]"]
  node_setup_py["Setup script<br/>package metadata<br/>[setup.py]"]
end

subgraph group_automation["CI/CD"]
  node_pages_workflow["Pages deploy<br/>github action<br/>[pages.yml]"]
  node_publish_workflow["Publish workflow<br/>github action<br/>[publish.yml]"]
end

node_template_tabla -->|"input spec"| node_bol_parser
node_main_module -->|"contains"| node_bol_parser
node_bol_parser -->|"builds"| node_musical_model
node_musical_model -->|"renders to"| node_notation_export
node_musical_model -->|"drives"| node_playback_pipeline
node_musical_model -->|"parameters for"| node_generator
node_musical_model -->|"targets"| node_transcription
node_playback_pipeline -->|"uses samples"| node_recordings
node_web_backend -->|"bridges"| node_main_module
node_index_html -->|"calls"| node_web_backend
node_pages_workflow -->|"deploys"| node_index_html
node_pyproject -->|"packages"| node_main_module
node_setup_py -->|"packages"| node_main_module
node_publish_workflow -->|"builds from"| node_pyproject
node_publish_workflow -->|"builds from"| node_setup_py
node_playback_pipeline -.->|"exposed via"| node_web_backend
node_generator -.->|"exposed via"| node_web_backend
node_transcription -.->|"exposed via"| node_web_backend

click node_template_tabla "https://github.com/shreyanmitra/tabalchi/blob/main/template.tabla"
click node_main_module "https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py"
click node_bol_parser "https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py"
click node_musical_model "https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py"
click node_notation_export "https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py"
click node_playback_pipeline "https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py"
click node_generator "https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py"
click node_transcription "https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py"
click node_web_backend "https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/web_backend.py"
click node_index_html "https://github.com/shreyanmitra/tabalchi/blob/main/index.html"
click node_recordings "https://github.com/shreyanmitra/tabalchi/tree/main/recordings"
click node_pyproject "https://github.com/shreyanmitra/tabalchi/blob/main/pyproject.toml"
click node_setup_py "https://github.com/shreyanmitra/tabalchi/blob/main/setup.py"
click node_pages_workflow "https://github.com/shreyanmitra/tabalchi/blob/main/.github/workflows/pages.yml"
click node_publish_workflow "https://github.com/shreyanmitra/tabalchi/blob/main/.github/workflows/publish.yml"

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_template_tabla,node_main_module,node_bol_parser,node_musical_model,node_notation_export,node_playback_pipeline,node_generator,node_transcription toneBlue
class node_recordings toneAmber
class node_web_backend,node_index_html toneMint
class node_pyproject,node_setup_py toneRose
class node_pages_workflow,node_publish_workflow toneIndigo
```

## Components

### Core library

Parsing, domain model, and feature pipelines for tabla compositions.

- [Template](https://github.com/shreyanmitra/tabalchi/blob/main/template.tabla): tabla spec · Reference composition document and example input format. · `template.tabla`
- [Main module](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py): library module · Primary Python module containing parsing, model, and feature logic. · `Tabalchi/main.py`
- [Bol Parser](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py): parser · Converts .tabla documents into the internal musical representation. · `Tabalchi/main.py`
- [Musical model](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py): domain model · Tabla concepts such as Bol, Beat, Phrase, Taal, Jati, Speed, and BeatRange. · `Tabalchi/main.py`
- [Notation export](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py): renderer · Abstract notation layer with concrete formats like Bhatkande and Paluskar. · `Tabalchi/main.py`
- [Playback](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py): sample audio · Sample-based playback path from parsed bols to sounds and phrases. · `Tabalchi/main.py`
- [Generator](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py): composition AI · Creates compositions from rhythmic parameters, optionally via hosted or local models. · `Tabalchi/main.py`
- [Transcription](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/main.py): audio to bol · Converts audio recordings into bol sequences. · `Tabalchi/main.py`

### Audio assets

Recorded samples used by sample-based playback and related tooling.

- [Samples](https://github.com/shreyanmitra/tabalchi/tree/main/recordings): audio assets · Recorded tabla samples used by playback and audio matching. · `recordings`

### Web UI

Minimal browser entrypoint and backend bridge.

- [Web backend](https://github.com/shreyanmitra/tabalchi/blob/main/Tabalchi/web_backend.py): bridge module · Thin Python shim for wiring browser interactions to library capabilities. · `Tabalchi/web_backend.py`
- [Browser UI](https://github.com/shreyanmitra/tabalchi/blob/main/index.html): frontend · Standalone HTML entrypoint for the minimal web interface. · `index.html`

### Packaging

Python distribution metadata and build inputs.

- [Build config](https://github.com/shreyanmitra/tabalchi/blob/main/pyproject.toml): package metadata · Modern Python packaging configuration and dependencies. · `pyproject.toml`
- [Setup script](https://github.com/shreyanmitra/tabalchi/blob/main/setup.py): package metadata · Legacy packaging entrypoint for building and distributing the library. · `setup.py`

### CI/CD

GitHub Actions workflows for site and package publishing.

- [Pages deploy](https://github.com/shreyanmitra/tabalchi/blob/main/.github/workflows/pages.yml): github action · Deploys the browser UI to GitHub Pages. · `.github/workflows/pages.yml`
- [Publish workflow](https://github.com/shreyanmitra/tabalchi/blob/main/.github/workflows/publish.yml): github action · Builds and publishes the Python package to PyPI. · `.github/workflows/publish.yml`

## Connections

- Template → Bol Parser: input spec · Template composition documents are parsed by the core parser.
- Main module → Bol Parser: contains · The main module houses the parser entrypoint.
- Bol Parser → Musical model: builds · Parsing produces the internal tabla domain model.
- Musical model → Notation export: renders to · The shared model feeds notation rendering.
- Musical model → Playback: drives · The same model is used to sequence sample playback.
- Musical model → Generator: parameters for · Composition generation uses rhythmic and stylistic metadata.
- Musical model → Transcription: targets · Transcription outputs bols in the same domain language.
- Playback → Samples: uses samples · Playback resolves bols to recorded tabla sounds.
- Web backend → Main module: bridges · Backend shim exposes library features to the UI.
- Browser UI → Web backend: calls · Browser UI interacts with the Python backend bridge.
- Pages deploy → Browser UI: deploys · GitHub Pages publishes the standalone HTML UI.
- Build config → Main module: packages · Packaging configuration includes the Python library module.
- Setup script → Main module: packages · Legacy setup script builds the library distribution.
- Publish workflow → Build config: builds from · Release automation uses the package configuration.
- Publish workflow → Setup script: builds from · Release automation also supports the legacy setup path.
- Playback → Web backend: exposed via · Playback capabilities can be wired through the backend shim.
- Generator → Web backend: exposed via · Generation features can also surface through the backend shim.
- Transcription → Web backend: exposed via · Transcription workflows may be routed through the browser bridge.