Project Report: financial
Analysis Context
- Agent: Claude Code (claude-opus-4-6)
- Project: 개인 금융 관리 웹 앱
- Privacy level: Anonymized (비공개 프로젝트)
- Commits reviewed: 30+ (최근 6개월)
- Sessions analyzed: 87
- Period: 2025-09 ~ 2026-03
- Confidence: High
Project Overview
개인 자산, 투자, 대출, 보험, 거래 내역을 통합 관리하는 금융 대시보드 웹 앱입니다. 자산 그룹화, 계좌별 스냅샷과 거래 내역 추적, AI 에이전트 연동 인터페이스를 제공합니다.
Tech Stack: Next.js, React, TypeScript, ORM, PostgreSQL (BaaS), 스키마 검증 라이브러리, E2E/단위 테스트, UI 컴포넌트 라이브러리, i18n
User's Role & Contributions
Youngsup은 이 프로젝트의 유일한 개발자이자 아키텍트입니다. 스키마 설계부터 프론트엔드 UI까지 전체 스택을 담당하며, 특히 서비스 레이어 아키텍처를 직접 설계하고 여러 단계에 걸쳐 도메인별 전환을 주도했습니다.
Technical Decisions
| Decision | Chosen Approach | Reasoning | Alternatives Considered |
|---|---|---|---|
| 데이터 접근 패턴 | Service Layer SSOT | 여러 진입점이 동일한 서비스를 호출하여 로직 중복 제거 | DB 클라이언트 직접 사용 (기존 방식) |
| ORM | 타입 안전한 ORM + 행 수준 보안 | 타입 안전성과 보안을 동시에 확보 | BaaS 클라이언트 자동 보안 |
| 스키마 관리 | 서비스 레이어에서 원천 스키마 정의 | 각 레이어가 원천 스키마에서 파생하여 단일 진실 원천 유지 | 각 레이어에서 독립 스키마 정의 |
| AI 에이전트 통합 | 도메인별 도구 + 인증 | AI 에이전트가 금융 데이터를 안전하게 조회/수정 가능 | REST API |
| 응답 타입 | 통일된 결과 타입 | 성공/실패를 일관된 타입으로 처리 | 각 액션별 자체 타입 정의 |
Notable Problem-Solving
서비스 레이어 SSOT 전환. 기존에 DB 클라이언트를 직접 사용하던 구조를 서비스 레이어 중심으로 전면 전환했습니다. 한 번에 바꾸지 않고 도메인별로 점진적으로 진행하며, 각 단계마다 서비스 함수 작성 → 도구 전환 → 액션 전환 → 페이지 전환 → 레거시 삭제의 일관된 패턴을 따랐습니다. 아키텍처 문서에 전환 현황 표를 유지하며 진행 상황을 추적했습니다.
프레임워크 경계 버그 해결. 클라이언트/서버 경계에서 서버 전용 모듈을 import할 때 발생하는 런타임 에러를 발견하고, "서버 전용 모듈은 클라이언트에서 import 금지 — 필요한 값은 로컬 상수로 복제"라는 규칙을 수립하여 프로젝트 전체에 적용했습니다.
인라인 컴포넌트 안티패턴 발견. render 함수 내부에서 컴포넌트를 정의하면 re-render마다 상태가 초기화되는 문제를 진단하고, 해결책을 적용한 뒤 규칙으로 문서화했습니다.
도메인 용어 리네이밍. 도메인 용어가 부정확하다는 판단 하에 전체 스택에 걸친 대규모 리네이밍을 수행. 설계 문서를 먼저 작성하고 영향 범위를 파악한 후 실행했습니다.
Characteristics Revealed
이 프로젝트에서 특히 드러나는 특성은 체계적 문서화를 통한 아키텍처 거버넌스입니다. 서비스 레이어 아키텍처 문서는 단순한 설명이 아니라 "이렇게 해야 한다"는 규약(contract)입니다. 함수 시그니처 규약, 에러 처리 전략, 조합 패턴까지 명시되어 있어, 이 문서를 따르면 누구든 일관된 코드를 작성할 수 있습니다.
또한 AI 에이전트 통합에 대한 선구적 접근이 눈에 띕니다. 개인 앱에 AI 에이전트 인터페이스를 내장하여 금융 데이터를 조회하고 조작할 수 있게 한 것은, "앱은 AI 에이전트의 도구가 될 수 있다"는 비전을 실현한 것입니다.
Git & GitHub Analysis
- Commit style: 한글 Conventional Commits. 메시지가 변경 내용을 정확히 설명하며, 아키텍처적 맥락을 포함
- Commit frequency: 단계별 집중 작업 패턴. 도메인별로 연속 커밋
- PR patterns: feature branch에서 작업 후 squash merge 선호. PR 제목에 변경 범위 명시
- Code quality signals: 명시적 반환 타입, 스키마 파생 구조, 서비스/어댑터 분리 등 일관된 코드 품질 기준
Summary
이 프로젝트는 Youngsup의 아키텍처 설계력이 가장 잘 드러나는 프로젝트입니다. Service Layer SSOT 패턴으로 여러 진입점을 통합하고, 이를 아키텍처 문서로 규약화한 것은 개인 프로젝트를 넘어선 엔지니어링 성숙도를 보여줍니다. 점진적 전환, 도메인별 정확한 질문, 그리고 실수를 규칙으로 전환하는 학습 패턴이 인상적이며, AI 에이전트 통합은 "앱이 AI의 도구가 되는" 미래를 먼저 구현한 사례입니다.