# neonc0wboy/rap architecture

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

- Interactive diagram: https://gitdiagram.com/neonc0wboy/rap
- Repository: https://github.com/neonc0wboy/rap

## Overview

##### Project Type and Purpose
- This is an open-source text-generation tool for creating Russian rap lyrics.
- It uses a GPU-backed inference service (hosted via a Jupyter notebook in GPU.ipynb) and various seed-phrase files to drive prompt generation.
- It also includes translation utilities (shell/PHP) and a lightweight web/CLI interface (HTML, JS, Python).

##### File-Structure Analysis
- Top-level scripts and folders:
- GPU.ipynb / GPU.txt – Jupyter notebook for spinning up the inference service on Colab.
- TextGen.py – Python CLI client that reads seed data, constructs prompts, and calls the inference API.
- api/ and api1/ – folders that may contain HTTP handler code or auxiliary API logic.
- php/ & php.php – a PHP-based translator microservice used by translate.sh.
- index.html / index.js – a simple static web UI that can invoke TextGen.py or the inference API directly.
- seed-related files: seeds.b39, RapSeedBIP39, wordlist.txt, wrus.txt, cipherseeds/, seeds/ – data stores for seed phrases and word lists.
- scr.sh / script.sh / translate.sh – shell wrappers that orchestrate translation calls, prompt formatting, and launching TextGen.py.
- package.json – contains Node.js dependencies, likely for the index.js UI or auxiliary scripts.

##### README Insights
- Instructs running GPU.ipynb first, copying the provided host URL into TextGen.py.
- Demonstrates CLI usage of “api” command and translate.sh to generate and translate rap lyrics.
- Relies on GPT-3.5-turbo (or similar) via an HTTP endpoint exposed by the notebook.

##### Main Components
A. Inference Service (GPU)
- A Jupyter Notebook (GPU.ipynb) deployed on Colab.
- Exposes an HTTP endpoint for text generation (host URL).
B. Client Layer
- TextGen.py: reads seed files → formats a JSON payload → sends HTTP request → receives generated lyrics.
- translate.sh + php/php.php: takes generated text → sends to PHP translator → returns Russian translation.
- Optional Web UI (index.html + index.js): static page that calls TextGen.py or directly hits the inference endpoint (using package.json’s Node.js server if present).
C. Data Store
- Local seed files: seeds.b39, RapSeedBIP39, wordlist.txt, wrus.txt, cipherseeds/, etc.
- Used by TextGen.py to craft prompts and by translation scripts as input.
D. Orchestration Scripts
- scr.sh / script.sh: automate the sequence (start notebook, inject host, run TextGen.py, run translation).

##### Relationships and Data Flows
- The orchestration script launches the GPU notebook or connects to it.
- TextGen.py reads seed files → constructs prompt → HTTP POST to GPU endpoint → receives lyrics.
- translate.sh calls php/php.php with the generated text → returns translated output.
- The Web UI (if used) issues the same HTTP requests to either TextGen.py or directly to the GPU endpoint.
- All components may log to script.log or nohup.out for debugging/tracing.

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- Inference service (model hosting) is decoupled from the prompt-generation client.
- Translation logic is isolated in a small PHP microservice.
- Seed data is externalized in flat files for easy swapping/extensibility.
- Microservice-like boundaries: each major function (inference, translation, web UI) lives in its own folder.
- Shell orchestration for reproducible workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Seed Data Store"
        SB39["seeds.b39"]:::data
        RAP["RapSeedBIP39"]:::data
        WL["wordlist.txt"]:::data
        WRUS["wrus.txt"]:::data
        CIPHER[(cipherseeds/)]:::data
        SEEDSDIR[(seeds/)]:::data
    end

    subgraph "Orchestration Scripts"
        SCR["scr.sh"]:::orch
        SCRIPT["script.sh"]:::orch
    end

    subgraph "Client Layer"
        TG["TextGen.py"]:::client
        TRANS_SH["translate.sh"]:::client
        PHPMICRO["php/php.php"]:::client
    end

    subgraph "Web UI"
        INDEX_HTML["index.html"]:::client
        INDEX_JS["index.js"]:::client
        PKG["package.json"]:::client
    end

    subgraph "Inference Service"
        GPU_NB["GPU.ipynb"]:::inference
        GPU_TXT["GPU.txt"]:::inference
    end

    SB39 -->|"Read seeds"| TG
    RAP -->|"Read seeds"| TG
    WL -->|"Read seeds"| TG
    WRUS -->|"Read seeds"| TG
    CIPHER -->|"Read seeds"| TG
    SEEDSDIR -->|"Read seeds"| TG

    SCR -->|"Launch notebook"| GPU_NB
    SCRIPT -->|"Orchestrate workflow"| TG
    SCRIPT -->|"Orchestrate workflow"| TRANS_SH

    TG -->|"HTTP POST prompt"| GPU_NB
    GPU_NB -->|"Generated lyrics"| TG

    TG -->|"Output lyrics"| TRANS_SH
    TRANS_SH -->|"Translate request"| PHPMICRO
    PHPMICRO -->|"Translated text"| TRANS_SH

    INDEX_HTML -->|"Browser request"| TG
    INDEX_HTML -->|"Direct to API"| GPU_NB
    INDEX_JS -->|"Browser logic"| TG

    classDef inference fill:#ADD8E6,stroke:#000;
    classDef client fill:#90EE90,stroke:#000;
    classDef data fill:#FFFF66,stroke:#000,stroke-width:1px;
    classDef orch fill:#FFA500,stroke:#000;

    click GPU_NB "https://github.com/neonc0wboy/rap/blob/123/GPU.ipynb"
    click GPU_TXT "https://github.com/neonc0wboy/rap/blob/123/GPU.txt"
    click TG "https://github.com/neonc0wboy/rap/blob/123/TextGen.py"
    click PHPMICRO "https://github.com/neonc0wboy/rap/blob/123/php/php.php"
    click TRANS_SH "https://github.com/neonc0wboy/rap/blob/123/translate.sh"
    click INDEX_HTML "https://github.com/neonc0wboy/rap/blob/123/index.html"
    click INDEX_JS "https://github.com/neonc0wboy/rap/blob/123/index.js"
    click PKG "https://github.com/neonc0wboy/rap/blob/123/package.json"
    click SB39 "https://github.com/neonc0wboy/rap/blob/123/seeds.b39"
    click RAP "https://github.com/neonc0wboy/rap/tree/123/RapSeedBIP39"
    click WL "https://github.com/neonc0wboy/rap/blob/123/wordlist.txt"
    click WRUS "https://github.com/neonc0wboy/rap/blob/123/wrus.txt"
    click CIPHER "https://github.com/neonc0wboy/rap/tree/123/cipherseeds/"
    click SEEDSDIR "https://github.com/neonc0wboy/rap/tree/123/seeds/"
    click SCR "https://github.com/neonc0wboy/rap/blob/123/scr.sh"
    click SCRIPT "https://github.com/neonc0wboy/rap/blob/123/script.sh"
```
