# jhleekr/semantle-koo architecture

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

- Interactive diagram: https://gitdiagram.com/jhleekr/semantle-koo
- Repository: https://github.com/jhleekr/semantle-koo

## Overview

##### Project type and purpose
- From the README and file‐tree, this is a full-stack web application (a fork of “Semantlich”) that lets users play a word-similarity guessing game in Korean.
- Key indicators:
- README describes a server (Gunicorn), data preprocessing (Word2Vec filter), and a web front-end
- Presence of `main.py` (Flask app), `xstatic/` folder with HTML/CSS/JS, data preprocessing scripts

##### High-level architecture overview
- Two distinct phases:
A. Offline data‐preprocessing pipeline
- filter raw Word2Vec vectors & dictionary to produce a trimmed vocabulary
- load trimmed vectors into a lightweight database (SQLite or similar)
- generate and store secret words for each game session
B. Runtime / request‐response pipeline
- Browser loads static pages + JS from `xstatic/`
- JS issues REST calls (e.g., `/near`, `/single`, `/multi`) to Flask endpoints in `main.py`
- Flask handlers use `crud.py`/`database.py` for persistence and call into `word2vec.py`/`process_similar.py` to compute similarities
- Responses (JSON) flow back to the browser, which updates the UI

##### Main components
- Client (Browser)
- HTML/CSS/JS in `xstatic/`
- UI logic in `multi.js`, `near1k.js`, `single.js`
- Web Server (Flask app)
- `main.py`: HTTP endpoints
- `crud.py` + `database.py`: persistent store interface
- Data Engine
- `word2vec.py`: loads vector model
- `process_vecs.py`, `filter_words.py`: offline preprocessing scripts
- `process_similar.py`: similarity computations at runtime
- `generate_secrets.py`: offline secret‐word generation
- Database
- Stores filtered word vectors, frequent words, secret words (`data/secrets.txt` or a .db file)
- External assets
- Raw Word2Vec `.vec` file
- Hunspell Korean dictionary
- Deployment
- Gunicorn (WSGI server)
- (Optional) Front-proxy like Nginx serving static assets / SSL

##### Relationships & data flow
Raw Word2Vec → filter_words.py → process_vecs.py → database
Hunspell dict → filter_words.py
→ generate_secrets.py → database/data/secrets.txt
Browser (xstatic HTML/JS) → HTTP request → Flask endpoints
Flask → CRUD layer → DB → word2vec/process_similar → result
Result → JSON response → Browser UI

##### Architectural patterns & design principles
- MVC-like separation:
- View: Static HTML/JS
- Controller: Flask routes in `main.py`
- Model: Database + word-vector engine
- Offline vs. online separation:
- Keep compute-heavy preprocessing offline
- Runtime only performs similarity lookups for speed
- Single-page-app style: JS drives the game UI, communicates over REST APIs

