Mimi / shadow-ai X-Ray

Mimi 구조를 백엔드부터 인프라까지 설명하는 페이지

목표는 과장된 포트폴리오 문장이 아니다. 제품 목적, 언어 선택 이유, backend domains, web/mobile flow, AI pipeline, data model, infra tradeoff까지 네 입으로 설명하게 만드는 것이다.

cards

domains

flows

One sentence

Mimi is a full-stack English shadowing system: YouTube input becomes clips, cached AI explanations, voice recording, SM-2 review, and daily output drills across web and mobile.

제품은 단순 AI wrapper가 아니라, Spring backend가 상태/권한/트랜잭션을 잡고 Next/Expo가 반복 훈련 UI를 제공하는 학습 시스템이다.

Tech stack from absolute zero

여기는 Mimi를 설명하기 위한 스택 해부다. 각 카드를 열면 Java/Spring/Next/Expo/Postgres/JWT/Docker/Caddy 같은 단어가 뭔지, 왜 썼는지, 대안과 trade-off가 뭔지, 어디 코드에 있는지, 면접 영어 문장까지 바로 나온다.

stack cards

0. Product shape

0. Product shapeCore

Full-stack learning product

유튜브 입력을 영어 출력 훈련으로 바꾸는 제품 구조다.

Mimi is a full-stack learning loop, not just a prompt UI: the system owns clips, analysis, recordings, review state, and daily drills.

What it does

영상 import, clip, AI explanation, recording, review, daily drill을 하나의 학습 loop로 연결한다.

Why this stack

단순 chat wrapper가 아니라 상태, 권한, 복습, 녹음, 콘텐츠 캐시가 필요한 제품이라 full-stack 구조가 맞다.

Trade-off

구현 범위가 넓다. 그래서 domain boundary와 핵심 loop를 계속 좁혀 말해야 한다.

Alternative

초기 MVP라면 mobile-only, web-only, 또는 노트 기반 앱으로 줄일 수 있다.

Terms you must know

full-stack = UI, backend, data, infra가 다 있는 제품
learning loop = 학습자가 반복해서 돌아오는 행동 흐름
stateful product = 서버가 사용자의 상태를 기억하는 제품

Where

shadow-ai README, frontend, mobile, backend

Beginner trap

AI가 있으니 backend가 필요 없다고 생각하면 안 된다.

0. Product shapeCore

@shadow-ai/core

웹과 모바일이 공유하는 TypeScript 패키지다.

The shared core package keeps platform-neutral learning content and helpers consistent across web and mobile.

What it does

practice content, parser, SRS helper 같은 platform-independent logic을 담는다.

Why this stack

같은 훈련 콘텐츠를 web/mobile에서 복붙하지 않고 하나의 source로 유지한다.

Trade-off

공유 범위를 너무 넓히면 platform-specific UX까지 억지로 묶인다.

Alternative

각 app 내부 중복은 단순하지만 drift가 생기고, backend-generated content는 중앙 통제는 좋지만 offline/UX 제약이 있다.

Terms you must know

monorepo package = 같은 repo 안의 재사용 패키지
pure helper = platform API 없이 계산만 하는 함수
drift = 복사본들이 서로 달라지는 현상

Where

packages/core, frontend/mobile package.json

Beginner trap

모든 코드를 공유하려고 하면 오히려 구조가 뻣뻣해진다.

0. Product shapeCore

SM-2 + Leitner SRS

복습 간격을 정하는 학습 알고리즘이다.

Mimi uses different SRS models because clip review and binary practice drills produce different feedback signals.

What it does

clip review는 0-5 quality 기반 SM-2, practice drill은 맞음/틀림 기반 Leitner를 사용한다.

Why this stack

채점 입력이 다르기 때문에 하나의 알고리즘에 억지로 합치지 않은 점이 설계 포인트다.

Trade-off

SRS는 실제 retention 실험과 tuning이 필요하다. 알고리즘만 넣으면 학습 효과가 증명되지는 않는다.

Alternative

단순 daily queue, FSRS, spaced repetition SaaS API가 대안이다.

Terms you must know

SRS = spaced repetition system
SM-2 = SuperMemo 계열 간격 반복 알고리즘
Leitner = box를 올리고 내리는 단순 반복 시스템

Where

ReviewService, Sm2Calculator, PracticeSrsService, packages/core/practice-srs

Beginner trap

SRS 알고리즘이 있으면 교육 효과가 검증됐다고 말하면 안 된다.

1. Languages

1. LanguagesCore

TypeScript

웹, 모바일, 공유 패키지의 주 언어다.

TypeScript gives the UI and shared learning content a typed contract across web and mobile.

What it does

React/Next/Expo UI와 shared core content를 타입 있는 JavaScript로 작성한다.

Why this stack

프론트와 모바일에서 같은 언어를 쓰면 모델, helper, 학습 콘텐츠를 공유하기 쉽다.

Trade-off

런타임 타입 보장은 아니다. API boundary에서는 validation이 따로 필요하다.

Alternative

plain JavaScript는 빠르지만 큰 앱에서 refactor 안정성이 낮고, Kotlin/Swift native는 플랫폼별 중복이 늘어난다.

Terms you must know

type = 값의 모양에 대한 약속
compile-time = 실행 전에 잡는 단계
runtime = 실제 앱이 도는 시간

Where

frontend, mobile, packages/core

Beginner trap

TypeScript가 DB/API 오류까지 자동으로 막는다고 말하지 말라.

1. LanguagesCore

Java 21

Spring backend의 언어다.

I used Java 21 because the backend needs mature transactions, security, persistence, async jobs, and observability.

What it does

auth, transaction, JPA, async event, AI provider orchestration 같은 서버 로직을 실행한다.

Why this stack

백엔드 면접에서 설명 가능한 성숙한 생태계이고, Spring/JPA/Security/Actuator 조합이 강하다.

Trade-off

boilerplate와 JVM 운영 복잡도가 있다. 작은 prototype이면 Node/FastAPI가 더 빠를 수 있다.

Alternative

Node.js는 TS 공유가 쉽고, Go는 단일 바이너리와 concurrency가 좋고, Python은 AI prototype이 빠르다.

Terms you must know

JVM = Java 프로그램을 실행하는 가상 머신
LTS = 장기 지원 버전
backend service = 서버에서 상태와 규칙을 책임지는 프로세스

Where

backend/build.gradle.kts, backend/src/main/java

Beginner trap

Java를 썼다고 자동으로 enterprise-grade라고 말하면 안 된다.

1. LanguagesCore

Gradle Kotlin DSL

Java backend 빌드 설정 언어다.

Gradle Kotlin DSL pins the Java toolchain and dependency graph for the Spring backend.

What it does

Spring Boot plugin, dependency management, Java toolchain, test task를 선언한다.

Why this stack

Kotlin DSL은 문자열 기반 Groovy보다 IDE 지원과 타입 힌트가 좋다.

Trade-off

Gradle 자체가 낯설면 복잡해 보인다. 작은 프로젝트는 Maven이 더 단순할 수 있다.

Alternative

Maven은 convention이 강하고 단순하지만, custom build logic은 Gradle이 유연하다.

Terms you must know

build tool = 컴파일/테스트/패키징을 자동화하는 도구
DSL = 특정 목적에 맞춘 작은 언어
toolchain = 어떤 Java 버전으로 빌드할지 고정하는 설정

Where

backend/build.gradle.kts

Beginner trap

Gradle 설정을 application runtime 코드와 혼동하지 말라.

3. Frontend

3. FrontendCore

Next.js 16

React 웹앱의 라우팅과 빌드를 담당하는 프레임워크다.

Next gives the web app routing, build, and deployment structure around the React training screens.

What it does

App Router, routing, build, deployment, React 화면 구성을 담당한다.

Why this stack

Mimi web은 로그인, library, clip player, review/practice screen이 있어서 React 기반 full app 구조가 맞다.

Trade-off

Next는 framework weight와 server/client boundary 복잡성이 있다.

Alternative

Vite SPA는 단순하고 빠르며, Remix는 data mutation 흐름이 강하고, plain React는 framework 기능이 적다.

Terms you must know

App Router = 폴더 기반 라우팅
SSR = 서버에서 HTML을 만드는 방식
client component = 브라우저에서 상호작용하는 React component

Where

frontend/package.json, frontend/app

Beginner trap

