How jhleekr/semantle-koo works
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