# menesard/qurananalysis architecture

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

- Interactive diagram: https://gitdiagram.com/menesard/qurananalysis
- Repository: https://github.com/menesard/qurananalysis

## Overview

This is a Python CLI for reproducible Quran counting and mathematical, statistical, and structural analysis. The main workflow fetches Diyanet chapter and verse data, normalizes it into a local JSON corpus, then runs analyses against that corpus without needing further API access. The graph includes text processing, numeric tests, descriptive statistics, and mushaf/revelation-structure analysis. Relationships are based on the README and shown source references; unsampled details are not inferred.

Main entry points: [`quran_analysis/cli.py`](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/cli.py) (Command interface), [`quran_analysis/corpus.py`](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/corpus.py) (Local corpus), [`quran_analysis/analysis/structure.py`](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/structure.py) (Quran structure analysis), [`quran_analysis/client.py`](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/client.py) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_client["API client<br/>[client.py]"]
  node_cache[("Response cache<br/>[cache.py]")]
  node_corpus_builder["Corpus conversion<br/>[corpus.py]"]
  node_corpus_store[("Local corpus<br/>[corpus.py]")]
end

subgraph group_text["Text analysis"]
  node_arabic["Arabic text processing<br/>[arabic.py]"]
  node_counts["Counts and word search<br/>[counts.py]"]
end

subgraph group_patterns["Pattern analysis"]
  node_numeric["Numeric pattern tests<br/>[numeric.py]"]
  node_stats["Statistical analysis<br/>[stats.py]"]
  node_structure["Quran structure analysis<br/>[structure.py]"]
end

subgraph group_interface["User interface"]
  node_cli["Command interface<br/>[cli.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_user(("CLI user"))
node_api{{"Diyanet Quran API"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"builds corpus"| node_corpus_builder
node_cli -->|"creates client"| node_client
node_cli -->|"loads and saves"| node_corpus_store
node_client -->|"requests chapters"| node_api
node_client -->|"reads and writes"| node_cache
node_corpus_builder -->|"fetches verses"| node_client
node_corpus_builder -->|"produces corpus"| node_corpus_store
node_cli -->|"runs count reports"| node_counts
node_cli -->|"runs numeric reports"| node_numeric
node_cli -->|"runs statistics"| node_stats
node_cli -->|"runs structure reports"| node_structure
node_counts -->|"processes text"| node_arabic
node_counts -->|"reads corpus"| node_corpus_store
node_numeric -->|"uses count reports"| node_counts
node_numeric -->|"reads corpus"| node_corpus_store
node_structure -->|"processes text"| node_arabic
node_structure -->|"uses statistics"| node_stats
node_structure -->|"reads corpus"| node_corpus_store

click node_cli "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/cli.py"
click node_settings "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/config.py"
click node_client "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/client.py"
click node_cache "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/cache.py"
click node_corpus_builder "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/corpus.py"
click node_corpus_store "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/corpus.py"
click node_arabic "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/arabic.py"
click node_counts "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/counts.py"
click node_numeric "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/numeric.py"
click node_stats "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/stats.py"
click node_structure "https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/structure.py"

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_client,node_cache,node_corpus_builder,node_corpus_store,node_user toneBlue
class node_arabic,node_counts toneAmber
class node_numeric,node_stats,node_structure,node_api toneMint
class node_cli,node_settings toneRose
```

## Components

### Data ingestion

- [API client](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/client.py): `quran_analysis/client.py`
- [Response cache](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/cache.py): `quran_analysis/cache.py`
- [Corpus conversion](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/corpus.py): `quran_analysis/corpus.py`
- [Local corpus](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/corpus.py): `quran_analysis/corpus.py`

### Text analysis

- [Arabic text processing](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/arabic.py): `quran_analysis/arabic.py`
- [Counts and word search](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/counts.py): `quran_analysis/analysis/counts.py`

### Pattern analysis

- [Numeric pattern tests](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/numeric.py): `quran_analysis/analysis/numeric.py`
- [Statistical analysis](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/stats.py): `quran_analysis/analysis/stats.py`
- [Quran structure analysis](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/analysis/structure.py): `quran_analysis/analysis/structure.py`

### User interface

- [Command interface](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/cli.py): `quran_analysis/cli.py`
- [Runtime settings](https://github.com/menesard/qurananalysis/blob/claude/project-thread-l5aw0g/quran_analysis/config.py): `quran_analysis/config.py`

### Other components

- **CLI user**
- **Diyanet Quran API**

## Connections

- CLI user → Command interface: runs commands (evidence: `README.md`)
- Command interface → Runtime settings: loads settings (evidence: `quran_analysis/cli.py`)
- Command interface → Corpus conversion: builds corpus (evidence: `quran_analysis/cli.py`)
- Command interface → API client: creates client (evidence: `quran_analysis/cli.py`)
- Command interface → Local corpus: loads and saves (evidence: `quran_analysis/cli.py`)
- API client → Diyanet Quran API: requests chapters (evidence: `quran_analysis/client.py`)
- API client → Response cache: reads and writes (evidence: `quran_analysis/client.py`)
- Corpus conversion → API client: fetches verses (evidence: `quran_analysis/corpus.py`)
- Corpus conversion → Local corpus: produces corpus (evidence: `quran_analysis/corpus.py`)
- Command interface → Counts and word search: runs count reports (evidence: `quran_analysis/cli.py`)
- Command interface → Numeric pattern tests: runs numeric reports (evidence: `quran_analysis/cli.py`)
- Command interface → Statistical analysis: runs statistics (evidence: `quran_analysis/cli.py`)
- Command interface → Quran structure analysis: runs structure reports (evidence: `quran_analysis/cli.py`)
- Counts and word search → Arabic text processing: processes text (evidence: `quran_analysis/analysis/counts.py`)
- Counts and word search → Local corpus: reads corpus (evidence: `quran_analysis/analysis/counts.py`)
- Numeric pattern tests → Counts and word search: uses count reports (evidence: `quran_analysis/analysis/numeric.py`)
- Numeric pattern tests → Local corpus: reads corpus (evidence: `quran_analysis/analysis/numeric.py`)
- Quran structure analysis → Arabic text processing: processes text (evidence: `quran_analysis/analysis/structure.py`)
- Quran structure analysis → Statistical analysis: uses statistics (evidence: `quran_analysis/analysis/structure.py`)
- Quran structure analysis → Local corpus: reads corpus (evidence: `quran_analysis/analysis/structure.py`)