# 9th-floor-developers/translatable-python architecture

> Architecture diagram of the GitHub repository 9th-floor-developers/translatable-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/9th-floor-developers/translatable-python
- Repository: https://github.com/9th-floor-developers/translatable-python

## Overview

##### What this project is (type + purpose)
This is a **single-file CLI “compiler/transpiler”** for a small language variant called **Translatable Python (`.tpy`)**. It:
- **Reads** a `.tpy` source file and a **dictionary CSV** (`PythonKeyword,TranslatedKeyword`)
- **Translates** the custom keywords back into valid Python syntax
- **Executes** the resulting Python code (so it’s a transpile-and-run pipeline, not a standalone bytecode compiler)

The “system” is therefore best diagrammed as a **language toolchain** (front-end + translation + runtime execution) rather than a web service architecture.

##### How the file tree maps to architecture
Top-level artifacts:
- **`lang.py`**: the entire compiler/transpiler + runner (core engine and CLI entrypoint).
- **`template_dict.csv`**: a base/example dictionary template for keyword mappings.
- **`examples/*`**: multiple sample “languages” (ru, th, kr, ar, hi, gen_alpha). Each contains:
- one `*.csv` dictionary file for that language
- **`images/*`**: README screenshots (documentation-only).

##### What to extract from README
Key behaviors to reflect:
- Invocation: `python lang.py script.tpy dict.csv`
- Dictionary requirements: each Python keyword maps to a **unique** translated keyword; UTF-8 support
- Python version: 3.10+ preferred (for `match/case` support)
- Output: execution prints/side-effects like normal Python

That implies **two primary external inputs** (source + dictionary), a **translation engine**, and a **Python execution runtime**.

##### CLI Invocation Layer
- Parses args: `script.tpy` path, `dict.csv` path
##### File I/O Layer
- Reads `.tpy` source (UTF-8)
- Reads CSV dictionary (UTF-8)
##### Dictionary Parser / Validator
- Parses CSV rows into a mapping
- Validates constraints implied by README:
- unique mapping
- no duplicate python keywords
- (optionally) “keyword collisions” / conflicting translations
##### Translator / Rewriter
- Applies keyword replacements to `.tpy` text to produce **Python source text**
- (If implemented) handles tokenization/safety boundaries (e.g., avoid replacing inside strings/comments) — even if it’s naive replacement today, represent it explicitly as a stage (“Text-based replacement” vs “Token-based replacement”)
##### Python Code Generation Output
- “Generated Python code” as an artifact (in-memory string; optionally can be persisted for debugging)
##### Execution Engine
- Executes generated code (likely `exec()` in-process)
- Runs under **Python 3 interpreter runtime**
##### Program Output
- stdout/stderr, exceptions, exit code

##### Architectural patterns to call out
- **Compiler pipeline pattern** (input → parse/validate → transform → output)
- **Transpilation** (source-to-source translation: `.tpy` → `.py`)
- **Interpreter embedding** (generated Python executed via host Python runtime)
- **Config-driven translation** (CSV dictionary as configuration)

##### Technologies/libraries worth labeling
- **Python 3.10+** runtime
- **CSV dictionary (UTF-8)** as configuration

Shows User, `lang.py` tool, and file artifacts (`.tpy`, `dict.csv`) + output.
Break `lang.py` into the logical components listed above (CLI, I/O, parser/validator, translator, executor).
Steps from invocation → read files → parse dict → translate → execute → output/error.

Before finalizing, open `lang.py` and confirm:
- Does it do **pure string replace**, regex, or token-based parsing?
- Does it avoid replacing inside strings/comments?
- How execution occurs:
- `exec()` in same process?
- `compile()` then `exec()`?
- writing a temp `.py` then running via `subprocess`?
- Error handling/reporting (line mapping from `.tpy` to `.py`?)

- “Syntax Normalizer (e.g., braces → indentation)” (if implemented)
- “Tokenizer” (if implemented)
- “Temp file writer + subprocess runner” (if that’s the execution strategy)

##### Don’t overthink it: decompose aggressively
- every artifact is explicit,
- and every boundary (process/filesystem/runtime) is visible.

