Skip to content

Commit 2dda195

Browse files
gracefullightgracefullight
committed
docs: add WHY documents explaining tech stack choices
1 parent 16cdd74 commit 2dda195

2 files changed

Lines changed: 368 additions & 0 deletions

File tree

‎docs/WHY.ko.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# 왜 이 기술 스택인가?
2+
3+
[English](./WHY.md) | [한국어](./WHY.ko.md)
4+
5+
이 문서는 풀스택 스타터 템플릿의 각 기술 선택에 대한 이유를 설명합니다.
6+
7+
## 프론트엔드
8+
9+
### Next.js 16 + React 19
10+
11+
- **서버 컴포넌트**: 클라이언트 JavaScript 번들 감소, 초기 로딩 시간 개선
12+
- **App Router**: 레이아웃, 로딩 상태, 에러 바운더리가 내장된 파일 기반 라우팅
13+
- **Turbopack**: Webpack 대비 빠른 개발 서버 및 빌드
14+
- **React 19**: Concurrent 기능, Actions, `use()` 훅으로 성능 향상
15+
16+
### TailwindCSS v4
17+
18+
- **제로 런타임**: 모든 스타일이 빌드 시점에 컴파일
19+
- **Lightning CSS**: PostCSS 기반 v3 대비 100배 빠름
20+
- **CSS 우선 설정**: JavaScript 설정 대신 네이티브 CSS 문법
21+
- **작은 번들**: 사용하지 않는 스타일 자동 제거
22+
23+
### shadcn/ui
24+
25+
- **복사-붙여넣기 컴포넌트**: npm 의존성 없음, 코드 완전 소유
26+
- **Radix 기반**: 기본적으로 접근성 지원 (ARIA, 키보드 내비게이션)
27+
- **Tailwind 네이티브**: 프로젝트 스타일링 방식과 일관성
28+
- **커스터마이징 용이**: 디자인 시스템과 싸우지 않고 쉽게 수정
29+
30+
### TanStack Query
31+
32+
- **자동 캐싱**: 중복 제거, 백그라운드 리페치, stale-while-revalidate
33+
- **DevTools**: 디버깅용 내장 쿼리 인스펙터
34+
- **프레임워크 독립적**: React Native에서도 동일한 멘탈 모델
35+
- **Optimistic updates**: 반응형 UI를 위한 1급 지원
36+
37+
### Jotai
38+
39+
- **원자적 상태**: 보일러플레이트 없음, 아톰과 파생 아톰만
40+
- **TypeScript 우선**: 뛰어난 타입 추론
41+
- **경량**: ~3KB, 기본 사용에 프로바이더 불필요
42+
- **Suspense 지원**: React concurrent 기능과 완벽 호환
43+
44+
## 백엔드
45+
46+
### FastAPI
47+
48+
- **AI/ML 생태계**: Python AI 라이브러리 직접 접근 (LangChain, Transformers 등)
49+
- **Async 우선**: Starlette 기반, 네이티브 async/await 지원
50+
- **자동 생성 문서**: OpenAPI (Swagger)와 ReDoc 기본 제공
51+
- **Pydantic 검증**: 타입 힌트를 통한 요청/응답 검증
52+
- **확장성**: 상태 비저장 설계로 쉬운 수평 확장
53+
54+
### SQLAlchemy (async)
55+
56+
- **ORM 유연성**: 필요하면 raw SQL, 편할 때는 ORM
57+
- **Async 지원**: asyncpg 드라이버로 네이티브 asyncio
58+
- **마이그레이션 친화적**: 스키마 버전 관리를 위한 Alembic 통합
59+
- **성숙한 생태계**: 수십 년간 프로덕션에서 검증됨
60+
61+
### PostgreSQL 16
62+
63+
- **ACID 준수**: 데이터 무결성 보장
64+
- **JSON 지원**: 유연한 반정형 데이터를 위한 JSONB
65+
- **벡터 확장**: AI 임베딩과 유사도 검색을 위한 pgvector
66+
- **성능**: 고급 쿼리 플래너, 병렬 쿼리, 파티셔닝
67+
- **확장 기능**: PostGIS, 전문 검색 내장
68+
69+
### Redis 7
70+
71+
- **밀리초 미만 지연**: 인메모리 데이터 구조 저장소
72+
- **다목적**: 캐시, 세션 저장소, pub/sub, 속도 제한
73+
- **영속성 옵션**: 내구성을 위한 RDB 스냅샷 또는 AOF
74+
- **클러스터 지원**: 필요시 수평 확장
75+
76+
## 모바일
77+
78+
### Flutter 3.38
79+
80+
- **전자정부 표준프레임워크 v5**: 한국 전자정부 표준프레임워크 공식 모바일 프레임워크로 선정
81+
- **유연한 버전 관리**: 프로젝트별 Flutter/Dart 버전 고정 및 업그레이드 용이
82+
- **핫 리로드**: 개발 중 1초 미만의 UI 반복
83+
- **네이티브 성능**: ARM으로 컴파일, JavaScript 브릿지 없음
84+
85+
### Riverpod 3
86+
87+
- **컴파일 안전**: 컴파일 시점에 의존성 검사
88+
- **테스트 용이**: 격리된 상태로 쉽게 목킹 및 테스트
89+
- **Context 불필요**: BuildContext 없이 어디서나 상태 접근
90+
- **코드 생성**: riverpod_generator로 보일러플레이트 감소
91+
92+
### go_router 17
93+
94+
- **선언적 라우팅**: 웹처럼 URL 기반 내비게이션
95+
- **딥링크**: iOS/Android에서 바로 작동
96+
- **타입 안전**: 코드 생성된 라우트 파라미터
97+
- **중첩 내비게이션**: 하단 내비, 탭을 위한 Shell 라우트
98+
99+
### Forui
100+
101+
- **Flutter용 shadcn/ui**: 웹(shadcn/ui)과 일관된 디자인 언어
102+
- **커스터마이징 가능**: Tailwind 스타일 토큰 시스템으로 테마 적용
103+
- **접근성**: 모바일용 ARIA 동등 시맨틱
104+
- **경량**: 무거운 의존성 없이 위젯만
105+
106+
### Firebase Crashlytics
107+
108+
- **실시간 크래시 리포팅**: 프로덕션 이슈 즉시 확인
109+
- **브레드크럼**: 크래시로 이어진 사용자 행동
110+
- **스택 난독화 해제**: Flutter용 읽기 쉬운 스택 트레이스
111+
- **무료 티어**: 대부분의 앱에 충분한 한도
112+
113+
### Fastlane
114+
115+
- **자동화된 릴리스**: 한 명령으로 빌드, 서명, 배포
116+
- **크로스플랫폼**: 같은 워크플로우로 iOS와 Android
117+
- **CI 통합**: GitHub Actions와 완벽 호환
118+
- **메타데이터 관리**: 스크린샷, 설명, 변경 로그
119+
120+
## 인프라
121+
122+
### Terraform
123+
124+
- **Infrastructure as Code**: 버전 관리, 리뷰 가능한 인프라 변경
125+
- **선언적**: 원하는 상태를 기술하면 Terraform이 처리
126+
- **상태 관리**: 배포된 것 추적, 적용 전 계획
127+
- **모듈**: 재사용 가능하고 공유 가능한 인프라 컴포넌트
128+
129+
### GCP (Cloud Run, Cloud SQL, Cloud Storage)
130+
131+
- **넉넉한 무료 크레딧**: 신규 계정 $300 크레딧, 다수 서비스 상시 무료 티어
132+
- **서버리스 컨테이너**: 서버 관리 없음, 제로로 스케일
133+
- **사용량 기반 과금**: 요청 처리 시에만 과금
134+
- **관리형 데이터베이스**: 자동 백업, HA, 유지보수
135+
- **글로벌 CDN**: 정적 자산 및 API 캐싱용 Cloud CDN
136+
137+
### GitHub Actions + Workload Identity Federation
138+
139+
- **키리스 배포**: 관리하거나 교체할 서비스 계정 키 없음
140+
- **네이티브 GitHub 통합**: push, PR, 스케줄에 트리거
141+
- **매트릭스 빌드**: 버전/플랫폼별 병렬 테스트
142+
- **마켓플레이스**: 수천 개의 커뮤니티 액션
143+
144+
## 개발자 경험
145+
146+
### Rust 기반 툴체인
147+
148+
**속도**를 위해 전체 개발 워크플로우에서 Rust 기반 도구를 선택:
149+
150+
- **Biome**: 린터 + 포매터 통합, ESLint + Prettier 대비 100배 빠름
151+
- **uv**: Python 패키지 매니저, pip/poetry 대비 10-100배 빠름
152+
- **Turbopack**: Next.js 번들러, Webpack보다 빠름
153+
- **Lightning CSS**: TailwindCSS v4 컴파일러, PostCSS 대비 100배 빠름
154+
155+
### mise
156+
157+
- **폴리글랏 모노레포 지원**: Node, Python, Flutter, Terraform — 다른 생태계를 하나의 도구로
158+
- **프로젝트 로컬 버전**: `.mise.toml`로 모든 런타임에서 팀 일관성 보장
159+
- **태스크 러너**: Makefile, npm scripts, shell scripts를 통합된 `mise` 명령어로 대체
160+
- **Rust로 작성**: 즉각적인 도구 전환, 시작 오버헤드 없음
161+
162+
### 폴리글랏 모노레포
163+
164+
- **단일 저장소**: Web (TypeScript), API (Python), Mobile (Dart), Infra (HCL)를 한 곳에
165+
- **바운디드 컨텍스트**: 각 언어 생태계는 해당 디렉토리로 스코프가 제한되어 상호 오염 방지
166+
- **원자적 변경**: 프론트엔드 + 백엔드 변경을 단일 PR로
167+
- **통합 도구**: 모든 앱에 동일한 `mise` 명령어
168+
169+
## 트레이드오프
170+
171+
| 선택 | 트레이드오프 | 수용하는 이유 |
172+
|------|-------------|--------------|
173+
| Remix/SvelteKit 대신 Next.js | 더 큰 번들, 더 많은 복잡성 | 생태계, React 19 호환성 |
174+
| Node.js 대신 FastAPI | 두 개의 런타임 (Node + Python) | Python AI/ML 생태계, 확장성 |
175+
| React Native 대신 Flutter | 더 큰 앱 크기, 커스텀 렌더링 | 전자정부 표준프레임워크 v5, 유연한 버전 관리 |
176+
177+
## 요약
178+
179+
이 스택이 최적화하는 것:
180+
181+
1. **개발자 속도**: 핫 리로드, 타입 안전성, 자동 생성 클라이언트
182+
2. **프로덕션 준비**: 관리형 서비스, 서버리스 스케일링, CI/CD
183+
3. **팀 확장성**: 명확한 경계, 공유 도구, 문서화
184+
4. **장기 유지보수성**: 검증된 기술, 활발한 커뮤니티

