# badreddinebensalahengineering/qr-cache-builder architecture

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

- Interactive diagram: https://gitdiagram.com/badreddinebensalahengineering/qr-cache-builder
- Repository: https://github.com/badreddinebensalahengineering/qr-cache-builder

## Overview

This local Flask tool helps an operator enrich a bilingual chatbot Q&A cache: enter a question, inspect similar groups, generate and assess French/English reformulations, select variants, provide answers, and save or edit a group. The browser calls Flask endpoints; the server coordinates language detection, paraphrase generation, semantic collision/novelty scoring, translation, and JSON persistence. Groq is used when configured; otherwise generation falls back to local Ollama, with rule-based paraphrasers as another fallback. The excerpts show key calls, but not every route or UI interaction.

Main entry points: [`app.py`](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/app.py) (Flask workflow), [`static/app.js`](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/static/app.js) (Question editor), [`llm_paraphraser.py`](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/llm_paraphraser.py) (LLM paraphrases), [`rule_paraphraser.py`](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/rule_paraphraser.py) (English rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator interface"]
  node_browser["Question editor<br/>[app.js]"]
end

subgraph group_api["Application API"]
  node_server["Flask workflow<br/>[app.py]"]
end

subgraph group_language["Language and generation"]
  node_paraphrases["LLM paraphrases<br/>[llm_paraphraser.py]"]
  node_english_rules["English rules"]
  node_french_rules["French rules"]
  node_translation["Language detection and translation<br/>[translator.py]"]
end

subgraph group_quality["Matching and persistence"]
  node_similarity["Semantic matching and scoring<br/>[app.py]"]
  node_text_cleanup["Text deduplication<br/>[text_utils.py]"]
  node_qa_store[("Q&amp;A groups")]
end

node_operator(("Operator"))
node_groq{{"Groq API"}}
node_ollama{{"Ollama service"}}

node_operator -->|"enters questions"| node_browser
node_browser -->|"requests suggestions"| node_server
node_browser -->|"saves groups"| node_server
node_browser -->|"requests translation"| node_server
node_server -->|"reads and writes"| node_qa_store
node_server -->|"detects and translates"| node_translation
node_server -->|"generates variants"| node_paraphrases
node_server -->|"uses fallback"| node_english_rules
node_server -->|"uses fallback"| node_french_rules
node_server -->|"scores candidates"| node_similarity
node_server -->|"deduplicates variants"| node_text_cleanup
node_paraphrases -.->|"calls when configured"| node_groq
node_paraphrases -.->|"calls otherwise"| node_ollama

click node_browser "https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/static/app.js"
click node_server "https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/app.py"
click node_paraphrases "https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/llm_paraphraser.py"
click node_english_rules "https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/rule_paraphraser.py"
click node_french_rules "https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/rule_paraphraser_fr.py"
click node_translation "https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/translator.py"
click node_similarity "https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/app.py"
click node_text_cleanup "https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/text_utils.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_browser toneBlue
class node_server toneAmber
class node_paraphrases,node_english_rules,node_french_rules,node_translation,node_groq toneMint
class node_similarity,node_text_cleanup,node_qa_store toneRose
class node_operator,node_ollama toneIndigo
```

## Components

### Operator interface

- [Question editor](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/static/app.js): `static/app.js`

### Application API

- [Flask workflow](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/app.py): `app.py`

### Language and generation

- [LLM paraphrases](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/llm_paraphraser.py): `llm_paraphraser.py`
- [English rules](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/rule_paraphraser.py): `rule_paraphraser.py`
- [French rules](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/rule_paraphraser_fr.py): `rule_paraphraser_fr.py`
- [Language detection and translation](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/translator.py): `translator.py`

### Matching and persistence

- [Semantic matching and scoring](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/app.py): `app.py`
- [Text deduplication](https://github.com/badreddinebensalahengineering/qr-cache-builder/blob/master/text_utils.py): `text_utils.py`
- **Q&A groups**

### Other components

- **Operator**
- **Groq API**
- **Ollama service**

## Connections

- Operator → Question editor: enters questions (evidence: `static/app.js`)
- Question editor → Flask workflow: requests suggestions (evidence: `static/app.js`)
- Question editor → Flask workflow: saves groups (evidence: `static/app.js`)
- Question editor → Flask workflow: requests translation (evidence: `static/app.js`)
- Flask workflow → Q&A groups: reads and writes (evidence: `app.py`)
- Flask workflow → Language detection and translation: detects and translates (evidence: `app.py`)
- Flask workflow → LLM paraphrases: generates variants (evidence: `app.py`)
- Flask workflow → English rules: uses fallback (evidence: `app.py`)
- Flask workflow → French rules: uses fallback (evidence: `app.py`)
- Flask workflow → Semantic matching and scoring: scores candidates (evidence: `app.py`)
- Flask workflow → Text deduplication: deduplicates variants (evidence: `app.py`)
- LLM paraphrases → Groq API: calls when configured (evidence: `llm_paraphraser.py`)
- LLM paraphrases → Ollama service: calls otherwise (evidence: `llm_paraphraser.py`)