That makes it clear what could be extended later (e.g., tokenization, better parsing, debugging outputs, multi-dict support) and matches the repo’s purpose as a lightweight transpiler tool.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Context (C4 L1-ish)
  %% =========================
  subgraph "External Environment"
    U["User / Developer"]:::external

    subgraph "Filesystem"
      TPY[".tpy source file"]:::artifact
      DC["Dictionary CSV (dict.csv)"]:::artifact
      TPL["Dictionary CSV Template (template_dict.csv)"]:::artifact

      subgraph "Examples (optional inputs)"
        EXDIR["examples/*"]:::artifact
        EXAR["examples/ar/*.tpy + ar.csv"]:::artifact
        EXRU["examples/ru/*.tpy + ru.csv"]:::artifact
        EXTH["examples/th/*.tpy + thai.csv"]:::artifact
        EXKR["examples/kr/*.tpy + kr.csv"]:::artifact
        EXHI["examples/hi/*.tpy + hi.csv"]:::artifact
        EXAL["examples/gen_alpha/*.tpy + alpha.csv"]:::artifact
      end

      DOCR["README (usage + spec)"]:::doc
      IMG["images/* (screenshots)"]:::doc
    end

    PYRT["Python 3.10+ Runtime (Interpreter)"]:::runtime
  end

  %% =========================
  %% TPY Tool Process Boundary
  %% =========================
  subgraph "TPY Tool Process (single-file tool: lang.py)"
    CORE["TPY Tool Core\n(transpile + run)"]:::process

    CLI["CLI / Arg Parser\n(parse script.tpy + dict.csv paths)"]:::process

    subgraph "File I/O Layer"
      SR["Source Reader (.tpy)\n(UTF-8)"]:::process
      DR["Dictionary Reader (CSV)\n(UTF-8)"]:::process
    end

    DPV["Dictionary Parser + Validator\n(CSV rows -> mapping; enforce uniqueness)"]:::process

    TR["Translator / Keyword Rewriter\n(.tpy text + mapping -> Python text)\n(text-based vs token-based replacement)"]:::process

    GPY[/"Generated Python Source\n(in-memory string; optional debug output)"/]:::artifact

    EXE["Execution Engine\n(exec/compile/run in-process)"]:::process

    OH["Output Handler\n(stdout/stderr, exceptions, exit code)"]:::process
  end

  %% =========================
  %% Data + Control Flow (vertical)
  %% =========================
  U -->|"invokes: python lang.py <script.tpy> <dict.csv>"| CLI
  CLI -->|"script_path"| SR
  CLI -->|"dict_path"| DR

  TPY -->|"read .tpy (UTF-8)"| SR
  DC -->|"read CSV (UTF-8)"| DR

  SR -->|"source_text"| TR
  DR -->|"csv_text"| DPV
  DPV -->|"keyword_map"| TR

  TR -->|"generated_python_source"| GPY
  GPY -->|"python_code_text"| EXE

  EXE -->|"execute under host interpreter"| PYRT
  PYRT -->|"stdout/stderr + exceptions"| OH
  OH -->|"program output"| U

  %% Optional / reference flows
  TPL -.->|"base mapping template"| DC
  DOCR -.->|"documents usage + pipeline"| U
  IMG -.->|"documentation only"| U

  EXDIR -.->|"provides sample inputs"| TPY
  EXAR -.->|"sample dict + .tpy"| DC
  EXRU -.->|"sample dict + .tpy"| DC
  EXTH -.->|"sample dict + .tpy"| DC
  EXKR -.->|"sample dict + .tpy"| DC
  EXHI -.->|"sample dict + .tpy"| DC
  EXAL -.->|"sample dict + .tpy"| DC

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click CORE "https://github.com/9th-floor-developers/translatable-python/blob/main/lang.py"
  click CLI "https://github.com/9th-floor-developers/translatable-python/blob/main/lang.py"
  click SR "https://github.com/9th-floor-developers/translatable-python/blob/main/lang.py"
  click DR "https://github.com/9th-floor-developers/translatable-python/blob/main/lang.py"
  click DPV "https://github.com/9th-floor-developers/translatable-python/blob/main/lang.py"
  click TR "https://github.com/9th-floor-developers/translatable-python/blob/main/lang.py"
  click EXE "https://github.com/9th-floor-developers/translatable-python/blob/main/lang.py"

  click TPL "https://github.com/9th-floor-developers/translatable-python/blob/main/template_dict.csv"

  click EXAR "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/ar/ar.csv"
  click EXRU "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/ru/ru.csv"
  click EXTH "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/th/thai.csv"
  click EXKR "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/kr/kr.csv"
  click EXHI "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/hi/hi.csv"
  click EXAL "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/gen_alpha/alpha.csv"

  click DOCR "https://github.com/9th-floor-developers/translatable-python/blob/main/README.md"
  click IMG "https://github.com/9th-floor-developers/translatable-python/tree/main/images/"

  click EXDIR "https://github.com/9th-floor-developers/translatable-python/tree/main/examples/"
  click EXAR "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/ar/*.tpy"
  click EXRU "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/ru/*.tpy"
  click EXTH "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/th/*.tpy"
  click EXKR "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/kr/*.tpy"
  click EXHI "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/hi/*.tpy"
  click EXAL "https://github.com/9th-floor-developers/translatable-python/blob/main/examples/gen_alpha/*.tpy"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#0b3556,stroke:#0b3556,color:#ffffff,stroke-width:1.5px
  classDef runtime fill:#3b1c5a,stroke:#3b1c5a,color:#ffffff,stroke-width:1.5px
  classDef process fill:#145a32,stroke:#145a32,color:#ffffff,stroke-width:1.5px
  classDef artifact fill:#7d6608,stroke:#7d6608,color:#ffffff,stroke-width:1.5px
  classDef doc fill:#4a4a4a,stroke:#4a4a4a,color:#ffffff,stroke-width:1.5px
```