Next를 썼다고 모든 페이지가 SSR이라는 뜻은 아니다.

3. FrontendCore

React 19

웹 UI를 component로 만드는 라이브러리다.

React lets the product compose repeated learning surfaces as state-driven components.

What it does

player, panels, cards, review flow, settings 같은 UI를 상태 기반으로 렌더링한다.

Why this stack

상호작용 많은 학습 앱에 component model이 잘 맞고 web/mobile mental model도 공유된다.

Trade-off

상태가 복잡해지면 re-render와 data ownership을 신경 써야 한다.

Alternative

Vue/Svelte는 더 단순한 syntax를 제공하고, native template framework는 플랫폼 밀착도가 높다.

Terms you must know

component = UI 조각
state = 화면을 바꾸는 데이터
render = state를 화면으로 그리는 과정

Where

frontend components/app

Beginner trap

React는 UI library이지 backend나 DB를 대체하지 않는다.

3. FrontendCore

TanStack Query

서버 데이터를 가져오고 캐시하는 client state 도구다.

TanStack Query manages server state, caching, and refetching for the web client.

What it does

clips, analysis, review queue 같은 API 결과를 fetch/cache/refetch한다.

Why this stack

server state와 local UI state를 분리해 loading/error/retry를 일관되게 처리한다.

Trade-off

cache invalidation을 잘못하면 오래된 화면을 보여줄 수 있다.

Alternative

SWR은 더 단순하고, 직접 fetch/useEffect는 작지만 반복과 edge case가 늘어난다.

Terms you must know

server state = 서버에서 온 데이터
cache = 다시 쓰려고 저장한 응답
invalidation = 캐시를 오래됐다고 표시하는 것

Where

frontend package.json, API hooks

Beginner trap

React Query를 쓰면 backend consistency 문제가 사라지는 건 아니다.

3. FrontendCore

Zustand

브라우저 안의 작은 UI 상태를 보관하는 저장소다.

Zustand is used for lightweight local UI state, while server data belongs in TanStack Query.

What it does

player 상태, local UI preference, transient interaction state를 간단하게 관리한다.

Why this stack

Redux보다 보일러플레이트가 적고, 복잡하지 않은 앱 상태에 빠르다.

Trade-off

큰 앱에서 store가 무질서해지면 추적이 어렵다. 서버 상태까지 넣으면 꼬인다.

Alternative

Redux Toolkit은 규칙이 강하고, Jotai는 atom 기반이며, React context는 작은 범위에 적합하다.

Terms you must know

client state = 브라우저 안에서만 필요한 상태
store = 여러 component가 공유하는 상태 저장소
transient = 잠깐 필요한 상태

Where

frontend package.json, frontend stores

Beginner trap

모든 상태를 Zustand에 넣으면 안 된다.

3. FrontendCore

next-intl

다국어 routing과 message를 관리한다.

next-intl keeps localized UI text and routes explicit for a language-learning product.

What it does

영어/한국어 UI text와 locale path를 Next 구조 안에서 처리한다.

Why this stack

영어 학습 제품이라 language surface가 제품 핵심이므로 i18n 구조가 필요하다.

Trade-off

번역 key 관리가 늘고, dynamic text와 콘텐츠 번역 경계가 헷갈릴 수 있다.

Alternative

next-i18next, custom dictionary, CMS 기반 translation이 대안이다.

Terms you must know

i18n = internationalization, 다국어 준비
locale = en/ko 같은 지역/언어 설정
message key = 번역 문장을 찾는 이름

Where

frontend package.json, locale routes/messages

Beginner trap

i18n은 번역 파일만이 아니라 route, formatting, product copy 문제다.

3. FrontendCore

Tailwind + shadcn/ui

UI 스타일과 component 기본형을 만든다.

Tailwind and shadcn let the app ship consistent UI quickly without building every primitive from scratch.

What it does

반복 화면, 카드, 버튼, dialog, form을 빠르게 조립한다.

Why this stack

학습 앱은 화면이 많아서 utility CSS와 component recipe가 생산성을 준다.

Trade-off

클래스가 길어지고 디자인 체계 없이 쓰면 화면이 산만해질 수 있다.

Alternative

CSS Modules, MUI, Chakra, Radix 직접 조합, custom design system이 대안이다.

Terms you must know

utility CSS = 작은 class를 조합하는 스타일 방식
component recipe = 재사용 가능한 UI 조합
design system = 일관된 UI 규칙 묶음

Where

frontend package.json, components/ui

Beginner trap

shadcn은 설치형 코드이지 완성된 디자인 시스템이 아니다.

4. Mobile

4. MobileCore

Expo 56

React Native 앱 개발/빌드 플랫폼이다.

Expo gives Mimi a fast path to a real mobile training surface with native audio, storage, and routing.

What it does

iOS/Android dev server, native module integration, release script, Expo Router entry를 제공한다.

Why this stack

걸으면서 반복 훈련하는 phone-first 제품이라 mobile app이 필요하고 Expo가 빠른 iteration을 준다.

Trade-off

native edge case가 생기면 Expo abstraction을 이해해야 하고, bare/native 설정 지식도 필요하다.

Alternative

순수 React Native CLI는 native 제어가 강하고, Swift/Kotlin native는 UX 밀착도가 높지만 개발량이 늘어난다.

Terms you must know

managed workflow = Expo가 native 설정 일부를 관리
native module = OS 기능을 쓰는 bridge
dev client = 개발용 앱 shell

Where

mobile/package.json, mobile app config

Beginner trap

Expo는 웹앱 포장지가 아니라 native app build system이다.

4. MobileCore

React Native

React 방식으로 native mobile UI를 만드는 프레임워크다.

React Native lets Mimi reuse React patterns while delivering a phone-native training experience.

What it does

탭, 화면, gesture, safe area, WebView, recording UI를 iOS/Android component로 만든다.

Why this stack

React mental model을 유지하면서 실제 phone UX를 만들 수 있다.

Trade-off

플랫폼별 차이와 native module 문제는 피할 수 없다.

Alternative

SwiftUI/Kotlin native는 성능과 platform fit이 좋고, Flutter는 자체 rendering stack이 강하다.

Terms you must know

bridge = JS와 native 사이 연결
native view = OS가 그리는 실제 UI 요소
safe area = notch/home indicator를 피하는 화면 영역

Where

mobile/src/app, mobile components

Beginner trap

React Native가 브라우저 React와 완전히 같다고 생각하면 안 된다.

4. MobileCore

Expo Router

모바일 화면 이동을 파일 구조로 관리하는 라우터다.

Expo Router gives the mobile app a file-based navigation model similar to modern web routing.

What it does

mobile/src/app 폴더 구조로 tabs, stack screens, dynamic routes를 만든다.

Why this stack

Next App Router와 비슷한 mental model이라 web/mobile navigation을 설명하기 쉽다.

Trade-off

복잡한 deep link와 auth guard는 구조를 잘 잡아야 한다.

Alternative

React Navigation 직접 구성은 더 유연하지만 boilerplate가 늘어난다.

Terms you must know

route = 이동 가능한 화면 경로
stack = 화면을 쌓는 navigation 방식
tabs = 하단 탭 navigation

Where

mobile/src/app

Beginner trap

라우팅은 화면 전환이지 서버 API 설계가 아니다.

4. MobileCore

Expo SecureStore

모바일에 민감한 값을 저장하는 secure storage다.

SecureStore is used so mobile auth tokens are not stored as plain local app data.

What it does

JWT 같은 session token을 일반 AsyncStorage보다 안전한 OS storage에 넣는다.

Why this stack

모바일 token은 탈취 위험이 있으므로 OS keychain/keystore 계층을 써야 한다.

Trade-off

기기 백업/생체인증/삭제 동작은 플랫폼별로 다를 수 있다.

Alternative

Keychain 직접 사용, MMKV encrypted storage, server session cookie가 대안이다.

Terms you must know

keychain = iOS 보안 저장소
keystore = Android 보안 저장소
token storage = 로그인 증명을 어디에 보관하는지

Where

mobile package.json, auth storage

Beginner trap

SecureStore를 쓴다고 jailbroken/rooted device risk가 없어지지는 않는다.

4. MobileCore

React Native WebView

앱 안에서 웹 페이지/스크립트를 실행하는 native view다.

The mobile WebView path exists because transcript ingestion sometimes works better from the user's device than from a server IP.

What it does

