Lumie 플랫폼 기술 문서
Lumie는 학원 운영을 위한 멀티테넌트 SaaS 교육 플랫폼입니다. 학생/출결/강의 관리, OMR 채점, 성적 리포트, AI 학습 분석 등 학원 운영에 필요한 기능을 제공합니다.
시스템 아키텍처
worker-1 노드는 2026-04에 제거되었습니다(MinIO 디스크는 master로 이전). 현재 클러스터는 1 master + 3 workers(worker-2, worker-3, worker-4) 구성입니다. OCI 두 계정(0213/0214)은 VCN peering으로 연결됩니다.
서비스 구성
백엔드 모듈러 모놀리스 (Spring Boot 3.4.13 / Java 21)
단일 lumie-backend.jar로 패키징, modules/{name}/ 멀티-Gradle 모듈 구조. 모듈 간 통신은 libs/internal-api Java 인터페이스로 in-process 호출. 모놀리스이므로 HTTP/gRPC 모듈 간 호출은 금지됩니다. Spring Modulith JDBC outbox 패턴으로 이벤트를 발행합니다.
| 그룹 | 모듈 | 설명 |
|---|---|---|
| 플랫폼 | tenant | 멀티테넌시 관리, 스키마 프로비저닝 |
| 플랫폼 | auth | JWT 인증, OAuth2 federated, 역할 기반 |
| 플랫폼 | billing | 구독/청구, 쿼터 |
| 플랫폼 | homepage | 학원 공개 랜딩(\{customId\}) |
| 코어 | student | 학생 등록, 일괄 가입 |
| 코어 | class | 반/수강 관리 |
| 코어 | lecture | 강의 콘텐츠 (YouTube 링크) |
| 코어 | exam | 시험, OMR, 성적 통계 |
| 코어 | attendance | 출결 세션 |
| 코어 | assignment | 과제 출제/제출 |
| 코어 | content | 공지/QnA/상담/교재 |
| 코어 | staff | 관리자/권한 |
| 코어 | ai | AI 챗봇 프록시 (chatbot-svc 연동) |
| 코어 | notification | SMS/푸시/메일 |
| 코어 | activity-log | 감사 로그 |
| 서포트 | file | MinIO 업/다운로드 |
| 서포트 | tuition | 수업료 관리 |
자세한 모듈 가이드: 백엔드 개요.
Worker 서비스 (FastAPI / Python 3.11)
lumie-worker/services/{name}/로 독립 배포되는 FastAPI 서비스. RabbitMQ consumer + HTTP callback 패턴(grading/report/analysis) 또는 HTTP 직접 호출(chatbot).
| 서비스 | 설명 |
|---|---|
| grading | OMR 시트 OpenCV 채점 (KEDA RabbitMQ 오토스케일링) |
| report | Playwright + Jinja2 성적표 PDF |
| analysis | LLM 학습 데이터 코멘터리 |
| chatbot | LangGraph + Gemini 2.5 Flash AI 챗봇 |
temp-omr-grading은 sunset 예정 레거시 동기 엔드포인트.
프론트엔드 (Next.js 16 / React 19 / TypeScript 5)
App Router + Feature-Sliced Design (FSD) 레이어. shared → entities → features → widgets → app/ 의존 방향. 로컬 머신에서 npm run dev로 실행 (localhost:3000).
| 항목 | 설명 |
|---|---|
| 아키텍처 | FSD 레이어 + 슬라이스 |
| 라우팅 | App Router, 테넌트 라우팅 |
| 상태 관리 | TanStack Query (서버) + Zustand (UI) + URL state |
기술 스택
| 레이어 | 기술 |
|---|---|
| Backend | Spring Boot 3.4.13, Java 21, Gradle, Spring Modulith (JDBC outbox), ShedLock, springdoc/OpenAPI |
| Frontend | Next.js 16.2, React 19.2, TypeScript 5, Tailwind CSS, Radix UI, TanStack Query, Zustand, Zod, orval |
| Worker | FastAPI, Python 3.11, Pydantic v2, OpenCV, Playwright, LangGraph, Gemini 2.5 Flash |
| Database | PostgreSQL (CNPG), CNPG Pooler (PgBouncer), Redis Sentinel |
| Messaging | RabbitMQ (operator 관리), KEDA (큐 기반 오토스케일링) |
| Storage | MinIO, Velero (백업) |
| Ingress | Traefik (K3s 내장), NLB 168.107.42.253 (CF 프록시) |
| GitOps | ArgoCD, Tekton CI/CD, Gitea (자체 호스팅) |
| Container | Zot 자체 레지스트리 |
| Observability | Prometheus → Thanos, Grafana, Loki, Tempo, OpenTelemetry |
| Security | Vault (VSO), Kyverno, Falco, Trivy, Teleport, Keycloak |
| Cluster | K3s (1 master + 3 workers, ARM64 VM.Standard.A1.Flex, Ubuntu 24.04) |
데이터 모델
멀티테넌시는 RLS(Row-Level Security) 기반 단일 public 스키마입니다. 물리적 스키마 분리(schema-per-tenant)는 2026-05-12에 제거되었고, 모든 테넌트 종속 테이블은 tenant_id 컬럼 + RLS 정책(FORCE ROW LEVEL SECURITY)으로 격리됩니다.
- 테넌트 종속 (RLS) — 학생/반/강의/과제/출결/시험/수강료 등 학원별 데이터
- 플랫폼 (RLS 없음) — 테넌트 메타, OWNER 디렉토리, 구독/청구(billing) 테이블
- langgraph — LangGraph 체크포인터 전용 스키마 (테넌트 데이터 없음)
런타임은 lumie_app(NOSUPERUSER NOBYPASSRLS) 역할로 접속해 RLS가 적용되며, Flyway 마이그레이션만 postgres 역할을 사용합니다. 자세한 내용: 데이터 모델 개요. 전체 ERD: ERD 개요.
문서 바로가기
| 카테고리 | 설명 |
|---|---|
| 아키텍처 | 시스템 아키텍처, 기술 스택 |
| 백엔드 | 17개 모듈, 헥사고날 |
| 프론트엔드 | FSD, App Router |
| Worker (AI) | grading / report / analysis |
| ERD | 전체 데이터 모델 다이어그램 |
| 인프라 | K3s 4노드, OCI 2계정 |
| 개발 환경 | 로컬 환경, Tilt, 컨벤션 |