기술 스택
Lumie는 의도적으로 local-first 웹 프론트엔드, 단일 Spring Boot 모듈러 모놀리스, 소수의 독립 FastAPI 워커, 그리고 GitOps로 관리되는 플랫폼 계층으로 나뉘어 있습니다. 이 페이지는 주요 기술 선택과 이들이 함께 맞물리는 방식을 요약합니다.
스택 한눈에 보기
| 영역 | 주요 선택 | 참고 |
|---|---|---|
| 프론트엔드 | Next.js 16 App Router, React 19, TypeScript 5 | 브라우저 앱은 개발 환경에서 로컬로 실행되며, 백엔드에 도달하기 위해 same-origin /api/... 프록시 라우트를 사용합니다. |
| 프론트엔드 상태 및 폼 | TanStack Query, Zustand, React Hook Form, Zod | Query 상태, 로컬 UI 상태, 타입이 지정된 폼 검증은 하나의 전역 저장소 대신 각각 분리해 처리합니다. |
| 프론트엔드 스타일링 및 UI | Tailwind CSS 4, Radix UI, class-variance-authority, lucide-react | 공유 UI 프리미티브는 제품 전용 위젯 및 feature slice와 함께 배치됩니다. |
| 프론트엔드 API 계약 | springdoc 기반 OpenAPI, orval 코드 생성 | 백엔드는 /v3/api-docs를 게시하고, 프론트엔드는 커밋된 스냅샷에서 엔티티 범위의 React Query 클라이언트를 생성합니다. |
| 백엔드 런타임 | Java 21, Spring Boot 3.4, Spring Security, Spring Data JPA, Bean Validation | 핵심 제품 로직은 코드 수준 모듈 경계를 가진 하나의 배포 가능한 애플리케이션에 존재합니다. |
| 백엔드 모듈성 및 작업 | Spring Modulith, JDBC event publication, ShedLock, Bucket4j | Modulith 이벤트는 모듈 간 비동기 작업을 뒷받침하고, ShedLock은 스케줄 작업을 보호하며, Bucket4j는 pod별 rate limiting을 처리합니다. |
| 워커 | Python 3.11+, FastAPI, Pydantic v2, aio-pika, httpx | 워커는 다른 런타임이나 확장 모델이 유용한 경우에만 분리됩니다. |
| 데이터 및 메시징 | PostgreSQL, RabbitMQ, Redis, MinIO | PostgreSQL은 source of truth이고, RabbitMQ는 백그라운드 작업을 전달하며, Redis는 캐시 성격의 워크로드를 지원하고, MinIO는 객체를 저장합니다. |
| 플랫폼 | K3s, ArgoCD, Traefik, Vault Secrets Operator, Cert-Manager, Zot | 클러스터는 GitOps로 관리되고, 시크릿은 Vault에서 오며, 이미지는 Zot을 통해 미러링됩니다. |
| 관측성 및 보안 | Prometheus, Grafana, Loki, Tempo, OpenTelemetry, Kyverno, Falco | 플랫폼 가시성과 정책은 lumie-infra에서 제품 저장소 밖에서 관리합니다. |
| 개발 도구 | Tilt, Gradle, Testcontainers, ArchUnit, Vitest, Playwright, Ruff, mypy, Docusaurus 3 | 도구는 모든 저장소에 하나의 스택을 강제하기보다 저장소 경계를 따릅니다. |
소스 앵커
| 경로 | 무엇을 고정하는가 |
|---|---|
lumie-frontend/package.json | Next.js, React, TypeScript, TanStack Query, Zustand, React Hook Form, Zod, Tailwind, Radix UI, Orval, Vitest, Playwright 의존성 |
lumie-frontend/app/api/[...path]/route.ts | 프론트엔드의 same-origin API 프록시 계약 |
lumie-backend/gradle/libs.versions.toml | Java, Spring Boot, Spring Modulith, ShedLock, Bucket4j, springdoc, MinIO, ArchUnit 버전 |
lumie-backend/app/build.gradle.kts | 배포 산출물에 실제로 조립되는 백엔드 런타임 및 테스트 스택 |
lumie-worker/pyproject.toml | 워크스페이스 전반의 Python 3.11, Ruff, mypy 기준선 |
lumie-worker/services/{analysis,grading,report,chatbot}/pyproject.toml | 서비스별 FastAPI, aio-pika, httpx, 관측성 의존성 |
lumie-infra/bootstrap/kustomization.yaml | MinIO, Zot, Vault 같은 bootstrap 소유 플랫폼 서비스 |
lumie-infra/platform/kustomization.yaml | Traefik, cert-manager, RabbitMQ, KEDA 및 기타 클러스터 전역 플랫폼 서비스 |
lumie-infra/{bootstrap,platform,storage,security,observability,applications}/application.yaml | Argo CD로 관리되는 GitOps slice 레이아웃 |
lumie-document/docusaurus/package.json | Docusaurus 3 사이트 도구 |
프론트엔드
프론트엔드는 lumie-frontend에 있으며 React 19와 TypeScript를 사용하는
Next.js App Router 기반으로 구축됩니다. 코드베이스는 src/shared,
src/entities, src/features, src/widgets 아래에 Feature-Sliced 스타일
구조를 사용하며, import 방향은 관례로만 두지 않고 ESLint에서 강제합니다.
데이터 페칭은 orval을 통해 백엔드 OpenAPI spec에서 생성되며, 클라이언트
런타임으로 TanStack Query를 사용합니다. 폼은 React Hook Form과 Zod를 함께
사용하고, 로컬 UI 상태는 필요한 경우 Zustand를 사용하며, 시각 계층은
Tailwind CSS 4와 Radix 기반 프리미티브로 구성됩니다.
백엔드
백엔드는 lumie-backend에 있으며 마이크로서비스 집합이 아니라 모듈러
모놀리스입니다. app은 하나의 Spring Boot 배포 가능 산출물을 만들고,
modules/*와 libs/*는 내부 모듈 경계를 정의합니다. 런타임 스택은 Spring
Web, Spring Data JPA, Spring Security, Bean Validation을 중심으로 합니다.
Spring Modulith는 내구성 있는 after-commit event publication에 사용되고,
springdoc-openapi는 HTTP 계약을 노출하며, ShedLock은 multi-pod 배포의
스케줄 작업을 보호하고, Bucket4j는 token-bucket rate limiting을
제공합니다. 백엔드 빌드는 Java 21 toolchain과 함께 Gradle, Spotless,
Error Prone, JaCoCo, ArchUnit, Testcontainers 기반 통합 테스트를
사용합니다.
워커
워커 저장소 lumie-worker에는 grading, report generation, analysis,
chatbot workload 같은 여러 개별 배포 FastAPI 서비스가 들어 있습니다. 이
서비스들은 Python 3.11 기준선과 FastAPI, Pydantic v2, 프로세스 환경 기반
설정을 공유합니다.
RabbitMQ consumer는 aio-pika를 사용하고, 백엔드 호출은 httpx를
사용하며, 객체 기반 워크플로는 MinIO를 사용합니다. 이 저장소는 포매팅과
린팅에 Ruff를, 타입 검사에 mypy를 표준으로 사용합니다.
데이터 및 메시징
PostgreSQL은 주요 트랜잭션 저장소입니다. Lumie는 테넌트 범위 테이블이 Row
Level Security로 보호되는 공유 public schema를 사용하므로,
멀티테넌시는 schema-per-tenant 설계가 아니라 데이터베이스에서 강제됩니다.
RabbitMQ는 채점과 리포트 생성 같은 비동기 워크플로를 처리합니다. Redis는 플랫폼 기반 캐시나 조정 용도에 사용되며, MinIO는 업로드된 파일과 생성 산 출물을 저장합니다.
플랫폼 및 전달
lumie-infra는 플랫폼을 GitOps 저장소로 관리합니다. 클러스터는 K3s에서
실행되고, ArgoCD는 애플리케이션 상태를 reconcile하며, Traefik은 ingress를
처리하고, Cert-Manager는 인증서를 발급하며, Vault와 Vault Secrets
Operator는 런타임 시크릿을 공급합니다. 이미지는 퍼블릭 레지스트리에서 직접
끌어오지 않고 Zot을 통해 흐르도록 설계되어 있습니다.
일상 개발에서는 Tilt가 로컬과 클러스터 조각을 묶어 줍니다. 프론트엔드는 개발자 머신에서 HMR과 함께 실행되고, 백엔드, 워커, 상태 저장 서비스는 dev 클러스터에서 실행됩니다.
계약 및 문서화 도구
다음 두 가지 보조 도구도 일상 스택의 일부입니다.
- Docusaurus 3는
lumie-document의 제품 문서 사이트를 구동합니다. .codex는 저장소 전반의 공용 워크플로, 라우팅, 규칙, 자동화 관례를 담고 있습니다.
검증
스택 관련 주장의 source of truth로 체크인된 매니페스트와 패키지 파일을 사용하세요.
cd /Users/bluemayne/Projects/Lumie
rg -n "\"next\"|\"react\"|\"typescript\"|\"@tanstack/react-query\"|\"zustand\"|\"react-hook-form\"|\"zod\"|\"tailwindcss\"|\"orval\"|\"vitest\"|\"@playwright/test\"" \
lumie-frontend/package.json
rg -n "java +=|spring-boot +=|spring-modulith +=|shedlock +=|bucket4j +=|springdoc-openapi +=|archunit +=|testcontainers|spring-boot-starter-security|spring-boot-starter-data-jpa" \
lumie-backend/gradle/libs.versions.toml \
lumie-backend/app/build.gradle.kts
rg -n "requires-python|fastapi==|aio-pika==|httpx==|prometheus-client==|opentelemetry-" \
lumie-worker/pyproject.toml \
lumie-worker/services/analysis/pyproject.toml \
lumie-worker/services/grading/pyproject.toml \
lumie-worker/services/report/pyproject.toml \
lumie-worker/services/chatbot/pyproject.toml
rg -n "minio/argocd.yaml|zot/argocd.yaml|vault/argocd.yaml|traefik-config/argocd.yaml|cert-manager/argocd.yaml|rabbitmq/argocd.yaml|keda/argocd.yaml" \
lumie-infra/bootstrap/kustomization.yaml \
lumie-infra/platform/kustomization.yaml
rg -n "\"@docusaurus/core\"|\"@docusaurus/preset-classic\"" \
lumie-document/docusaurus/package.json
성공 신호:
- 프론트엔드 의존성 매니페스트에 이 페이지에서 언급한 프레임워크, 상태, 폼, 스타일링, 테스트 라이브러리가 여전히 표시됩니다.
- 백엔드 버전 카탈로그와 app 빌드 파일에 Java 21 및 Spring Boot 3.4 기반 단일 배포 단위와 Modulith, ShedLock, Bucket4j, springdoc, ArchUnit, Testcontainers가 계속 나타납니다.
- 워커 서비스 매니페스트는 여전히 Python 3.11 FastAPI 런타임을 선언하며,
aio-pika는 queue 기반 서비스에만,httpx는 플랫폼으로 다시 호출하는 서비스에만 사용됩니다. - 인프라 kustomization은 Vault, Zot, Traefik, cert-manager, RabbitMQ, KEDA를 이 문서에서 설명한 플랫폼 계층에 계속 배치합니다.