Tech Stack

기능 구현 속도보다 유지보수 가능한 구조와 교체 가능한 아키텍처를 기준으로 기술을 선택했습니다.

영역	기술
Frontend	React, TypeScript, Vite
UI	Tailwind CSS
Client State	Zustand
Server State	TanStack Query
API 통신	Axios, Zod
Backend	Node.js 22 LTS, NestJS
ORM / DB	Prisma, PostgreSQL
인증	JWT (Access + Refresh Token)
PWA	Vite PWA Plugin, Workbox, IndexedDB
배포	Docker, Nginx

Frontend Architecture

pages → features → entities → shared

계층	역할
pages	화면 조립
features	사용자 액션, API Mutation
entities	도메인 API·모델·타입
shared	공통 UI·훅·유틸·스토리지

• 역방향 의존 금지
• API 호출은 entities 계층에서만 처리, 컴포넌트 직접 호출 금지
• 서버 상태(TanStack Query)와 클라이언트 상태(Zustand) 분리 관리
• API 응답 검증은 Zod로 처리

Backend Architecture

Controller → UseCase → Repository Interface → Repository 구현 → Prisma → PostgreSQL

계층	역할
Controller	요청 수신, DTO 검증
UseCase	정책 판단, 트랜잭션 흐름 제어
Repository	데이터 접근 추상화
Infrastructure	Prisma, 암호화, 토큰 처리

• 기능 모듈: auth, transaction, account, card, category, statistics, sync
• Controller의 비즈니스 로직 처리 금지
• Prisma 직접 호출은 Repository 내부로 제한
• Prisma 모델 대신 공통 Response DTO로 응답
• 잔액 변경을 동반하는 거래 저장·수정·삭제는 DB Transaction으로 처리

Offline & Sync

대상	캐시 전략	이유
App Shell	Cache First	오프라인 실행 보장
Dashboard, 최근 거래	Network First	최신 데이터 우선
통계, 계좌·카드·카테고리	Stale While Revalidate	빠른 표시 후 백그라운드 갱신
이미지, 폰트	Cache First	변경 빈도 낮음

거래 등록·수정·삭제는 캐시 대상에서 제외하고 별도 경로로 처리합니다.

오프라인 저장 → IndexedDB → Sync Queue 등록 → 네트워크 복구 → FIFO 동기화 → 서버 반영

• 중복 방지: 클라이언트 임시 ID 기준 서버 중복 검사
• 충돌 처리: 클라이언트 변경 우선 반영, 충돌 이력 기록

Receipt OCR

영수증 촬영·사진·텍스트 붙여넣기로 거래 등록을 보조하는 기능입니다. 분석 결과는 거래 초안에만 반영되며, 거래를 직접 생성·수정하지 않습니다.

• 문자 추출(OCR)과 문자 해석(파싱)을 별도 API로 분리
• OCR: 자체 호스팅 PaddleOCR(한국어 모델), 외부 유료 OCR API 미사용
• 카메라 사진과 스크린샷에 서로 다른 전처리 적용, 신뢰도 낮으면 재분석
• 파싱: profile 기반 범용 문자 파싱 API, 영수증은 receipt-transaction profile 사용
• OCR provider는 인터페이스로 분리해 교체 가능, 프론트엔드·API 계약 유지
• 원본·변환 이미지 미저장, 오프라인 미지원

Deployment

• Frontend / Backend Docker 컨테이너 분리 배포
• Nginx: 정적 리소스 제공 + API Reverse Proxy
• 로컬 개발 · GitHub Actions · Docker build 공통 런타임: Node.js 22 LTS