μ€μκ° νμ΅ λΆμ, λ€μ€ κ³μ μλ³ λ° λμΌ μ€ν μ΄(Dual-Store) 무μ€λ¨ λ§μ΄κ·Έλ μ΄μ μ ꡬνν μ’ ν© κ΅μ‘ μ΄μ νλ«νΌ
Learning Trackerλ μκ°μ 1,000+ λͺ κ·λͺ¨μ μ½λ© κ΅μ‘ νκ²½μμ λ°μνλ νμ΅ μ§λ μΆμ μ§μ°, λΉκ΅¬μ‘°νλ λ€μ€ κ³μ ννΈν, λΉν¨μ¨μ μΈ μλ κ³Όμ νΌλλ°± μ 무λ₯Ό μλννκ³ κ³ λννκΈ° μν΄ μ€κ³Β·κ΅¬μΆλ λ°±μλ μ€μ¬μ μΉ νλ«νΌμ λλ€.
κΈ°μ‘΄ νμΌ μμ€ν (JSON) κΈ°λ°μ λΉ λ₯Έ νλ‘ν νμ΄νμμ μΆλ°νμ¬, μμ€ν νμ₯κ³Ό λμμ± λ¬Έμ ν΄κ²°μ μν΄ **RDB(Relational Database)λ‘μ 무μ€λ¨ μ μ§μ λ§μ΄κ·Έλ μ΄μ (Dual-Store ν¨ν΄ λ° ETL νμ΄νλΌμΈ)**μ μ±κ³΅μ μΌλ‘ μμν μν€ν μ²μ κ³ λ―Όκ³Ό ꡬν κ²°κ³Όλ¬Όμ λ΄κ³ μμ΅λλ€.
π κ°μΈμ 보 λ³΄νΈ μλ΄: λ³Έ κ³΅κ° μ μ₯μλ μ€μ νμ κ°μΈμ 보(PII)μ μΈλΆ μΈμ¦ μ 보λ₯Ό μΌμ²΄ ν¬ν¨νμ§ μμΌλ©°, μμ€ν μ λͺ¨λ κΈ°λ₯κ³Ό UI/APIλ₯Ό λ‘컬 νκ²½μμ μ¦μ κ²μ¦ν μ μλ **μ κ΅ν λͺ¨μ λ°μ΄ν°μ (Mock Dataset)**μΌλ‘ ꡬμ±λμ΄ μμ΅λλ€.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Client Layer (Vanilla JS SPA) β
β [νμ΅ λμ보λ] [μ£Όκ° μκ°ν / μΆκ²°] [κ³Όμ λ°μ€μΌ] [μλ μ€νΈλ¦] β
βββββββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ
β HTTP / JSON API
βββββββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββ
β Flask 3.1 Application Layer β
β βββ Blueprints: auth / schedule / students / workspace β
β βββ Services: ProblemCatalog / WorkspaceStudent / Crawler β
βββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββ
β β
βΌ βΌ
ββββββββββββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββ
β Dual-Store Data Layer (Repository) β β Background Sync Workers β
β βββ Read: RDB First β JSON Fallback β β βββ Periodic Sync Task β
β βββ Write: Atomic RDB + Snapshot Sync β β βββ Rate-limited Crawler β
βββββββββ¬βββββββββββββββββββββββββ¬ββββββββ βββββββββββββββ¬ββββββββββββββ
β β β
βΌ βΌ βΌ
ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββββββ
β SQLAlchemy β β File System β β External LMS API β
β (SQLite/PG) β β (JSON Cache) β β (Async Session Auth) β
ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββββββ
-
λ¬Έμ μν©: 14,000+ λΌμΈμ λΉκ΅¬μ‘°ν JSON νμΌ I/Oλ‘ μΈν
$O(N)$ λ³λͺ©, νμΌ Lock κ²½ν© λ° νΈλμμ λΆμ¬. -
ν΄κ²° λ°©μ: κΈ°μ‘΄ λ κ±°μ μ½λμ μ΄μμ μ μ§νλ©΄μ RDBλ‘ μ μ§μ μ ννλ Dual-Store Repository ν¨ν΄ μ€κ³ (
src/db/dual_store.py).-
USE_RDB_STOREνλκ·Έλ‘ λ°νμ μ μ΄: RDB μ°μ μ‘°ν λ° μ€ν¨ μ JSON μμ ν΄λ°±. - μ€νλΌμΈ ETL μ€ν¬λ¦½νΈ(
src/scripts/etl_json_to_rdb.py)μ μ ν©μ± μ μ κ²μ¦ μ€ν¬λ¦½νΈ(src/scripts/verify_etl.py)λ₯Ό κ°λ°νμ¬ λ°μ΄ν° μ μ€ 0.00% λ¬μ±. - π μμΈν μ€κ³ κ³Όμ μ RFC-001: Dual-Store Migration λ¬Έμλ₯Ό μ°Έκ³ νμΈμ.
-
- νμλ€μ΄ νμ λ΄μμ μ¬μ©νλ λ€μν μλΈ κ³μ (μ:
κΉμ½λ©0101,0101κΉμ½λ©,κΉμ½λ©_sub)μ λ¨μΌinternal_user_id (UUID)λ‘ μλ ν΅ν©. - μ κ·ννμ κΈ°λ° κ³μ μμ/λ³ν νμ§ λ° κ°μ€μΉ λ§€μΉ μκ³ λ¦¬μ¦ κ΅¬ν (
_normalize_accounts).
- λΆμ°λ μ μΆ μ΄λ ₯μ νμμ€ν¬νλ₯Ό UTCλ‘ μ κ·ν(
TIMESTAMPTZ) μ μ₯νκ³ , μ¬μ©μ μκ°ν μ μμΈ νμ€μ(KST, UTC+9)λ‘ λ³ν. - μ΅κ·Ό 90μΌκ°μ μ°μ νμ΅ ν¨ν΄, μ£Όλ ₯ μΈμ΄ κ°μ€μΉ νλ³, λ¬Έμ νμ΄ μ λ΅λ₯ ν΅κ³λ₯Ό μΊμ μΉνμ μΌλ‘ κ³ μ κ³μ°.
- λ¬Έμ μΉ΄νλ‘κ·Έμμ λλκ·Έ & ν΄λ¦μΌλ‘ μμ λ¬Έμ λ₯Ό μ₯λ°κ΅¬λμ λ΄κ³ , νμλ³ νμ΅ νλμ λλ²κΉ μνμ°©μ€λ₯Ό λΆμνμ¬ νλΆλͺ¨ μλ¦Όν‘/λ¬Έμμ© νΌλλ°± λ©μμ§λ₯Ό μλ μ‘°ν© μμ±.
λ³λμ μΈλΆ μΈνλΌ μ€μ μ΄λ μΈλΆ μ¬μ΄νΈ κ³μ μμ΄, λ΄μ₯λ Mock λ°μ΄ν°μ κ³Ό SQLiteλ₯Ό κΈ°λ°μΌλ‘ 1λΆ μμ μ¦μ ꡬλν μ μμ΅λλ€.
git clone https://github.com/sleepyhood/learning-tracker-showcase.git
cd learning-tracker-showcase
python -m venv venv
# Windows:
.\venv\Scripts\activate
# macOS/Linux:
source venv/bin/activatepip install -r requirements.txt# κΈ°λ³Έ μ 곡λλ μμ μ€μ μ 볡μ¬ν©λλ€ (λ‘컬 λ°λͺ¨ λͺ¨λ νμ±ν)
cp .env.example .envpython src/app.pyλΈλΌμ°μ μμ http://localhost:5000 λλ **http://localhost:5000/schedule**μΌλ‘ μ μνλ©΄ κ°μ νμλ€(κΉμ½λ©, λ°νμ΄μ¬, μ΄μκ³ )μ μ€μκ° λμ보λλ₯Ό λ°λ‘ νμνμ€ μ μμ΅λλ€.
learning-tracker-showcase/
βββ docs/ # κΈ°μ λ¬Έμ λ° μν€ν
μ² λ€μ΄μ΄κ·Έλ¨
β βββ rfc_dual_store_migration.md # Dual-Store λ§μ΄κ·Έλ μ΄μ
RFC λ¬Έμ
β βββ chapter_workspace_contract.md # API λ°μ΄ν° κ³μ½ λͺ
μΈμ
β βββ hybrid_cloud_architecture.drawio # μΈνλΌ λ° ν΄λΌμ°λ λ€μ΄μ΄κ·Έλ¨
βββ meta/ # μμ€ν
μ€μ λ° Mock λ°μ΄ν°μ
β βββ workspace_students.json # κ°μ νμ νλ‘ν λ° μκ° μ 보
β βββ schedule.json # μμΌλ³ μμ
μ¬λ‘― λ°°μΉλ
β βββ uuids.json # κ³μ μλ³μ - UUID λ§€ν
β βββ portal_mapping.json # λͺ¨μ μΈλΆ ν¬νΈ λ§€ν
βββ src/ # μ ν리μΌμ΄μ
μμ€μ½λ
β βββ app.py # Flask μνΈλ¦¬ν¬μΈνΈ λ° λ―Έλ€μ¨μ΄
β βββ config.py # νκ²½λ³μ λ° μμ€ν
μ μ μ€μ
β βββ core/ # ν΅μ¬ I/O μ€ν λ¦¬μ§ μμ§
β βββ db/ # SQLAlchemy ORM λͺ¨λΈ, Base, DualStore
β β βββ models.py # User, ExternalAccount, Submission λ±
β β βββ dual_store.py # RDB / JSON μ΄μ€ν μ μ₯μ μΆμν
β β βββ repo.py # DB 쿼리 λ ν¬μ§ν 리 κ³μΈ΅
β βββ routes/ # Flask Blueprints (API / Web Routes)
β β βββ schedule.py # λ©μΈ λμ보λ & μ£Όκ° μκ°ν λΌμ°νΈ
β β βββ students.py # νμ μμΈ, μλ(Streak), κ³Όμ API
β β βββ workspace/ # μΉ΄νλ‘κ·Έ, ν¬λ‘€λ¬, νΌλλ°± λͺ¨λ
β βββ services/ # μμ λλ©μΈ λΉμ¦λμ€ λ‘μ§ κ³μΈ΅
β βββ static/ # UI μ€νμΌμνΈ(CSS) λ° λͺ¨λν JS
β βββ templates/ # Jinja2 HTML ν
νλ¦Ώ μ»΄ν¬λνΈ
β βββ utils/ # μ νΈλ¦¬ν° (ν¬λ‘€λ¬, μ€νΈλ¦ κ³μ°, μμ½κΈ°)
β βββ workers/ # λ°±κ·ΈλΌμ΄λ λκΈ°ν μ€μΌμ€λ¬ μ컀
βββ .env.example # νκ²½λ³μ ν
νλ¦Ώ
βββ .gitignore # Git μΆμ μ μΈ μ€μ
βββ requirements.txt # μμ‘΄μ± λΌμ΄λΈλ¬λ¦¬ λͺ©λ‘
| λΆλ₯ | κΈ°μ μ€ν |
|---|---|
| Backend | Python 3.10+, Flask 3.1, Jinja2 |
| Database & ORM | SQLAlchemy 2.0, SQLite (Local Demo) / PostgreSQL (Production) |
| Frontend | Vanilla JavaScript (ES6+), HTML5, CSS3 Custom Properties, Chart.js |
| Data & Pipeline | Python Requests, BeautifulSoup4, Playwright (Async Crawler) |
| Architecture | Dual-Store Pattern, Heuristic Identity Resolution, Zero-Downtime ETL |
- μ€μΉμ (Seungwon Oh)
- GitHub: @sleepyhood
- Email: smartosw@korea.ac.kr