기술 스택
런타임 및 언어
| 기술 | 버전 | 용도 |
|---|---|---|
| Node.js | 20+ | 런타임 |
| TypeScript | 5.x | 언어 (strict 모드) |
| pnpm | 10+ | 패키지 매니저 |
백엔드
| 기술 | 버전 | 용도 |
|---|---|---|
| Fastify | 5.x | HTTP 서버 |
| tRPC | 11.x | 타입 안전 API 레이어 |
| TypeORM | 0.3.x | 데이터베이스 ORM |
| PostgreSQL | 16 | 기본 데이터베이스 (TimescaleDB + pgvector) |
| Redis | 7 | 캐싱 및 세션 |
| Zod | 3.x | 스키마 유효성 검사 |
| Pino | - | 구조화된 로깅 |
| JWT | - | 인증 |
| bcrypt | - | 비밀번호 해싱 |
프론트엔드
| 기술 | 버전 | 용도 |
|---|---|---|
| Alpine.js | 3.14 | 반응형 UI 프레임워크 |
| Vite | 6.x | 빌드 도구 및 개발 서버 |
| Tailwind CSS | 4.0 | 유틸리티 우선 CSS 프레임워크 |
| Capacitor | 6.x | 모바일 앱 (iOS + Android) |
| Cropper.js | 1.6 | 이미지 크롭 (직원 앱) |
인프라
| 기술 | 용도 |
|---|---|
| Docker Compose | 컨테이너 오케스트레이션 |
| pgAdmin 4 | 데이터베이스 관리 UI |
| Husky | Git 훅 |
| Biome | 2.3.x |
빌드 및 테스트
| 기술 | 용도 |
|---|---|
| Vitest | 테스트 러너 |
| Faker.js | 테스트 데이터 생성 |
| tsup | 라이브러리 번들링 (SDK, 컴포넌트) |
| Commander.js | CLI 프레임워크 |
프론트엔드 아키텍처
모든 프론트엔드 앱은 동일한 스택을 공유합니다:
Alpine.js 3.14 (반응형 컴포넌트)
+ @hereby/sdk (tRPC 클라이언트)
+ @hereby/components (인증 UI)
+ Tailwind CSS 4.0 (스타일링)
+ Vite 6.0 (빌드 + HMR)커스텀 Vite 플러그인
모든 앱은 <!-- include "path" --> 디렉티브를 처리하는 커스텀 htmlInclude() Vite 플러그인을 사용하여 모듈형 뷰/컴포넌트 템플릿 구성이 가능합니다.
SDK 통합
SDK는 Alpine.js 플러그인으로 등록되어 다음을 포함하는 $store.hereby 스토어를 생성합니다:
- 인증 상태 관리
- SDK 클라이언트 인스턴스
- 권한 확인 헬퍼
- 로그인/로그아웃 메서드
TypeScript 설정
json
{
"strict": true,
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"target": "ES2020",
"module": "ESNext"
}- Strict 모드: implicit any 금지, strict null 체크
- 데코레이터: TypeORM 엔티티에 필요
- PascalCase: 타입, 인터페이스, 클래스
- camelCase: 변수, 함수