##### Final checklist
- [ ] Components: Browser, Static Assets, Flask App, Data-Pipeline, DB, External Data Sources, Deployment
- [ ] Annotations for offline vs. online phases

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Sources
    RawW2V["Raw Word2Vec .vec"]:::external
    Hunspell["Hunspell Korean Dictionary"]:::external

    %% Offline Preprocessing Pipeline
    subgraph "Offline Preprocessing" 
        direction TB
        FW["filter_words.py"]:::script
        PV["process_vecs.py"]:::script
        GS["generate_secrets.py"]:::script
    end

    %% Database / Storage
    subgraph "Database / Storage"
        direction TB
        DBNear["Filtered Vectors<br/>(data/near/)"]:::db
        DBFreq["Frequent Words List<br/>(data/frequent_words.txt)"]:::db
        DBSecrets["Secret Words Store<br/>(data/secrets.txt)"]:::db
    end

    %% Offline Flow
    RawW2V -->|"filter_words.py"| FW
    Hunspell -->|"filter_words.py"| FW
    FW -->|"process_vecs.py"| PV
    PV -->|Store Vectors| DBNear
    PV -->|Store Frequent Words| DBFreq
    PV -->|"generate_secrets.py"| GS
    GS -->|Store Secrets| DBSecrets

    %% Runtime Serving Pipeline
    subgraph "Runtime Serving"
        direction TB
        %% Client and Static Assets
        Browser["Browser"]:::component
        subgraph "Static Assets (xstatic/)" 
            direction TB
            HTMLMulti["multi.html"]:::static
            HTMLNear["near1k.html"]:::static
            HTMLSelect["select.html"]:::static
            HTMLSingle["single.html"]:::static
            CSS["pc.css"]:::static
            JSMulti["multi.js"]:::static
            JSNear["near1k.js"]:::static
            JSSingle["single.js"]:::static
        end

        %% Deployment 
        Nginx["Nginx (Optional)"]:::infra
        Gunicorn["Gunicorn WSGI"]:::infra

        %% Application Layer
        Flask["Flask App<br/>(main.py)"]:::component
        CRUD["CRUD Layer<br/>(crud.py)"]:::component
        DBConn["DB Schema<br/>(database.py)"]:::component
        Word2Vec["Word2Vec Loader<br/>(word2vec.py)"]:::component
        Similar["process_similar.py"]:::component
    end

    %% Runtime Flow
    Browser -->|"loads HTML/CSS/JS"| HTMLMulti
    Browser --> HTMLNear
    Browser --> HTMLSelect
    Browser --> HTMLSingle
    Browser --> CSS
    Browser --> JSMulti
    Browser --> JSNear
    Browser --> JSSingle

    Browser -->|Requests| Nginx
    Nginx --> Gunicorn
    Gunicorn --> Flask
    Flask -->|"POST /near<br/>POST /single<br/>POST /multi"| Flask
    Flask --> CRUD
    CRUD --> DBConn
    DBConn --> DBNear
    DBConn --> DBFreq
    CRUD --> DBSecrets
    Flask --> Word2Vec
    Flask --> Similar
    Word2Vec --> DBNear
    Similar --> DBNear
    Similar --> DBFreq
    Similar --> DBSecrets
    Flask -->|JSON Response| Browser

    %% Click Events
    click FW "https://github.com/jhleekr/semantle-koo/blob/master/filter_words.py"
    click PV "https://github.com/jhleekr/semantle-koo/blob/master/process_vecs.py"
    click GS "https://github.com/jhleekr/semantle-koo/blob/master/generate_secrets.py"
    click DBNear "https://github.com/jhleekr/semantle-koo/tree/master/data/near/"
    click DBFreq "https://github.com/jhleekr/semantle-koo/blob/master/data/frequent_words.txt"
    click DBSecrets "https://github.com/jhleekr/semantle-koo/blob/master/data/secrets.txt"
    click HTMLMulti "https://github.com/jhleekr/semantle-koo/blob/master/xstatic/multi.html"
    click HTMLNear "https://github.com/jhleekr/semantle-koo/blob/master/xstatic/near1k.html"
    click HTMLSelect "https://github.com/jhleekr/semantle-koo/blob/master/xstatic/select.html"
    click HTMLSingle "https://github.com/jhleekr/semantle-koo/blob/master/xstatic/single.html"
    click CSS "https://github.com/jhleekr/semantle-koo/blob/master/xstatic/css/pc.css"
    click JSMulti "https://github.com/jhleekr/semantle-koo/blob/master/xstatic/js/multi.js"
    click JSNear "https://github.com/jhleekr/semantle-koo/blob/master/xstatic/js/near1k.js"
    click JSSingle "https://github.com/jhleekr/semantle-koo/blob/master/xstatic/js/single.js"
    click Flask "https://github.com/jhleekr/semantle-koo/blob/master/main.py"
    click CRUD "https://github.com/jhleekr/semantle-koo/blob/master/crud.py"
    click DBConn "https://github.com/jhleekr/semantle-koo/blob/master/database.py"
    click Word2Vec "https://github.com/jhleekr/semantle-koo/blob/master/word2vec.py"
    click Similar "https://github.com/jhleekr/semantle-koo/blob/master/process_similar.py"
    click Gunicorn "https://github.com/jhleekr/semantle-koo/blob/master/requirements.txt"
    click Nginx "https://github.com/jhleekr/semantle-koo/blob/master/readme.md"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef script fill:#add8e6,stroke:#333,stroke-width:1px
    classDef db fill:#9fdf9f,stroke:#333,stroke-width:1px
    classDef static fill:#f9d57e,stroke:#333,stroke-width:1px
    classDef component fill:#79bfff,stroke:#333,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#333,stroke-width:1px
```