모바일에서 YouTube caption endpoint를 device network로 fetch하는 보조 경로에 사용된다.

Why this stack

서버 datacenter IP가 막힐 때 사용자 device path가 import reliability를 높인다.

Trade-off

WebView injection은 brittle하고 policy/보안/디버깅 리스크가 있다.

Alternative

server-only yt-dlp, paid transcript API, user-uploaded caption이 대안이다.

Terms you must know

WebView = 앱 안의 작은 브라우저
injected JS = WebView 안에 넣어 실행하는 script
device IP = 사용자의 폰 네트워크 IP

Where

mobile/src/lib/youtube-transcript-webview.tsx

Beginner trap

WebView 수집이 공식 API처럼 안정적이라고 말하면 안 된다.

4. MobileCore

expo-audio / speech recognition

사용자 음성 녹음과 발화 훈련에 쓰는 native 기능이다.

Native audio support is central because Mimi trains spoken output, not only reading comprehension.

What it does

쉐도잉 녹음, 재생, 발화 입력/인식 flow를 mobile에서 처리한다.

Why this stack

영어 학습 제품은 읽기보다 말하기 output이 중요해서 audio capability가 핵심이다.

Trade-off

권한 요청, device compatibility, background behavior, file size 문제가 있다.

Alternative

웹 MediaRecorder, native AVFoundation/MediaRecorder, third-party speech SDK가 대안이다.

Terms you must know

audio recording = 마이크 입력을 파일/stream으로 저장
permission = OS가 사용자에게 허락받는 권한
speech recognition = 음성을 text로 바꾸는 기능

Where

mobile/package.json, recording screens

Beginner trap

마이크 기능은 UI 버튼만으로 끝나지 않고 권한/저장/업로드/삭제가 따라온다.

5. Backend

5. BackendCore

Spring Boot

Java backend를 빠르게 구성하는 프레임워크다.

Spring Boot lets the backend focus on domain logic while relying on mature HTTP, security, persistence, and observability modules.

What it does

HTTP API, dependency injection, security, validation, JPA, actuator 설정을 자동 구성한다.

Why this stack

Mimi는 사용자 상태와 트랜잭션이 많아서 Spring의 convention과 생태계를 활용하는 게 이득이다.

Trade-off

추상화가 많아 내부 동작을 모르면 magic처럼 보인다. cold start와 memory도 Node/Go보다 무거울 수 있다.

Alternative

Express/NestJS는 TS 일관성이 좋고, FastAPI는 AI prototype이 빠르고, Go HTTP는 단순하고 가볍다.

Terms you must know

framework = 공통 구조를 제공하는 틀
dependency injection = 필요한 객체를 프레임워크가 넣어주는 방식
auto-configuration = 설정을 관례대로 자동 조립하는 기능

Where

backend/build.gradle.kts, backend/src/main/java/com/tubeshadow

Beginner trap

Spring Boot가 business design을 대신 해주지는 않는다.

5. BackendCore

Spring MVC REST API

브라우저/앱이 호출하는 HTTP API layer다.

The REST API is the contract between the clients and the backend-owned domain state.

What it does

Controller가 request를 받고 Service가 domain logic을 처리하며 DTO로 응답한다.

Why this stack

web/mobile이 같은 backend contract를 쓰기 때문에 REST API가 명확한 integration point가 된다.

Trade-off

REST가 복잡한 실시간 협업에는 불편할 수 있다. over-fetching도 생길 수 있다.

Alternative

GraphQL은 클라이언트 query 자유도가 높고, gRPC는 내부 service 간 contract가 강하다.

Terms you must know

REST = URL과 HTTP method로 resource를 다루는 API 스타일
DTO = API 입출력 전용 객체
controller = HTTP boundary

Where

