Skip to content

About

Automated Learning Progress Tracking & Dual-Store (JSON to RDB) Zero-Downtime Architecture Showcase

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ“Š Learning Tracker API & Showcase

μ‹€μ‹œκ°„ ν•™μŠ΅ 뢄석, 닀쀑 계정 식별 및 λ“€μ–Ό μŠ€ν† μ–΄(Dual-Store) 무쀑단 λ§ˆμ΄κ·Έλ ˆμ΄μ…˜μ„ κ΅¬ν˜„ν•œ μ’…ν•© ꡐ윑 운영 ν”Œλž«νΌ

Python Version Framework ORM Database Architecture License


πŸ’‘ Project Overview (ν”„λ‘œμ νŠΈ μ†Œκ°œ)

Learning TrackerλŠ” μˆ˜κ°•μƒ 1,000+ λͺ… 규λͺ¨μ˜ μ½”λ”© ꡐ윑 ν™˜κ²½μ—μ„œ λ°œμƒν•˜λŠ” ν•™μŠ΅ 진도 좔적 μ§€μ—°, λΉ„κ΅¬μ‘°ν™”λœ 닀쀑 계정 νŒŒνŽΈν™”, λΉ„νš¨μœ¨μ μΈ μˆ˜λ™ 과제 ν”Όλ“œλ°± 업무λ₯Ό μžλ™ν™”ν•˜κ³  κ³ λ„ν™”ν•˜κΈ° μœ„ν•΄ μ„€κ³„Β·κ΅¬μΆ•λœ λ°±μ—”λ“œ μ€‘μ‹¬μ˜ μ›Ή ν”Œλž«νΌμž…λ‹ˆλ‹€.

κΈ°μ‘΄ 파일 μ‹œμŠ€ν…œ(JSON) 기반의 λΉ λ₯Έ ν”„λ‘œν† νƒ€μ΄ν•‘μ—μ„œ μΆœλ°œν•˜μ—¬, μ‹œμŠ€ν…œ ν™•μž₯κ³Ό λ™μ‹œμ„± 문제 해결을 μœ„ν•΄ **RDB(Relational Database)둜의 무쀑단 점진적 λ§ˆμ΄κ·Έλ ˆμ΄μ…˜(Dual-Store νŒ¨ν„΄ 및 ETL νŒŒμ΄ν”„λΌμΈ)**을 μ„±κ³΅μ μœΌλ‘œ μ™„μˆ˜ν•œ μ•„ν‚€ν…μ²˜μ  κ³ λ―Όκ³Ό κ΅¬ν˜„ 결과물을 λ‹΄κ³  μžˆμŠ΅λ‹ˆλ‹€.

πŸ”’ κ°œμΈμ •λ³΄ 보호 μ•ˆλ‚΄: λ³Έ 곡개 μ €μž₯μ†ŒλŠ” μ‹€μ œ 학생 κ°œμΈμ •λ³΄(PII)와 μ™ΈλΆ€ 인증 정보λ₯Ό 일체 ν¬ν•¨ν•˜μ§€ μ•ŠμœΌλ©°, μ‹œμŠ€ν…œμ˜ λͺ¨λ“  κΈ°λŠ₯κ³Ό UI/APIλ₯Ό 둜컬 ν™˜κ²½μ—μ„œ μ¦‰μ‹œ 검증할 수 μžˆλŠ” **μ •κ΅ν•œ λͺ¨μ˜ 데이터셋(Mock Dataset)**으둜 κ΅¬μ„±λ˜μ–΄ μžˆμŠ΅λ‹ˆλ‹€.


πŸ›οΈ System Architecture (μ‹œμŠ€ν…œ μ•„ν‚€ν…μ²˜)

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                        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) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸš€ Key Engineering Highlights (핡심 μ—”μ§€λ‹ˆμ–΄λ§ μ„±κ³Ό)

1. Dual-Store Architecture & 무쀑단 점진적 λ§ˆμ΄κ·Έλ ˆμ΄μ…˜

  • 문제 상황: 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 λ¬Έμ„œλ₯Ό μ°Έκ³ ν•˜μ„Έμš”.

2. 닀쀑 계정 식별 및 νœ΄λ¦¬μŠ€ν‹± λ§€μΉ­ μ—”μ§„

  • 학생듀이 학원 λ‚΄μ—μ„œ μ‚¬μš©ν•˜λŠ” λ‹€μ–‘ν•œ μ„œλΈŒ 계정(예: κΉ€μ½”λ”©0101, 0101κΉ€μ½”λ”©, κΉ€μ½”λ”©_sub)을 단일 internal_user_id (UUID)둜 μžλ™ 톡합.
  • μ •κ·œν‘œν˜„μ‹ 기반 계정 μ—­μˆœ/λ³€ν˜• 탐지 및 κ°€μ€‘μΉ˜ λ§€μΉ­ μ•Œκ³ λ¦¬μ¦˜ κ΅¬ν˜„ (_normalize_accounts).

