# marwanair/tinypy-generator architecture

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

- Interactive diagram: https://gitdiagram.com/marwanair/tinypy-generator
- Repository: https://github.com/marwanair/tinypy-generator

## Overview

##### Project type and purpose
- This is an open-source code-generation tool (TinyPy Generator) written in Python.
- Purpose: automatically generate Python programs at varying levels of complexity (arithmetic, conditionals, loops) via a context-free grammar (CFG).

##### File structure
- Top-level files:
- code_generator.py – main Python script (CLI entry point and generator engine)
- requirements.txt – Python dependencies
- README.md – usage and project description
- example.ipynb – interactive demonstration
- data/ directory: contains sample/generated program outputs (data_1.1.txt, data_1.2.txt, …, data_all.txt)
- No separate front-end/backend: single CLI tool with optional notebook interface.

##### README for additional insights
- Uses command-line arguments: num_programs, level, filename, deduplicate
- Describes generator levels (1.1 → 3.2, plus ALL) mapping to CFG rules
- Encourages modification and extension

a. Main components
1. Command-Line Interface (CLI)
2. Argument Parser (e.g., argparse)
3. Generator Engine
- CFG Rule Loader (internal module or code block within code_generator.py)
- Program Synthesizer (applies grammar rules to build AST/code strings)
4. Deduplication Module (optional step)
5. File I/O
- Input: data/ (optional seed or sample data)
- Output: target file (e.g., data/data.txt or user-specified filename)
6. Example/Notebook Interface (example.ipynb)
b. Relationships and interactions
- User → CLI → Argument Parser → Generator Engine → (Deduplication) → File Writer
- Generator Engine → may read/write data/ folder for intermediate or sample data
- Notebook → imports code_generator functions to demonstrate usage
c. Architectural patterns/design principles
- Single responsibility per module: parsing, generation, deduplication, I/O
- Pipeline flow: linear stages with clearly defined inputs/outputs
- Extensibility point: adding new grammar levels or custom rules
d. Relevant technologies/frameworks/libraries
- Python 3.x
- argparse or click (for CLI)
- Standard library (os, sys, random)
- Jupyter Notebook (for example.ipynb demonstration)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing components
    User(("User")):::frontend
    CLI["CLI (code_generator.py)"]:::frontend
    Notebook["Example Notebook\n(example.ipynb)"]:::frontend

    %% Core logic components
    ArgParser["Argument Parser\n(argparse)"]:::core
    subgraph "Generator Engine"
        direction TB
        Engine["Generator Engine"]:::core
        CFGLoader["CFG Rule Loader"]:::core
        Synthesizer["Program Synthesizer"]:::core
    end
    DedupDecision{"Deduplicate?"}:::decision
    Deduplicator["Deduplication Module"]:::core
    FileWriter["File Writer\n(I/O)"]:::core

    %% Storage components
    DataFolder[(data/)]:::storage
    OutputFile[(Output File)]:::storage

    %% Relationships
    User -->|uses| CLI
    CLI -->|parses args| ArgParser
    ArgParser -->|configures| Engine
    Engine -->|loads rules| CFGLoader
    Engine -->|synthesizes code| Synthesizer
    Synthesizer --> DedupDecision
    DedupDecision --Yes--> Deduplicator
    DedupDecision --No--> FileWriter
    Deduplicator -->|filtered code| FileWriter
    Engine -->|reads/writes samples| DataFolder
    FileWriter -->|writes programs| OutputFile
    Notebook -->|imports functions| Engine

    %% Click Events
    click CLI "https://github.com/marwanair/tinypy-generator/blob/main/code_generator.py"
    click ArgParser "https://github.com/marwanair/tinypy-generator/blob/main/code_generator.py"
    click Engine "https://github.com/marwanair/tinypy-generator/blob/main/code_generator.py"
    click CFGLoader "https://github.com/marwanair/tinypy-generator/blob/main/code_generator.py"
    click Synthesizer "https://github.com/marwanair/tinypy-generator/blob/main/code_generator.py"
    click Deduplicator "https://github.com/marwanair/tinypy-generator/blob/main/code_generator.py"
    click FileWriter "https://github.com/marwanair/tinypy-generator/blob/main/code_generator.py"
    click DataFolder "https://github.com/marwanair/tinypy-generator/tree/main/data/"
    click Notebook "https://github.com/marwanair/tinypy-generator/blob/main/example.ipynb"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFD580,stroke:#333,stroke-width:1px
    classDef decision fill:#FFFACD,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