backend/*/api/*Controller.java

Beginner trap

Controller에 모든 비즈니스 로직을 넣으면 구조가 무너진다.

5. BackendCore

Bean Validation

입력값을 서버에서 검증하는 방식이다.

Server-side validation protects the API boundary even if the client is buggy or bypassed.

What it does

DTO에 NotBlank, Size 같은 제약을 두고 잘못된 요청을 빠르게 거절한다.

Why this stack

클라이언트 UI 검증은 우회 가능하므로 backend validation이 진짜 경계다.

Trade-off

복잡한 cross-field rule은 annotation만으로 부족해서 service validation이 필요하다.

Alternative

수동 if문은 명확하지만 반복이 늘고, JSON schema validation은 API boundary에 강하다.

Terms you must know

validation = 입력이 규칙에 맞는지 검사
constraint = 값이 지켜야 하는 조건
boundary = 신뢰할 수 없는 입력이 들어오는 경계

Where

spring-boot-starter-validation, request DTOs

Beginner trap

프론트 검증이 있으니 서버 검증이 필요 없다고 보면 안 된다.

5. BackendCore

AFTER_COMMIT async event

클립 저장 후 AI 분석을 백그라운드로 넘기는 구조다.

The AI job runs after commit and outside the database transaction so slow provider calls do not hold DB connections.

What it does

ClipService가 DB commit 후 event를 발행하고 ClipAnalysisService가 @Async로 provider 호출을 처리한다.

Why this stack

LLM 호출은 느리고 실패 가능해서 request transaction 안에서 처리하면 connection과 UX가 망가진다.

Trade-off

in-process async라 서버가 죽으면 작업 유실 위험이 있다. retry queue가 더 강하다.

Alternative

SQS, RabbitMQ, Kafka, BullMQ 같은 durable queue를 쓰면 복구력이 좋아진다.

Terms you must know

transaction = DB 작업을 한 묶음으로 commit/rollback하는 단위
AFTER_COMMIT = DB commit 성공 후 실행
async = 요청 흐름과 분리해서 나중에 실행

Where

ClipService.java, ClipAnalysisService.java

Beginner trap

비동기라고 해서 자동으로 durable job queue가 되는 건 아니다.

5. BackendCore

RestClient / WebClient

외부 HTTP API를 호출하는 Spring client다.

External API calls are isolated behind clients so provider-specific failures do not leak into domain code.

What it does

LLM provider, YouTube-related service, Supadata 같은 외부 endpoint와 통신한다.

Why this stack

Spring 생태계 안에서 timeout, serialization, error handling을 구성하기 좋다.

Trade-off

blocking client를 async path에서 잘못 쓰면 thread를 잡아먹을 수 있다.

Alternative

OkHttp, Feign, raw Java HttpClient, Node fetch가 대안이다.

Terms you must know

HTTP client = 다른 서버를 호출하는 코드
timeout = 너무 오래 기다리지 않고 끊는 시간
retry = 실패한 호출을 다시 시도

Where

AI clients, YoutubeTranscriptClient

Beginner trap

외부 호출에는 timeout과 failure handling이 반드시 필요하다.

6. Data

6. DataCore

Spring Data JPA / Hibernate

Java 객체와 DB table을 연결하는 persistence layer다.

JPA is useful for domain persistence, but I still need to watch query shape and transaction boundaries.

What it does

Repository와 entity로 users/videos/clips/reviews 같은 row를 읽고 쓴다.

Why this stack

CRUD와 transaction 작업이 많아 생산성이 좋고, domain code가 SQL 문자열에 묻히지 않는다.

Trade-off

N+1, lazy loading, transaction boundary를 모르면 성능 문제가 난다.

Alternative

jOOQ는 SQL 제어가 강하고, MyBatis는 명시 SQL이 쉽고, raw SQL은 단순하지만 반복이 늘어난다.

Terms you must know

ORM = 객체와 관계형 DB를 매핑하는 기술
entity = DB row와 연결되는 Java 객체
lazy loading = 필요할 때 연관 데이터를 늦게 읽는 방식

Where

backend repositories/entities

Beginner trap

JPA를 쓰면 SQL을 몰라도 된다고 말하지 말라.

6. DataCore

PostgreSQL

권한과 학습 상태를 저장하는 주 DB다.

Postgres fits because Mimi needs relational ownership and constraints plus JSONB for semi-structured transcripts and AI analysis.

What it does

users, videos, library, clips, analyses, recordings, review/practice state를 저장한다.

Why this stack

관계형 소유권과 constraint가 중요하고, transcript/analysis는 JSONB로 담을 수 있어 잘 맞다.

Trade-off

수직 확장과 connection 수 한계가 있다. 무거운 analytics/search는 별도 계층이 필요할 수 있다.

Alternative

MongoDB는 flexible document에 강하고, DynamoDB는 managed scale이 좋지만 relational query와 constraint가 약해진다.

Terms you must know

RDBMS = table 관계와 transaction을 제공하는 DB
constraint = DB가 강제하는 규칙
JSONB = JSON을 binary 형태로 저장/검색하는 Postgres 타입

Where

backend migrations, docker-compose

Beginner trap

Postgres를 쓰면 확장 문제가 끝난다고 말하지 말라.

6. DataCore

Flyway migrations

DB schema 변경을 버전 파일로 관리한다.

Flyway makes the database schema versioned and reproducible across local, test, and production.

What it does

V1, V2 같은 SQL migration으로 table/index/constraint 변화를 재현 가능하게 만든다.

Why this stack

코드와 DB schema가 같이 진화해야 하므로 migration history가 필요하다.

Trade-off

잘못 배포한 migration은 되돌리기 어렵다. backward-compatible migration discipline이 필요하다.

Alternative

Liquibase는 더 많은 형식과 rollback 기능이 있고, 수동 SQL은 작지만 추적성이 약하다.

Terms you must know

migration = DB 구조 변경 기록
schema = table/index/constraint 설계
backward-compatible = 구버전 코드와도 깨지지 않는 변경

Where

backend/src/main/resources/db/migration

Beginner trap

entity만 바꾸고 DB가 자동으로 안전하게 바뀐다고 생각하면 안 된다.

6. DataCore

JSONB

자막과 AI 결과 같은 반구조 데이터를 저장하는 Postgres 타입이다.

JSONB is a pragmatic fit for AI and transcript payloads that are structured but still evolving.

What it does

transcript segments, analysis payload처럼 nested structure를 column 하나에 보관한다.

Why this stack

AI 결과 schema가 변할 수 있어서 모든 필드를 table로 찢기보다 JSONB가 유연하다.

Trade-off

query가 복잡해지면 index 설계가 어렵고, DB constraint가 약해진다.

Alternative

정규화 table은 query/constraint가 강하고, object storage는 큰 blob에 적합하지만 transactional query가 약하다.

Terms you must know

semi-structured = 모양은 있지만 자주 바뀌는 데이터
normalized = 중복을 줄이려고 table로 나누는 설계
index = 검색을 빠르게 하는 DB 구조

Where

clip_analyses, videos transcript JSON columns

Beginner trap

JSONB를 아무 데이터나 넣는 쓰레기통으로 쓰면 안 된다.

6. DataCore

HikariCP

DB connection pool이다.

Connection pooling matters because slow AI calls must not hold database connections.

What it does

Spring Boot가 기본으로 사용하며 backend thread가 Postgres connection을 재사용한다.

Why this stack

매 요청마다 새 connection을 만들면 느리고 비싸다. pool이 latency와 DB 부하를 줄인다.

Trade-off

pool 크기를 키운다고 무조건 처리량이 늘지 않는다. DB max connection과 slow query가 병목이다.

Alternative

PgBouncer 같은 external pooler를 둘 수도 있고, serverless DB는 provider pool을 쓸 수 있다.

Terms you must know

connection pool = DB 연결을 미리 만들어 재사용하는 묶음
leak = 빌린 연결을 반환하지 않는 문제
pool exhaustion = 모든 connection이 사용 중이라 대기하는 상태

Where

Spring Boot datasource defaults, backend runtime

Beginner trap

AI HTTP 호출 중 DB transaction을 오래 잡으면 pool이 고갈될 수 있다.

7. AI

7. AICore

AI provider fallback

Gemini/OpenAI/Claude 중 가능한 provider로 순차 시도하는 구조다.

The provider interface lets Mimi degrade across configured LLM providers instead of hard-failing on one vendor.

What it does

CompositeAiClient가 configured provider를 order대로 호출하고 실패하면 다음 provider로 넘어간다.

Why this stack

LLM provider는 quota, latency, outage가 있으므로 interface와 fallback이 실제 운영에 중요하다.

Trade-off

fallback은 비용과 결과 일관성을 흔들 수 있다. 모델별 output schema 차이를 검증해야 한다.

Alternative

단일 provider는 단순하고, gateway 서비스는 routing/observability를 맡길 수 있지만 vendor dependency가 생긴다.

Terms you must know

provider = 모델 API를 제공하는 회사/서비스
adapter = 공통 interface에 맞게 감싸는 코드
fallback = 실패 시 대체 경로

Where

CompositeAiClient.java, Gemini/OpenAi/Claude clients

Beginner trap

fallback이 있으면 품질과 비용 문제가 사라진다고 말하면 안 된다.

7. AICore

yt-dlp

YouTube metadata/caption을 가져오는 CLI 도구다.

yt-dlp is a pragmatic ingestion tool, but the system must treat it as a fragile external dependency.

What it does

서버에서 video info와 transcript를 뽑는 경로로 사용된다.

Why this stack

YouTube API가 주지 않는 caption/metadata 접근에 현실적으로 강하다.

Trade-off

YouTube 변경과 IP 차단에 취약하고, CLI dependency라 운영 환경 관리가 필요하다.

Alternative

Official YouTube Data API는 안정적이지만 caption 접근 제약이 있고, Supadata 같은 API는 비용과 vendor dependency가 있다.

Terms you must know

CLI = 터미널에서 실행하는 프로그램
metadata = 제목/길이 같은 설명 데이터
caption = 자막

Where

YoutubeTranscriptClient.java, Docker/runtime docs

Beginner trap

yt-dlp가 항상 합법적/안정적 API처럼 동작한다고 말하지 말라.

7. AICore

POToken sidecar

YouTube 접근 제한을 우회/보완하기 위한 별도 helper service다.

The POToken sidecar exists because YouTube ingestion can fail from server IPs, so ingestion needs multiple paths.

What it does

서버 IP에서 막히는 caption 접근을 보완하기 위해 token/provider sidecar를 둔다.

Why this stack

데이터센터 IP 차단 같은 현실 운영 문제를 제품 구조로 다룬 흔적이다.

Trade-off

sidecar가 추가되면 배포, 모니터링, 장애 지점도 늘어난다.

Alternative

모바일 WebView 수집, 유료 transcript API, 사용자 업로드 자막이 대안이다.

Terms you must know

sidecar = 주 서비스 옆에서 보조 기능을 하는 작은 서비스
datacenter IP = 클라우드 서버 IP
token = 접근에 필요한 증명값

Where

infrastructure/ncp, docker-compose, YoutubeTranscriptClient

Beginner trap

이 구조가 YouTube 정책 리스크를 없앤다고 말하면 안 된다.

7. AICore

Supadata fallback

자막을 가져오는 외부 API fallback이다.

Supadata is a resilience fallback for transcript ingestion, not the core product logic.

What it does

yt-dlp/POToken path가 실패할 때 transcript vendor를 통해 대체 수집한다.

Why this stack

핵심 import flow가 한 경로 실패로 완전히 죽지 않게 만든다.

Trade-off

비용, quota, vendor lock-in, 데이터 품질 차이가 생긴다.

Alternative

직접 crawler 유지, 모바일 device fetch, 사용자 자막 업로드가 대안이다.

Terms you must know

fallback API = 주 경로 실패 시 쓰는 외부 서비스
quota = 호출 가능 한도
vendor lock-in = 특정 업체 의존도가 높아지는 문제

Where

YoutubeTranscriptClient.java config

Beginner trap

fallback이 있으면 monitoring이 덜 필요하다고 생각하면 안 된다.

8. Infra

8. InfraCore

Docker

앱 실행 환경을 이미지로 포장한다.

Docker makes the runtime reproducible enough to move between local, NCP, and cloud deployment paths.

What it does

backend, pot-provider, ds-forge deployment 같은 runtime을 동일한 파일 시스템/command로 실행한다.

Why this stack

서버마다 설치 상태가 달라도 컨테이너 이미지로 재현성을 높인다.

Trade-off

이미지 빌드/보안 패치/volume/network 이해가 필요하고, local과 prod가 완전히 같지는 않다.

Alternative

VM 직접 배포는 단순하지만 drift가 크고, serverless는 운영 부담은 낮지만 runtime 제약이 있다.

Terms you must know

image = 실행 파일과 dependency를 묶은 template
container = image를 실행한 프로세스 격리 단위
volume = container 밖에 보존되는 저장소

Where

Dockerfile, docker-compose.yml, infrastructure

Beginner trap

Docker가 security나 scaling을 자동 해결한다고 말하면 안 된다.

8. InfraCore

Docker Compose

여러 컨테이너를 한 파일로 같이 실행한다.

Compose is a pragmatic single-box orchestration layer for early deployment and debugging.

What it does

backend, Postgres, Caddy, pot-provider 같은 서비스를 local/NCP 단일 박스에서 묶는다.

Why this stack

초기 운영에서 이해와 복구가 쉽고 비용이 낮다.

Trade-off

단일 서버 HA가 약하고 rolling deploy/auto scale은 직접 챙겨야 한다.

Alternative

Kubernetes는 orchestration이 강하지만 복잡하고, ECS는 managed container 배포에 좋다.

Terms you must know

service = compose 안의 컨테이너 단위
network = 컨테이너끼리 통신하는 가상망
single box = 한 VM 안에 여러 서비스가 있는 구조

Where

docker-compose.yml, infrastructure/ncp

Beginner trap

Compose를 쓴다고 production-grade HA가 되는 건 아니다.

8. InfraCore

Caddy

reverse proxy와 HTTPS termination을 담당한다.

Caddy keeps the NCP deployment simple by handling HTTPS and routing in front of the containers.

What it does

도메인 요청을 container로 보내고 TLS 인증서를 자동 처리한다.

Why this stack

NCP 단일 서버에서 nginx보다 설정이 단순하고 Let's Encrypt 자동화가 편하다.

Trade-off

복잡한 enterprise routing이나 custom module ecosystem은 nginx/Envoy가 더 강할 수 있다.

Alternative

nginx는 널리 쓰이고, Traefik은 container discovery가 강하고, AWS ALB는 managed L7 proxy다.

Terms you must know

reverse proxy = 앞에서 요청을 받아 뒤 서비스로 넘기는 서버
TLS termination = HTTPS 암호화를 proxy에서 끝내는 것
Caddyfile = Caddy 설정 파일

Where

infrastructure/ncp, deploy-ncp.sh

Beginner trap

Caddy가 앱 인증을 대신하는 것은 아니다.

8. InfraCore

NCP single VM

현재 비용/지연시간 중심의 단일 서버 운영 경로다.

The NCP single-box deployment is a cost and latency trade-off, not a high-availability architecture.

What it does

Caddy, backend, Postgres, sidecar를 한 VM/Docker network에 올리는 방식이다.

Why this stack

초기 제품에서 비용과 한국 latency를 줄이고 운영을 눈으로 확인하기 좋다.

Trade-off

HA가 약하다. VM 장애, disk 장애, backup/restore, deploy rollback을 직접 책임져야 한다.

Alternative

AWS ECS/RDS처럼 managed service를 쓰면 HA/backup은 좋아지지만 비용과 복잡도가 늘어난다.

Terms you must know

VM = 가상 서버
HA = 장애가 나도 서비스가 계속 되는 구조
backup/restore = 데이터 복구 계획

Where

infrastructure/ncp, deploy scripts

Beginner trap

단일 박스를 production이라고 말할 수는 있어도 HA라고 말하면 안 된다.

8. InfraCore

AWS ECS / RDS / S3 path

더 managed한 AWS 배포 설계 경로다.

The AWS path separates compute, database, storage, and secrets for a more managed production architecture.

What it does

ECS는 backend container, RDS는 Postgres, S3는 recording object storage, Secrets Manager는 secret을 맡는다.

Why this stack

운영 안정성, backup, IAM, managed DB가 필요할 때 자연스러운 확장 경로다.

Trade-off

비용과 Terraform/IAM/네트워크 복잡도가 커진다.

Alternative

NCP single box는 단순/저렴하고, Fly.io/Render/Railway는 더 쉬운 PaaS 대안이다.

Terms you must know

ECS = AWS container orchestration
RDS = managed relational DB
S3 = object storage
IAM = AWS 권한 시스템

Where

infrastructure/aws, INFRA_DEEP_DIVE.md

Beginner trap

AWS를 문서화했다고 지금 모든 운영이 AWS에서 도는 것처럼 말하면 안 된다.

8. InfraCore

Vercel web deployment

Next.js 웹 배포 플랫폼이다.

Vercel is a good fit for the web surface, while stateful backend concerns stay in the backend infrastructure.

What it does

frontend를 build/deploy하고 CDN/preview deployment와 연결한다.

Why this stack

Next.js 앱을 빠르게 배포하고 preview URL로 검증하기 좋다.

Trade-off

backend/stateful workload에는 맞지 않고 vendor platform behavior에 의존한다.

Alternative

Netlify, Cloudflare Pages, self-hosted Next, Docker deployment가 대안이다.

Terms you must know

CDN = 정적 자산을 가까운 edge에서 주는 네트워크
preview deployment = PR/branch별 미리보기 배포
serverless = 요청마다 관리형 실행 환경에서 도는 방식

Where

frontend deployment, Vercel project

Beginner trap

Vercel에 배포됐다고 backend도 Vercel에 있다는 뜻은 아니다.

8. InfraCore

S3-compatible recording storage

녹음 파일 bytes를 저장하는 object storage 계층이다.

The storage seam keeps recording bytes out of Postgres and allows local or S3-compatible storage behind the same interface.

What it does

DB에는 metadata만 저장하고 실제 audio bytes는 Local/S3 구현체가 보관한다.

Why this stack

파일을 DB에 직접 넣지 않아 DB 부하를 줄이고 storage backend를 바꿀 수 있다.

Trade-off

object lifecycle, access control, signed URL/streaming, delete policy를 설계해야 한다.

Alternative

local disk는 단순하지만 서버 장애에 약하고, DB blob은 transaction은 쉽지만 DB가 무거워진다.

Terms you must know

object storage = 파일 같은 큰 객체를 key로 저장하는 서비스
metadata = 파일 설명 정보
streaming = 파일을 조금씩 읽어 보내는 방식

Where

RecordingStorage, S3RecordingStorage, LocalRecordingStorage

Beginner trap

S3를 쓰면 privacy가 자동으로 해결되는 건 아니다.

9. Security

9. SecurityCore

Spring Security

인증과 권한 검사를 담당하는 필터 체인이다.

Spring Security is the backend gate that authenticates requests and enforces protected API access.

What it does

JWT filter, password hashing, CORS, protected routes를 강제한다.

Why this stack

사용자별 clips/recordings/reviews가 있으므로 backend에서 identity와 authorization을 안정적으로 처리해야 한다.

Trade-off

설정이 복잡하고 filter order를 모르면 디버깅이 어렵다.

Alternative

NextAuth 같은 web 중심 auth, Supabase Auth 같은 managed auth, custom middleware 방식이 대안이다.

Terms you must know

authentication = 누구인지 확인
authorization = 무엇을 할 수 있는지 확인
filter chain = request가 여러 검문소를 통과하는 구조

Where

SecurityConfig, JwtAuthenticationFilter

Beginner trap

로그인만 구현하면 authorization이 끝난다고 생각하면 안 된다.

9. SecurityCore

JWT

로그인 사용자를 증명하는 서명된 토큰이다.

JWT gives web and mobile a common stateless authentication mechanism, with token_version for revocation.

What it does

client가 Authorization header로 보내고 backend가 signature와 claims를 검증한다.

Why this stack

모바일/웹이 같은 API를 쓰기 쉽고, 서버가 session table을 매 요청 조회하지 않아도 된다.

Trade-off

탈취되면 만료 전까지 위험하다. token_version, short expiry, secure storage가 필요하다.

Alternative

server-side session은 즉시 revoke가 쉽고, opaque token은 정보 노출이 적지만 조회가 필요하다.

Terms you must know

claim = 토큰 안의 정보 조각
signature = 위변조를 막는 서명
stateless = 서버가 세션 상태를 많이 들고 있지 않는 방식

Where

JwtTokenProvider, JwtAuthenticationFilter

Beginner trap

JWT payload는 암호화가 아니라 base64url 인코딩일 뿐이다.

9. SecurityCore

BCrypt

비밀번호를 안전하게 hash하는 알고리즘이다.

BCrypt protects stored passwords by hashing them with salt and a configurable work factor.

What it does

원문 password를 저장하지 않고 salt와 cost가 있는 hash를 저장한다.

Why this stack

DB가 유출돼도 원문 password를 바로 알 수 없게 만든다.

Trade-off

cost가 너무 낮으면 약하고 너무 높으면 login latency와 CPU 부하가 커진다.

Alternative

Argon2는 memory-hard라 더 현대적이고, PBKDF2는 표준성이 강하다.

Terms you must know

hash = 원문으로 되돌리기 어려운 변환
salt = 같은 password도 다른 hash가 되게 하는 랜덤값
cost = 계산을 일부러 느리게 만드는 강도

Where

AuthService, User passwordHash

Beginner trap

password를 암호화해서 복호화한다고 말하면 틀린 표현이다.

9. SecurityCore

token_version revocation

이미 발급된 JWT를 무효화하는 버전 값이다.

The token_version claim lets the backend reject old JWTs after password or account security changes.

What it does

사용자 row의 token_version과 JWT claim이 다르면 요청을 거절한다.

Why this stack

JWT는 stateless라 기본적으로 즉시 revoke가 어렵기 때문에 DB check를 섞은 현실적 장치다.

Trade-off

매 요청 DB 조회 비용이 있다. cache나 short-lived access token과 조합할 수 있다.

Alternative

refresh token rotation, session table, blacklist cache가 대안이다.

Terms you must know

revocation = 권한을 취소하는 것
claim mismatch = 토큰 내용과 서버 상태가 안 맞음
blacklist = 폐기 토큰 목록

Where

users.token_version, JwtAuthenticationFilter

Beginner trap

JWT만 쓰면 logout/revoke 문제가 자동으로 해결된다고 말하지 말라.

9. SecurityCore

Rate limiting

요청 횟수를 제한하는 보호 장치다.

Rate limiting protects costly AI paths and sensitive auth endpoints from abuse and accidental loops.

What it does

auth 시도나 AI composition 같은 비싼/위험한 API를 사용자별로 제한한다.

Why this stack

비용 폭주, brute force, accidental spam을 막는 기본 운영 장치다.

Trade-off

in-memory limit는 서버가 여러 대면 일관성이 깨진다.

Alternative

Redis 기반 rate limiter, API gateway/WAF, provider quota가 대안/보완책이다.

Terms you must know

rate limit = 일정 시간에 허용하는 요청 수
brute force = 비밀번호 등을 반복 시도하는 공격
quota = 사용 한도

Where

Auth rate limit, ComposeRateLimitInterceptor

Beginner trap

rate limit만으로 abuse 방어가 끝난다고 말하지 말라.

11. Testing

11. TestingCore

JUnit, Testcontainers, Vitest, Playwright

backend/frontend/e2e 검증 도구들이다.

The test stack is layered: unit tests for logic, integration tests for database behavior, and e2e tests for user flows.

What it does

Spring service/API는 JUnit, DB integration은 Testcontainers, UI/shared logic은 Vitest, browser flow는 Playwright로 검증한다.

Why this stack

계층별 위험이 달라서 테스트 도구도 다르게 쓴다.

Trade-off

테스트가 많아질수록 느려지고 flaky test 관리가 필요하다.

Alternative

수동 QA는 빠른 확인에는 좋지만 회귀 방지가 약하고, Cypress는 e2e 대안이다.

Terms you must know

unit test = 작은 함수/서비스 테스트
integration test = DB/API 등 실제 의존성 포함 테스트
e2e = 사용자 흐름 전체 테스트

Where

backend tests, frontend tests, e2e

Beginner trap

테스트 도구 이름만 나열하지 말고 어떤 위험을 잡는지 말해야 한다.

12. Ops

12. OpsCore

Actuator + Micrometer + Prometheus

상태와 metric을 보는 운영 계층이다.

Metrics make AI latency and provider failure observable instead of relying only on logs.

What it does

health endpoint와 AI analysis latency/failure metric을 노출한다.

Why this stack

면접에서는 기능보다 장애 시 원인을 찾는 능력이 중요해서 observability가 필요하다.

Trade-off

metric만 있고 alert/dashboard가 없으면 반쪽이다.

Alternative

OpenTelemetry, Datadog, Grafana Cloud, CloudWatch가 대안/확장이다.

Terms you must know

metric = 숫자로 남기는 상태
p95/p99 = 느린 요청 상위 percentile latency
alert = 조건이 나빠지면 알리는 규칙

Where

spring-boot-starter-actuator, micrometer-registry-prometheus

Beginner trap

Prometheus endpoint가 있다고 운영 체계가 완성된 건 아니다.

12. OpsCore

Structured JSON logging

로그를 기계가 읽기 쉽게 남기는 방식이다.

Structured logs help tie user actions, requests, and failures together during incident analysis.

What it does

request id, user id, error, latency 같은 필드를 JSON으로 기록한다.

Why this stack

장애 분석과 correlation이 쉬워지고 container/cloud logging과 잘 맞는다.

Trade-off

PII/secret이 로그에 새면 위험하다. redaction이 필요하다.

Alternative

plain text log는 사람이 읽기 쉽고, OpenTelemetry trace는 request 흐름 분석에 더 강하다.

Terms you must know

structured log = key/value 필드가 있는 로그
correlation id = 여러 로그를 한 요청으로 묶는 id
redaction = 민감값 제거

Where

logstash-logback-encoder, RequestLoggingFilter

Beginner trap

로그를 많이 남기는 것과 안전하게 남기는 것은 다르다.

Start from zero path

이 순서대로 말하면 제품 목적에서 infra 한계까지 끊기지 않는다.

steps

Product loop

Mimi를 기능 나열이 아니라 loop로 설명한다.

유튜브 입력을 클립으로 자르고 AI 설명과 SRS/녹음으로 output practice까지 연결하는 앱이다.

Mimi turns YouTube input into repeatable English output practice: clip, analyze, record, review, repeat.

Mimi productFriction removalFull system

Code focus: README.md product walkthrough

Repo map

frontend/backend/mobile/packages/infra의 역할을 한 번에 말한다.

웹은 Next, 모바일은 Expo, 백엔드는 Spring, 공통 학습 로직은 packages/core, 배포는 infrastructure에 있다.

The repo is split into web, mobile, backend, shared core, and infrastructure.

Next.jsExpo RouterSpring BootShared TypeScript core

Code focus: root package.json + folder tree

Language choices

왜 Java/TypeScript/SQL/Docker인지 말한다.

서버 트랜잭션/보안은 Java/Spring, 클라이언트와 shared content는 TypeScript, schema는 SQL migration, 실행 재현성은 Docker다.

Java owns the transactional backend, TypeScript owns client and shared learning logic, SQL owns schema, and Docker owns runtime packaging.

Java 21TypeScriptSQL + FlywayDocker

Code focus: backend/build.gradle.kts, frontend/package.json, mobile/package.json

Backend domains

도메인 패키지 11개를 책임 중심으로 설명한다.

하나의 Spring 앱이지만 auth/video/clip/analysis/recording/review/practice/deck/library/billing/common으로 기능 경계를 나눴다.

It is a modular monolith: one backend deployment, split internally by feature domains.

Modular monolithFeature-sliced packagesAuth domainClip domainAnalysis domain

Code focus: backend/src/main/java/com/tubeshadow/*

Data model

users/videos/clips/analyses/review/practice/library 관계를 그린다.

videos는 전역 캐시고, user별 소유는 clips/library_videos/review/practice rows로 표현한다.

The database combines relational ownership with JSONB for transcripts and AI results.

PostgreSQLGlobal video cachePostgres JSONBFlyway migrations

Code focus: V1-V20 migration files

Video import

YouTube import가 왜 복잡한지 설명한다.

서버는 datacenter IP와 token 문제를 만나므로 yt-dlp/POToken/Supadata를 쓰고, 모바일은 폰 IP로 직접 caption을 가져온다.

Transcript import has both a server path and a device path because YouTube blocks or changes server-side caption access.

yt-dlp transcript pathPOToken sidecarDevice WebView transcriptRace-safe import

Code focus: VideoImportService + YoutubeTranscriptClient + mobile WebView

Clip to AI

가장 중요한 비동기 AI 파이프라인을 화이트보드로 설명한다.

클립 저장은 먼저 커밋하고, AI 호출은 트랜잭션 밖 @Async 스레드에서 실행해 DB 커넥션을 묶지 않는다.

I commit the clip first, then run the slow AI call after commit, on a background thread, outside the transaction.

Async AI pipelineConnection pool protectionPENDING READY FAILEDSpring self proxy

Code focus: ClipService + ClipAnalysisService

AI provider fallback

vendor independence와 cost control을 말한다.

호출부는 interface만 알고, Composite가 Gemini/OpenAI/Claude를 설정 순서대로 시도한다.

The backend depends on one AI interface; the composite implementation handles provider order and fallback.

AiAnalysisClient interfaceCompositeAiClientAI JSON parsingCost control

Code focus: CompositeAiClient + provider clients

Learning engines

SM-2와 Leitner를 왜 나눴는지 말한다.

클립 리뷰는 0-5 품질 신호라 SM-2, 데일리 드릴은 binary라 Leitner를 쓴다.

Clip review uses SM-2, while binary daily drills use Leitner boxes.

Two SRS enginesSM-2Practice drills Leitner

Code focus: Sm2Calculator + PracticeCard + practice-srs.ts

Security

JWT, ownership, rate limit, private recordings를 묶어 설명한다.

JWT는 token_version으로 revoke하고, 모든 user resource는 userId로 걸러 읽고, 녹음은 public URL 없이 백엔드가 stream한다.

Security is built around JWT with token-version revocation, user-scoped queries, rate limits, and private recording streams.

JWT token versionOwnership queriesAI per-user rate limitPrivate recording stream

Code focus: security + recording packages

Frontend and mobile

웹과 모바일이 같은 loop를 다른 플랫폼에 맞춘다는 점을 설명한다.

웹은 편집/관리와 풍부한 화면, 모바일은 walking/recording/device transcript에 강하다.

Web and mobile share the product loop, but mobile adds native recording and device-side transcript fetching.

Next.jsTanStack QueryExpo mobile appWeb/mobile parityExpo audio

Code focus: frontend/app + mobile/src/app + packages/core

Infra and limits

배포 구조와 한계를 정직하게 말한다.

웹은 Vercel, 백엔드는 container path가 있고, AWS managed 경로와 NCP 저비용 경로의 tradeoff를 구분한다.

The deployment story has tradeoffs: managed AWS is more resilient; a Seoul NCP box is cheaper and lower latency but less HA.

Vercel web deploymentAWS ECS Fargate pathNCP Seoul boxCaddyHonest limits

Code focus: infrastructure + docker-compose + runbooks

Architecture layers

각 layer는 “무엇을 하고, 왜 그 기술인지”까지 같이 봐야 한다.

Learner product surface

The user imports videos, clips lines, records, reviews, and drills weak English patterns.

사용자가 보는 제품이다. 유튜브 영상 가져오기, 구간 자르기, 쉐도잉, 녹음 비교, 복습, 문장 훈련을 한다.

Why: 웹과 모바일을 같이 둔 이유는 사용 맥락이 다르기 때문이다. 웹은 편집/관리, 모바일은 걷거나 침대에서 반복 훈련에 맞다.

libraryimportplayerreview

frontend/app/[locale]/(app), mobile/src/app

Next.js web app

Browser UI with SSR-capable routing, locale paths, and rich training screens.

브라우저용 UI다. 로그인, 라이브러리, 클립 플레이어, 분석 패널, 복습/훈련 화면을 제공한다.

Why: Next.js는 라우팅, 배포, i18n, React 기반 UI를 빠르게 묶기 좋다. Vercel 배포와도 자연스럽다.

App Routernext-intlTanStack QueryZustand

frontend/app, frontend/components, frontend/lib

Expo mobile app

Native training surface for phone-first shadowing, recording, and device-side YouTube transcript fetch.

폰에서 쓰는 앱이다. 탭 구조, 비디오 플레이어, 녹음, 음성 입력, WebView 자막 수집을 담당한다.

Why: Expo는 React 지식으로 iOS 앱을 빠르게 만들고 TestFlight까지 갈 수 있다. 네이티브 오디오/WebView가 필요해서 단순 웹앱보다 맞다.

expo-routerexpo-audiosecure-storereact-native-webview

mobile/src/app, mobile/src/components, mobile/src/lib

Shared TypeScript core

Static drills and pure helpers shared by web and mobile.

웹과 모바일이 같이 쓰는 순수 TS 패키지다. 패턴, 콜로케이션, preposition 자료와 SRS helper가 들어 있다.

Why: 학습 콘텐츠와 순수 로직은 플랫폼과 무관하다. 복붙을 막고 web/mobile parity를 유지하려고 shared package로 뺐다.

patternscollocationspractice-srsyoutube parser

packages/core/src

Spring Boot API

Owns auth, user data, video import, clips, AI analysis, recordings, review, practice, decks, and billing entitlements.

상태와 비즈니스 규칙의 중심이다. 사용자의 데이터, 트랜잭션, 권한, AI 호출, 저장소 경계를 책임진다.

Why: Java/Spring은 인증, 트랜잭션, JPA, async, actuator, 테스트 생태계가 강하다. 면접에서도 백엔드 설계를 설명하기 좋다.

Java 21Spring Boot 3.3Spring SecurityJPA

backend/src/main/java/com/tubeshadow

PostgreSQL data core

Stores users, videos, clips, JSONB transcripts, AI results, recordings metadata, review state, and practice state.

제품의 영속 상태다. 유저별 데이터와 전역 비디오 캐시를 저장하고, JSONB로 자막/AI 결과 같은 반구조 데이터를 담는다.

Why: 관계형 소유권/제약/트랜잭션이 필요하면서 transcript와 analysis는 JSON 구조라 Postgres + JSONB가 잘 맞는다.

Flyway migrationsunique youtube_idJSONBCHECK

backend/src/main/resources/db/migration

AI analysis pipeline

Turns clipped transcript into translation, chunk gloss, vocabulary, grammar notes, scenario, and preposition notes.

클립 저장 후 AI 설명을 만든다. 느린 provider 호출은 트랜잭션 밖 백그라운드에서 돌리고 결과만 DB에 저장한다.

Why: AI 호출은 느리고 실패할 수 있다. 그래서 event + async + status machine + cached result 구조가 필요하다.

AFTER_COMMIT@AsyncAiAnalysisClientCompositeAiClient

ClipService.java, ClipAnalysisService.java, CompositeAiClient.java

YouTube transcript ingestion

Imports metadata, dimensions, captions, and stores a global video cache.

유튜브 URL에서 영상 정보와 자막을 얻는다. 서버는 yt-dlp/POToken/Supadata를 쓰고, 모바일은 폰 WebView로 직접 자막을 가져온다.

Why: YouTube는 datacenter IP를 막을 수 있다. 서버 경로와 디바이스 경로를 둘 다 둬야 실제 서비스가 산다.

oEmbedyt-dlpPOToken sidecarSupadata fallback

VideoImportService.java, YoutubeTranscriptClient.java, mobile youtube-transcript-webview.tsx

Recording storage seam

Stores learner voice recordings through an interface: local disk in dev/NCP, S3-compatible storage when configured.

사용자 녹음 파일 저장 계층이다. DB에는 metadata만, bytes는 storage에 저장하고 백엔드가 소유권 확인 후 stream한다.

Why: 파일 bytes를 DB에 넣지 않고, storage 구현을 env로 바꿀 수 있게 분리했다. 공개 URL을 주지 않아 개인정보도 지킨다.

RecordingStorageLocalRecordingStorageS3RecordingStorageInputStreamResource

backend/src/main/java/com/tubeshadow/recording

Two SRS engines

SM-2 for clip review, Leitner for binary daily drill cards.

복습 스케줄링이다. 클립 리뷰는 Again/Hard/Good/Easy라 SM-2, 패턴 드릴은 맞음/틀림이라 Leitner를 쓴다.

Why: 채점 모양이 다르면 알고리즘도 달라야 한다. 0-5 품질 점수와 binary recall을 억지로 한 모델에 넣지 않았다.

ReviewItemSm2CalculatorPracticeCardPracticeSrsService

review, practice domain, packages/core/src/practice-srs.ts

Deployment layer

Runs web on Vercel and backend on container infrastructure; current runbook includes NCP/Caddy and older AWS ECS path.

배포 계층이다. 웹은 Vercel, 백엔드는 Docker 컨테이너로 운영한다. AWS ECS 설계와 NCP 단일 박스 전환 문서가 같이 있다.

Why: 초기에는 managed AWS가 안정적이고, 비용/한국 지연시간 때문에 NCP 단일 박스로 줄이는 선택지가 생겼다.

DockerCaddyPostgres containerpot-provider

infrastructure, Dockerfile, docker-compose, DEVOPS.md

Observability and audit trail

Request logs, user/request MDC, Actuator/Prometheus metrics, and written troubleshooting logs.

운영 중 원인을 찾기 위한 계층이다. 로그에 request/user id를 태우고, AI 지연/실패를 metric으로 남긴다.

Why: 면접에서 중요한 건 만든 기능보다 고장 났을 때 찾는 능력이다. 로그와 metric, decision log가 그 증거다.

RequestLoggingFilterMicrometerActuatordocs/troubleshooting.md

common/web, analysis/application, docs

Runtime flows

정적 구조보다 request/data flow를 설명할 수 있어야 한다.

Selected flow

Signup and authenticated API call

이메일/비밀번호로 가입하고 JWT를 받아 이후 요청마다 Authorization header로 보낸다.

1POST /api/auth/signup

2BCrypt hash saved in users

3POST /api/auth/login

4JWT issued with user id + token_version

5Frontend/mobile store token

6API call sends Bearer token

7JwtAuthenticationFilter checks signature + DB token_version

Failure checks

JWT secret must not be dev default in prod
Password change must bump token_version
User-scoped queries must use userId filters

Say it

Mimi uses stateless JWT for API auth, but it still supports revocation by checking a token_version claim against the database on every request.

Backend domains

도메인을 외우는 게 아니라 책임, 파일, 테이블, 면접 문장으로 연결해라.

auth

회원가입, 로그인, JWT 발급/검증, password hash, token-version revocation.

Auth is stateless JWT, but password change still revokes old tokens through a token_version claim checked against the DB.

Files: AuthController, AuthService, User, JwtTokenProvider, JwtAuthenticationFilter, SecurityConfig

Tables: users

video

YouTube metadata/transcript import, global video cache, curated collections.

Videos are global cache rows keyed by youtube_id, and per-user ownership is modeled separately through library/clips.

Files: VideoImportService, YoutubeTranscriptClient, YoutubeProbe, CollectionService, Video

Tables: videos, collections, collection_videos

library

사용자별 saved videos 목록. 같은 global video를 여러 유저가 자기 library에 저장.

The videos table is shared cache; library_videos is the user-specific saved-video relation and makes re-import idempotent.

Files: LibraryVideoController, LibraryVideoService, LibraryVideo

Tables: library_videos

clip

영상 구간 자르기, transcript slicing, tag/note/deck 연결, AI/review 이벤트 발행.

A clip is the user's study unit; creating it publishes a domain event that seeds review and AI analysis after commit.

Files: ClipController, ClipService, TranscriptSlicer, Clip, ClipRepository

Tables: clips

analysis

AI 분석 상태/결과 저장, provider fallback, grammar/vocab/chunk/preposition/scenario 생성.

The slow provider call is outside the DB transaction; only PENDING and READY/FAILED writes are transactional.

Files: ClipAnalysisService, ClipAnalysis, CompositeAiClient, GeminiClient, OpenAiClient, ClaudeClient

Tables: clip_analyses

recording

사용자 음성 녹음 업로드, MIME/size 검증, local/S3 저장, 소유권 기반 stream/delete.

Recordings are never public URLs; the backend verifies ownership and streams the bytes.

Files: RecordingController, RecordingService, RecordingStorage, LocalRecordingStorage, S3RecordingStorage

Tables: recordings

review

클립 기반 SM-2 복습 queue, quality grade, streak.

Clip review uses SM-2 because it has a 0-to-5 quality signal like Again/Hard/Good/Easy.

Files: ReviewController, ReviewService, ReviewItem, Sm2Calculator

Tables: review_items

practice

패턴/콜로케이션/영작/시나리오/인터뷰/전사/문장 변형 훈련과 Leitner SRS.

Daily drills use a simpler Leitner system because the grading signal is binary: got it or missed it.

Files: PracticeController, CompositionService, PracticeSrsService, TransformService, TranscriptionClient

Tables: practice_progress, practice_card, sentence_transform_set

deck

Anki식 덱 구성. 클립을 그룹화하되 deck 삭제는 clip 삭제가 아니라 Inbox로 되돌림.

A deck is organization, not ownership; deleting a deck keeps the clips by setting deck_id to null.

Files: DeckController, DeckService, Deck

Tables: decks, clips.deck_id

billing

외부 결제 플랫폼이 plan entitlement를 webhook으로 반영하는 skeleton.

Mimi does not process payments itself; it only stores entitlement state from an external billing source.

Files: BillingController, BillingService

Tables: users.plan, users.plan_valid_until, users.billing_customer_id

common

공통 응답, 예외, logging, CORS, async config, S3 config, current-user resolver.

Cross-cutting concerns live in common, but business logic stays feature-sliced by domain.

Files: ApiResponse, GlobalExceptionHandler, RequestLoggingFilter, WebMvcConfig, AsyncConfig

Tables: none

Concept cards

모르는 단어를 누르면 의미, repo 위치, 선택 이유, 영어 답변, 함정, 코드 예시가 열린다.

visible

Source map

이 페이지가 어떤 shadow-ai 문서/코드에서 왔는지 기억해라.

Product README

shadow-ai/README.md

High-level product, stack, architecture, security, testing

Interview prep

shadow-ai/INTERVIEW_PREP.md

Existing verified scripts for async AI and provider fallback

Architecture doc

shadow-ai/ARCHITECTURE.md

C4, data model, flows, failure modes, scaling

Backend source

shadow-ai/backend/src/main/java/com/tubeshadow

Actual domain/service/controller/security code

DB migrations

shadow-ai/backend/src/main/resources/db/migration

Source of truth for tables, constraints, JSONB columns

Web app

shadow-ai/frontend/app + components + lib

Next screens, API client, React Query, i18n

Mobile app

shadow-ai/mobile/src/app + components + lib

Expo screens, recording, WebView transcript, phone-first flows

Shared core

shadow-ai/packages/core/src

Shared drill content and pure helpers

Infra

shadow-ai/infrastructure + docker-compose

AWS/NCP, Caddy, pot-provider, Docker deployment shape

Troubleshooting log

shadow-ai/docs/troubleshooting.md

Real incidents, fixes, and operational learning

Reality board

말할 수 있는 것과 조심할 것

Built

Async AI pipeline

실제 코드에 AFTER_COMMIT + @Async + transaction-outside call이 있다.

in-process async라 process crash 시 durable job queue처럼 보장되진 않는다.

Next: Scale stage에서는 SQS/queue + retry state가 다음 단계다.

Built

Provider fallback

Gemini/OpenAI/Claude clients and CompositeAiClient가 있다.

provider별 output schema drift와 parse failure는 계속 관리해야 한다.

Next: Schema validation/eval corpus를 붙이면 더 단단하다.

Built

Mobile app

Expo app, tabs, recording, WebView transcript path가 있다.

dirty worktree에 최근 모바일 수정이 많아서 release 상태는 별도 확인이 필요하다.

Next: TestFlight/App Store status를 실제 계정 기준으로 확인한다.

Partial

Infra story

AWS Terraform/ECS path와 NCP migration path가 같이 문서화돼 있다.

현재 운영 위치를 면접에서 혼동하면 큰 실수다.

Next: 현재 live deployment source of truth를 별도 operational card로 고정한다.

Partial

Billing

plan entitlement skeleton은 있으나 full payment processing은 아니다.

Stripe/Apple IAP complete처럼 말하면 거짓말이다.

Next: 실제 billing provider 연결 전까지 entitlement skeleton이라고 말한다.

Risk

High availability

NCP 단일박스 구조는 비용/latency tradeoff다.

VM 하나가 죽으면 서비스가 죽는 SPOF다.

Next: managed DB, backups, health checks, multi-instance로 진화시킨다.

Risk

YouTube transcript brittleness

yt-dlp/POToken/device path로 현실적인 우회를 둔다.

YouTube 내부 구조/API가 바뀌면 깨질 수 있다.

Next: fallback provider, caching, runbook을 계속 유지한다.

Built

Tests

JUnit/Testcontainers, Vitest, Playwright가 있다.

현재 dirty mobile changes에 대해 최신 test pass 여부는 별도 실행해야 한다.

Next: 변경 후 backend/frontend/mobile/e2e를 각각 검증한다.