3. Timezone-Safe ν•™μŠ΅ μž”λ””(Streak) & ν™œλ™ 집계 μ—”μ§„

  • λΆ„μ‚°λœ 제좜 이λ ₯의 νƒ€μž„μŠ€νƒ¬ν”„λ₯Ό UTC둜 μ •κ·œν™”(TIMESTAMPTZ) μ €μž₯ν•˜κ³ , μ‚¬μš©μž μ‹œκ°ν™” μ‹œ μ„œμšΈ ν‘œμ€€μ‹œ(KST, UTC+9)둜 λ³€ν™˜.
  • 졜근 90μΌκ°„μ˜ 연속 ν•™μŠ΅ νŒ¨ν„΄, μ£Όλ ₯ μ–Έμ–΄ κ°€μ€‘μΉ˜ νŒλ³„, 문제 풀이 μ •λ‹΅λ₯  톡계λ₯Ό μΊμ‹œ μΉœν™”μ μœΌλ‘œ 고속 계산.

4. 과제 λ°”μŠ€μΌ“ 및 1-Click ν”Όλ“œλ°± ν…œν”Œλ¦Ώ μ—”μ§„

  • 문제 μΉ΄νƒˆλ‘œκ·Έμ—μ„œ λ“œλž˜κ·Έ & 클릭으둜 μˆ™μ œ 문제λ₯Ό μž₯λ°”κ΅¬λ‹ˆμ— λ‹΄κ³ , 학생별 ν•™μŠ΅ νƒœλ„μ™€ 디버깅 μ‹œν–‰μ°©μ˜€λ₯Ό λΆ„μ„ν•˜μ—¬ ν•™λΆ€λͺ¨ μ•Œλ¦Όν†‘/문자용 ν”Όλ“œλ°± λ©”μ‹œμ§€λ₯Ό μžλ™ μ‘°ν•© 생성.

⚑ 1-Minute Quick Start (둜컬 μ‹€ν–‰ κ°€μ΄λ“œ)

λ³„λ„μ˜ μ™ΈλΆ€ 인프라 μ„€μ •μ΄λ‚˜ μ™ΈλΆ€ μ‚¬μ΄νŠΈ 계정 없이, λ‚΄μž₯된 Mock 데이터셋과 SQLiteλ₯Ό 기반으둜 1λΆ„ μ•ˆμ— μ¦‰μ‹œ ꡬ동할 수 μžˆμŠ΅λ‹ˆλ‹€.

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/activate

2. μ˜μ‘΄μ„± νŒ¨ν‚€μ§€ μ„€μΉ˜

pip install -r requirements.txt

3. ν™˜κ²½ λ³€μˆ˜ μ„€μ •

# κΈ°λ³Έ μ œκ³΅λ˜λŠ” 예제 섀정을 λ³΅μ‚¬ν•©λ‹ˆλ‹€ (둜컬 데λͺ¨ λͺ¨λ“œ ν™œμ„±ν™”)
cp .env.example .env

4. 둜컬 μ„œλ²„ μ‹€ν–‰

python src/app.py

λΈŒλΌμš°μ €μ—μ„œ http://localhost:5000 λ˜λŠ” **http://localhost:5000/schedule**으둜 μ ‘μ†ν•˜λ©΄ 가상 학생듀(κΉ€μ½”λ”©, λ°•νŒŒμ΄μ¬, μ΄μ•Œκ³ )의 μ‹€μ‹œκ°„ λŒ€μ‹œλ³΄λ“œλ₯Ό λ°”λ‘œ νƒμƒ‰ν•˜μ‹€ 수 μžˆμŠ΅λ‹ˆλ‹€.


πŸ“‚ Project Structure (디렉토리 ꡬ쑰)

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                     # μ˜μ‘΄μ„± 라이브러리 λͺ©λ‘

πŸ› οΈ Tech Stack (기술 μŠ€νƒ)

λΆ„λ₯˜ 기술 μŠ€νƒ
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

πŸ‘¨β€πŸ’» Author

About

Automated Learning Progress Tracking & Dual-Store (JSON to RDB) Zero-Downtime Architecture Showcase

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages