# yazinsai/tilawa architecture

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

- Interactive diagram: https://gitdiagram.com/yazinsai/tilawa
- Repository: https://github.com/yazinsai/tilawa

## Overview

Tilawa is an offline Quran-recitation recognition product: callers provide 16 kHz audio and receive verse matches, transcript and progress events. The primary path is audio chunks into a core session, through Zipformer inference and streaming phoneme/verse tracking, then events to a caller or the web interface. FastConformer is a documented alternate engine for one-shot transcription. The frontend adds word-level correction and reporting. Core relationships are supported by the README and indexed imports; some runtime wiring is not shown in the sampled excerpts, so uncertain links are omitted.

Main entry points: [`packages/core/src/recitation/session.ts`](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/session.ts) (Recognition session), [`packages/core/src/recitation/engine.ts`](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/engine.ts) (Streaming engine), [`web/frontend/src/main.ts`](https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/main.ts) (Web interface), [`packages/core/src/recitation/search.ts`](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/search.ts) (Verse search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session API"]
  node_api["Recognition session<br/>[session.ts]"]
  node_fastsession["FastConformer session<br/>[session.ts]"]
end

subgraph group_inference["Audio inference"]
  node_posteriors["Frame posteriors<br/>[posteriors.ts]"]
  node_ziprunner["Zipformer runner<br/>[zipformerRunner.ts]"]
  node_fbank["Feature extraction<br/>[fbank.ts]"]
end

subgraph group_recognition["Verse recognition"]
  node_engine["Streaming engine<br/>[engine.ts]"]
  node_config["Engine settings<br/>[config.ts]"]
  node_corpus[("Verse corpus<br/>[corpus.ts]")]
  node_ctc["CTC decoding<br/>[ctcDecoder.ts]"]
  node_align["Phoneme alignment<br/>[alignment.ts]"]
  node_cost["Phoneme costs<br/>[phonemeCost.ts]"]
  node_search["Verse search<br/>[search.ts]"]
  node_tracker["Word tracker<br/>[tracker.ts]"]
  node_correction["Correction analysis<br/>[correction.ts]"]
  node_slip["Slip detection<br/>[slipHead.ts]"]
  node_structural["Structural checks<br/>[structural.ts]"]
  node_qurandb[("Display Quran data<br/>[quran-db.ts]")]
  node_legacytracker["FastConformer tracker<br/>[tracker.ts]"]
end

subgraph group_interaction["Web experience"]
  node_frontend["Web interface<br/>[main.ts]"]
  node_worker["Web session worker"]
  node_correctionview["Correction view<br/>[correction-view.ts]"]
  node_report["User reports<br/>[report-dialog.ts]"]
  node_audioinput["Microphone chunks<br/>[audio-processor.js]"]
end

node_caller(("Audio caller"))
node_ort["ONNX Runtime"]

node_caller -->|"feeds audio"| node_api
node_api -->|"streams chunks"| node_engine
node_engine -->|"expands tokens"| node_ctc
node_engine -->|"aligns text"| node_align
node_engine -->|"tracks words"| node_tracker
node_engine -->|"locates verses"| node_search
node_search -->|"aligns candidates"| node_align
node_search -->|"scores phonemes"| node_cost
node_api -->|"loads corpus"| node_corpus
node_api -->|"resolves display data"| node_qurandb
node_api -->|"checks structure"| node_structural
node_api -->|"uses slip head"| node_slip
node_api -->|"processes posteriors"| node_posteriors
node_api -->|"runs Zipformer"| node_ziprunner
node_ziprunner -->|"runs ONNX"| node_ort
node_api -->|"extracts features"| node_fbank
node_api -->|"selects alternate engine"| node_fastsession
node_fastsession -.->|"tracks transcript"| node_legacytracker
node_api -.->|"analyzes corrections"| node_correction
node_audioinput -.->|"sends chunks"| node_worker
node_frontend -.->|"starts session"| node_worker
node_worker -->|"creates session"| node_api
node_frontend -->|"shows corrections"| node_correctionview
node_frontend -->|"opens report"| node_report

click node_api "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/session.ts"
click node_fastsession "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/session.ts"
click node_engine "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/engine.ts"
click node_config "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/config.ts"
click node_corpus "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/corpus.ts"
click node_ctc "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/ctcDecoder.ts"
click node_posteriors "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/posteriors.ts"
click node_align "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/alignment.ts"
click node_cost "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/phonemeCost.ts"
click node_search "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/search.ts"
click node_tracker "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/tracker.ts"
click node_correction "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/correction.ts"
click node_slip "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/slipHead.ts"
click node_structural "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/structural.ts"
click node_qurandb "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/quran-db.ts"
click node_legacytracker "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/tracker.ts"
click node_ziprunner "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/zipformerRunner.ts"
click node_fbank "https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/fbank.ts"
click node_frontend "https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/main.ts"
click node_worker "https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/worker/zipformer-session.ts"
click node_correctionview "https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/correction-view.ts"
click node_report "https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/report-dialog.ts"
click node_audioinput "https://github.com/yazinsai/tilawa/blob/main/web/frontend/public/audio-processor.js"

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_api,node_fastsession toneBlue
class node_posteriors,node_ziprunner,node_fbank toneAmber
class node_engine,node_config,node_corpus,node_ctc,node_align,node_cost,node_search,node_tracker,node_correction,node_slip,node_structural,node_qurandb,node_legacytracker toneMint
class node_frontend,node_worker,node_correctionview,node_report,node_audioinput toneRose
class node_caller,node_ort toneIndigo
```

## Components

### Session API

- [Recognition session](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/session.ts): `packages/core/src/recitation/session.ts`
- [FastConformer session](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/session.ts): `packages/core/src/session.ts`

### Audio inference

- [Frame posteriors](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/posteriors.ts): `packages/core/src/recitation/posteriors.ts`
- [Zipformer runner](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/zipformerRunner.ts): `packages/core/src/recitation/zipformerRunner.ts`
- [Feature extraction](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/fbank.ts): `packages/core/src/recitation/fbank.ts`

### Verse recognition

- [Streaming engine](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/engine.ts): `packages/core/src/recitation/engine.ts`
- [Engine settings](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/config.ts): `packages/core/src/recitation/config.ts`
- [Verse corpus](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/corpus.ts): `packages/core/src/recitation/corpus.ts`
- [CTC decoding](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/ctcDecoder.ts): `packages/core/src/recitation/ctcDecoder.ts`
- [Phoneme alignment](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/alignment.ts): `packages/core/src/recitation/alignment.ts`
- [Phoneme costs](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/phonemeCost.ts): `packages/core/src/recitation/phonemeCost.ts`
- [Verse search](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/search.ts): `packages/core/src/recitation/search.ts`
- [Word tracker](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/tracker.ts): `packages/core/src/recitation/tracker.ts`
- [Correction analysis](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/correction.ts): `packages/core/src/recitation/correction.ts`
- [Slip detection](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/slipHead.ts): `packages/core/src/recitation/slipHead.ts`
- [Structural checks](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/recitation/structural.ts): `packages/core/src/recitation/structural.ts`
- [Display Quran data](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/quran-db.ts): `packages/core/src/quran-db.ts`
- [FastConformer tracker](https://github.com/yazinsai/tilawa/blob/main/packages/core/src/tracker.ts): `packages/core/src/tracker.ts`

### Web experience

- [Web interface](https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/main.ts): `web/frontend/src/main.ts`
- [Web session worker](https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/worker/zipformer-session.ts): `web/frontend/src/worker/zipformer-session.ts`
- [Correction view](https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/correction-view.ts): `web/frontend/src/correction-view.ts`
- [User reports](https://github.com/yazinsai/tilawa/blob/main/web/frontend/src/report-dialog.ts): `web/frontend/src/report-dialog.ts`
- [Microphone chunks](https://github.com/yazinsai/tilawa/blob/main/web/frontend/public/audio-processor.js): `web/frontend/public/audio-processor.js`

### Other components

- **Audio caller**
- **ONNX Runtime**

## Connections

- Audio caller → Recognition session: feeds audio (evidence: `README.md`)
- Recognition session → Streaming engine: streams chunks (evidence: `packages/core/src/recitation/session.ts`)
- Streaming engine → CTC decoding: expands tokens (evidence: `packages/core/src/recitation/engine.ts`)
- Streaming engine → Phoneme alignment: aligns text (evidence: `packages/core/src/recitation/engine.ts`)
- Streaming engine → Word tracker: tracks words (evidence: `packages/core/src/recitation/engine.ts`)
- Streaming engine → Verse search: locates verses (evidence: `packages/core/src/recitation/engine.ts`)
- Verse search → Phoneme alignment: aligns candidates (evidence: `packages/core/src/recitation/search.ts`)
- Verse search → Phoneme costs: scores phonemes (evidence: `packages/core/src/recitation/search.ts`)
- Recognition session → Verse corpus: loads corpus (evidence: `packages/core/src/recitation/session.ts`)
- Recognition session → Display Quran data: resolves display data (evidence: `packages/core/src/recitation/session.ts`)
- Recognition session → Structural checks: checks structure (evidence: `packages/core/src/recitation/session.ts`)
- Recognition session → Slip detection: uses slip head (evidence: `packages/core/src/recitation/session.ts`)
- Recognition session → Frame posteriors: processes posteriors (evidence: `packages/core/src/recitation/session.ts`)
- Recognition session → Zipformer runner: runs Zipformer (evidence: `README.md`)
- Zipformer runner → ONNX Runtime: runs ONNX (evidence: `README.md`)
- Recognition session → Feature extraction: extracts features (evidence: `packages/core/src/recitation/session.ts`)
- Recognition session → FastConformer session: selects alternate engine (evidence: `README.md`)
- FastConformer session → FastConformer tracker: tracks transcript
- Recognition session → Correction analysis: analyzes corrections (evidence: `packages/core/src/recitation/session.ts`)
- Microphone chunks → Web session worker: sends chunks
- Web interface → Web session worker: starts session
- Web session worker → Recognition session: creates session (evidence: `web/frontend/src/worker/zipformer-session.ts`)
- Web interface → Correction view: shows corrections (evidence: `web/frontend/src/main.ts`)
- Web interface → User reports: opens report (evidence: `web/frontend/src/main.ts`)