‎docs/WHY.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Why This Tech Stack?
2+
3+
[English](./WHY.md) | [한국어](./WHY.ko.md)
4+
5+
This document explains the reasoning behind each technology choice in this fullstack starter template.
6+
7+
## Frontend
8+
9+
### Next.js 16 + React 19
10+
11+
- **Server Components**: Reduces client-side JavaScript bundle, improves initial load time
12+
- **App Router**: File-based routing with layouts, loading states, and error boundaries built-in
13+
- **Turbopack**: Faster dev server and builds compared to Webpack
14+
- **React 19**: Improved performance with concurrent features, Actions, and `use()` hook
15+
16+
### TailwindCSS v4
17+
18+
- **Zero runtime**: All styles compiled at build time
19+
- **Lightning CSS**: 100x faster than PostCSS-based v3
20+
- **CSS-first config**: Native CSS syntax instead of JavaScript config
21+
- **Smaller bundles**: Automatic unused style removal
22+
23+
### shadcn/ui
24+
25+
- **Copy-paste components**: No npm dependency, full ownership of code
26+
- **Radix primitives**: Accessible by default (ARIA, keyboard navigation)
27+
- **Tailwind-native**: Consistent with project styling approach
28+
- **Customizable**: Easy to modify without fighting a design system
29+
30+
### TanStack Query
31+
32+
- **Automatic caching**: Deduplication, background refetching, stale-while-revalidate
33+
- **DevTools**: Built-in query inspector for debugging
34+
- **Framework agnostic**: Same mental model works in React Native if needed
35+
- **Optimistic updates**: First-class support for responsive UIs
36+
37+
### Jotai
38+
39+
- **Atomic state**: No boilerplate, just atoms and derived atoms
40+
- **TypeScript-first**: Excellent type inference
41+
- **Lightweight**: ~3KB, no providers required for basic usage
42+
- **Suspense-ready**: Works seamlessly with React concurrent features
43+
44+
## Backend
45+
46+
### FastAPI
47+
48+
- **AI/ML ecosystem**: Direct access to Python's AI libraries (LangChain, Transformers, etc.)
49+
- **Async-first**: Built on Starlette with native async/await support
50+
- **Auto-generated docs**: OpenAPI (Swagger) and ReDoc out of the box
51+
- **Pydantic validation**: Request/response validation with type hints
52+
- **Scalability**: Easy horizontal scaling with stateless design
53+
54+
### SQLAlchemy (async)
55+
56+
- **ORM flexibility**: Can write raw SQL when needed, ORM when convenient
57+
- **Async support**: Native asyncio with asyncpg driver
58+
- **Migration-friendly**: Alembic integration for schema versioning
59+
- **Mature ecosystem**: Battle-tested in production for decades
60+
61+
### PostgreSQL 16
62+
63+
- **ACID compliance**: Data integrity guaranteed
64+
- **JSON support**: JSONB for flexible semi-structured data
65+
- **Vector extension**: pgvector for AI embeddings and similarity search
66+
- **Performance**: Advanced query planner, parallel queries, partitioning
67+
- **Extensions**: PostGIS, full-text search built-in
68+
69+
### Redis 7
70+
71+
- **Sub-millisecond latency**: In-memory data structure store
72+
- **Versatile**: Cache, session store, pub/sub, rate limiting
73+
- **Persistence options**: RDB snapshots or AOF for durability
74+
- **Cluster support**: Horizontal scaling when needed
75+
76+
## Mobile
77+
78+
### Flutter 3.38
79+
80+
- **Korea eGovFrame v5**: Selected as the official mobile framework by Korea e-Government Standard Framework
81+
- **Flexible versioning**: Easy to pin and upgrade Flutter/Dart versions per project
82+
- **Hot reload**: Sub-second UI iteration during development
83+
- **Native performance**: Compiled to ARM, no JavaScript bridge
84+
85+
### Riverpod 3
86+
87+
- **Compile-safe**: Dependencies checked at compile time
88+
- **Testable**: Easy to mock and test in isolation
89+
- **No context required**: Access state from anywhere without BuildContext
90+
- **Code generation**: Reduces boilerplate with riverpod_generator
91+
92+
### go_router 17
93+
94+
- **Declarative routing**: URL-based navigation like web
95+
- **Deep linking**: Works out of the box for iOS/Android
96+
- **Type-safe**: Code-generated route parameters
97+
- **Nested navigation**: Shell routes for bottom nav, tabs
98+
99+
### Forui
100+
101+
- **shadcn/ui for Flutter**: Consistent design language with web (shadcn/ui)
102+
- **Customizable**: Themeable components with Tailwind-like token system
103+
- **Accessible**: ARIA-equivalent semantics for mobile
104+
- **Lightweight**: No heavy dependencies, just widgets
105+
106+
### Firebase Crashlytics
107+
108+
- **Real-time crash reporting**: Immediate visibility into production issues
109+
- **Breadcrumbs**: User actions leading to crash
110+
- **Stack deobfuscation**: Readable stack traces for Flutter
111+
- **Free tier**: Generous limits for most apps
112+
113+
### Fastlane
114+
115+
- **Automated releases**: One command to build, sign, and deploy
116+
- **Cross-platform**: iOS and Android with same workflow
117+
- **CI integration**: Works seamlessly with GitHub Actions
118+
- **Metadata management**: Screenshots, descriptions, changelogs
119+
120+
## Infrastructure
121+
122+
### Terraform
123+
124+
- **Infrastructure as Code**: Version-controlled, reviewable infra changes
125+
- **Declarative**: Describe desired state, let Terraform handle the rest
126+
- **State management**: Track what's deployed, plan before apply
127+
- **Modules**: Reusable, shareable infrastructure components
128+
129+
### GCP (Cloud Run, Cloud SQL, Cloud Storage)
130+
131+
- **Generous free tier**: $300 credit for new accounts, always-free tier for many services
132+
- **Serverless containers**: No server management, scales to zero
133+
- **Pay-per-use**: Only charged when handling requests
134+
- **Managed database**: Automated backups, HA, maintenance
135+
- **Global CDN**: Cloud CDN for static assets and API caching
136+
137+
### GitHub Actions + Workload Identity Federation
138+
139+
- **Keyless deployment**: No service account keys to manage or rotate
140+
- **Native GitHub integration**: Triggered on push, PR, scheduled
141+
- **Matrix builds**: Parallel testing across versions/platforms
142+
- **Marketplace**: Thousands of community actions
143+
144+
## Developer Experience
145+
146+
### Rust-based Toolchain
147+
148+
We prioritize **speed** across the entire development workflow by choosing Rust-based tools:
149+
150+
- **Biome**: Linter + formatter in one tool, 100x faster than ESLint + Prettier
151+
- **uv**: Python package manager, 10-100x faster than pip/poetry
152+
- **Turbopack**: Next.js bundler, faster than Webpack
153+
- **Lightning CSS**: TailwindCSS v4 compiler, 100x faster than PostCSS
154+
155+
### mise
156+
157+
- **Polyglot monorepo support**: Node, Python, Flutter, Terraform — different ecosystems, one tool
158+
- **Project-local versions**: `.mise.toml` ensures team consistency across all runtimes
159+
- **Task runner**: Replace Makefile, npm scripts, shell scripts with unified `mise` commands
160+
- **Written in Rust**: Instant tool switching, no startup overhead
161+
162+
### Polyglot Monorepo
163+
164+
- **Single repository**: Web (TypeScript), API (Python), Mobile (Dart), Infra (HCL) in one place
165+
- **Bounded contexts**: Each language ecosystem is scoped to its directory, preventing cross-contamination
166+
- **Atomic changes**: Frontend + backend changes in single PR
167+
- **Unified tooling**: Same `mise` commands across all apps
168+
169+
## Trade-offs
170+
171+
| Choice | Trade-off | Why We Accept It |
172+
|--------|-----------|------------------|
173+
| Next.js over Remix/SvelteKit | Larger bundle, more complexity | Ecosystem, React 19 compatibility |
174+
| FastAPI over Node.js | Two runtimes (Node + Python) | Python AI/ML ecosystem, scalability |
175+
| Flutter over React Native | Larger app size, custom rendering | Korea eGovFrame v5, flexible versioning |
176+
177+
## Summary
178+
179+
This stack optimizes for:
180+
181+
1. **Developer velocity**: Hot reload, type safety, auto-generated clients
182+
2. **Production readiness**: Managed services, serverless scaling, CI/CD
183+
3. **Team scalability**: Clear boundaries, shared tooling, documentation
184+
4. **Long-term maintainability**: Proven technologies, active communities

0 commit comments

Comments
 (0)