# karslioglu/oxford3000 architecture

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

- Interactive diagram: https://gitdiagram.com/karslioglu/oxford3000
- Repository: https://github.com/karslioglu/oxford3000

## Overview

Oxford 3000 is a command-line pipeline that downloads the Oxford word-list PDF, parses word/part-of-speech/CEFR records into SQLite, enriches records with Turkish translations and example sentences, and produces CSV, Excel, and pronunciation files. The README documents these capabilities; the shown code confirms the CLI routing, PDF parsing and SQLite writing, database reads, and external-service calls. The graph omits unsampled implementation details and includes only relationships supported by the excerpts or README.

Main entry points: [`oxford3000.py`](https://github.com/karslioglu/oxford3000/blob/main/oxford3000.py) (Command router), [`scripts/db_reader.py`](https://github.com/karslioglu/oxford3000/blob/main/scripts/db_reader.py) (Word reader), [`scripts/export_sqlite.py`](https://github.com/karslioglu/oxford3000/blob/main/scripts/export_sqlite.py) (Oxford database), [`scripts/translate.py`](https://github.com/karslioglu/oxford3000/blob/main/scripts/translate.py) (Turkish translation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["PDF ingestion"]
  node_cli["Command router<br/>[oxford3000.py]"]
  node_downloader["PDF downloader<br/>[download_pdf.py]"]
  node_parser["PDF parser<br/>[pdf_parser.py]"]
  node_sqlite_export["SQLite importer<br/>[export_sqlite.py]"]
end

subgraph group_enrich["Database enrichment"]
  node_translator["Turkish translation<br/>[translate.py]"]
  node_examples["Example sentences<br/>[examples.py]"]
end

subgraph group_outputs["Exports and audio"]
  node_csv_export["CSV export<br/>[export_csv.py]"]
  node_xlsx_export["Excel export<br/>[export_xlsx.py]"]
  node_sounds["Pronunciation downloader<br/>[sounds.py]"]
end

subgraph group_storage["Shared storage"]
  node_database[("Oxford database<br/>[export_sqlite.py]")]
  node_reader["Word reader<br/>[db_reader.py]"]
end

node_operator(("CLI user"))
node_oxford(("Oxford PDF source"))
node_gemini(("Gemini API"))
node_sound_service(("Sound of Text"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"dispatches download"| node_downloader
node_oxford -->|"serves PDF"| node_downloader
node_cli -->|"dispatches import"| node_sqlite_export
node_sqlite_export -->|"calls parse_pdf"| node_parser
node_sqlite_export -->|"writes records"| node_database
node_cli -->|"dispatches translate"| node_translator
node_translator -->|"requests translations"| node_gemini
node_translator -->|"updates translations"| node_database
node_cli -->|"dispatches examples"| node_examples
node_examples -->|"requests sentences"| node_gemini
node_examples -->|"writes examples"| node_database
node_cli -->|"dispatches CSV"| node_csv_export
node_cli -->|"dispatches Excel"| node_xlsx_export
node_cli -->|"dispatches audio"| node_sounds
node_csv_export -->|"fetches words"| node_reader
node_xlsx_export -->|"fetches words"| node_reader
node_sounds -->|"fetches words"| node_reader
node_reader -->|"reads words"| node_database
node_sounds -->|"requests audio"| node_sound_service

click node_cli "https://github.com/karslioglu/oxford3000/blob/main/oxford3000.py"
click node_downloader "https://github.com/karslioglu/oxford3000/blob/main/scripts/download_pdf.py"
click node_parser "https://github.com/karslioglu/oxford3000/blob/main/scripts/pdf_parser.py"
click node_sqlite_export "https://github.com/karslioglu/oxford3000/blob/main/scripts/export_sqlite.py"
click node_database "https://github.com/karslioglu/oxford3000/blob/main/scripts/export_sqlite.py"
click node_translator "https://github.com/karslioglu/oxford3000/blob/main/scripts/translate.py"
click node_examples "https://github.com/karslioglu/oxford3000/blob/main/scripts/examples.py"
click node_reader "https://github.com/karslioglu/oxford3000/blob/main/scripts/db_reader.py"
click node_csv_export "https://github.com/karslioglu/oxford3000/blob/main/scripts/export_csv.py"
click node_xlsx_export "https://github.com/karslioglu/oxford3000/blob/main/scripts/export_xlsx.py"
click node_sounds "https://github.com/karslioglu/oxford3000/blob/main/scripts/sounds.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_cli,node_downloader,node_parser,node_sqlite_export,node_operator toneBlue
class node_translator,node_examples toneAmber
class node_csv_export,node_xlsx_export,node_sounds,node_gemini toneMint
class node_database,node_reader toneRose
class node_oxford,node_sound_service toneIndigo
```

## Components

### PDF ingestion

- [Command router](https://github.com/karslioglu/oxford3000/blob/main/oxford3000.py): `oxford3000.py`
- [PDF downloader](https://github.com/karslioglu/oxford3000/blob/main/scripts/download_pdf.py): `scripts/download_pdf.py`
- [PDF parser](https://github.com/karslioglu/oxford3000/blob/main/scripts/pdf_parser.py): `scripts/pdf_parser.py`
- [SQLite importer](https://github.com/karslioglu/oxford3000/blob/main/scripts/export_sqlite.py): `scripts/export_sqlite.py`

### Database enrichment

- [Turkish translation](https://github.com/karslioglu/oxford3000/blob/main/scripts/translate.py): `scripts/translate.py`
- [Example sentences](https://github.com/karslioglu/oxford3000/blob/main/scripts/examples.py): `scripts/examples.py`

### Exports and audio

- [CSV export](https://github.com/karslioglu/oxford3000/blob/main/scripts/export_csv.py): `scripts/export_csv.py`
- [Excel export](https://github.com/karslioglu/oxford3000/blob/main/scripts/export_xlsx.py): `scripts/export_xlsx.py`
- [Pronunciation downloader](https://github.com/karslioglu/oxford3000/blob/main/scripts/sounds.py): `scripts/sounds.py`

### Shared storage

- [Oxford database](https://github.com/karslioglu/oxford3000/blob/main/scripts/export_sqlite.py): `scripts/export_sqlite.py`
- [Word reader](https://github.com/karslioglu/oxford3000/blob/main/scripts/db_reader.py): `scripts/db_reader.py`

### Other components

- **CLI user**
- **Oxford PDF source**
- **Gemini API**
- **Sound of Text**

## Connections

- CLI user → Command router: runs commands (evidence: `README.md`)
- Command router → PDF downloader: dispatches download (evidence: `oxford3000.py`)
- Oxford PDF source → PDF downloader: serves PDF (evidence: `scripts/download_pdf.py`)
- Command router → SQLite importer: dispatches import (evidence: `oxford3000.py`)
- SQLite importer → PDF parser: calls parse_pdf (evidence: `scripts/export_sqlite.py`)
- SQLite importer → Oxford database: writes records (evidence: `scripts/export_sqlite.py`)
- Command router → Turkish translation: dispatches translate (evidence: `oxford3000.py`)
- Turkish translation → Gemini API: requests translations (evidence: `scripts/translate.py`)
- Turkish translation → Oxford database: updates translations (evidence: `scripts/translate.py`)
- Command router → Example sentences: dispatches examples (evidence: `oxford3000.py`)
- Example sentences → Gemini API: requests sentences (evidence: `scripts/examples.py`)
- Example sentences → Oxford database: writes examples (evidence: `scripts/examples.py`)
- Command router → CSV export: dispatches CSV (evidence: `oxford3000.py`)
- Command router → Excel export: dispatches Excel (evidence: `oxford3000.py`)
- Command router → Pronunciation downloader: dispatches audio (evidence: `oxford3000.py`)
- CSV export → Word reader: fetches words (evidence: `scripts/export_csv.py`)
- Excel export → Word reader: fetches words (evidence: `scripts/export_xlsx.py`)
- Pronunciation downloader → Word reader: fetches words (evidence: `scripts/sounds.py`)
- Word reader → Oxford database: reads words (evidence: `scripts/db_reader.py`)
- Pronunciation downloader → Sound of Text: requests audio (evidence: `scripts/sounds.py`)
