2025.12.25 / JUN
사주 포켓(Saju Pocket)은 한국의 사주·명리학 이론을 현대적인 모바일 앱 형태로 구현한 MVP 프로젝트로서, 바이브코딩(Vibe Coding) 방식으로 아이디어를 빠르게 기획하고, 구현하고, 검증할 수 있도록 돕는 교육용 퍼블릭 프로젝트입니다.
Flutter를 기반으로 설계되어 iOS와 Android 플랫폼에 동시에 배포할 수 있으며, 서버나 외부 API 없이 완전 오프라인 환경에서 작동하는 구조를 채택하여 바이브코딩 입문자도 앱 빌드 및 배포 성공 확률을 높이고 앱스토어 등록과 심사 과정에서의 리스크를 줄일 수 있도록 설계된 교육용 프로젝트입니다.
깃허브 | 사주 포켓 (Saju Pocket) 프로젝트 소스코드
https://github.com/junsang-dong/vibe_1224_saju_flutter
1. 사주 포켓 프로젝트의 핵심 기능
사주 포켓은 모바일 사주 앱으로서 필요한 기본 흐름을 충실히 구현하고 있다. 온보딩 화면에서는 면책 조항과 개인정보 처리 방침에 대한 동의를 명확히 받도록 구성했다. 홈 화면에서는 사주 풀이를 바로 시작할 수 있으며, 최근에 생성한 사주 결과를 최대 3개까지 미리 확인할 수 있다.
입력 화면에서는 이름 또는 별명, 생년월일시, 성별 정보를 입력할 수 있고, 양력·음력 선택과 윤달 옵션, 생시를 모르는 경우를 위한 ‘시간 모름’ 기능도 제공한다. 또한 결과 출력 스타일을 간결, 균형, 상세 중에서 선택할 수 있도록 설계해 사용자 선호도를 반영했다.
결과 화면에서는 사주를 구성하는 네 개의 주(년·월·일·시)를 시각적으로 표시하고, 한 줄 요약과 키워드, 강점과 주의사항을 함께 제시한다. 이어서 성향, 직업·재물, 인간관계, 건강, 타이밍 노트 등 실생활과 연결되는 항목별 해석을 제공하며, 현재 결과의 신뢰도와 제한사항도 함께 명시한다. 모든 결과 하단에는 면책 문구가 항상 표시되도록 구성했다.
생성된 사주 결과는 로컬에 저장할 수 있으며, 히스토리 화면에서 목록 조회, 상세 보기, 스와이프 삭제가 가능하다. 설정 화면에서는 기본 출력 스타일 설정, 데이터 초기화, 면책 및 개인정보 처리 방침 확인, 앱 버전 정보 확인 기능을 제공한다. 공유 기능을 통해 사주 결과를 텍스트 형태로 외부 앱에 전달할 수도 있다.
2. 기술 스택과 아키텍처 설계
사주 포켓은 Flutter(stable channel)와 Dart 3를 기반으로 개발되었다. 상태 관리는 Riverpod을 사용했고, 화면 전환은 go_router를 활용해 명확한 라우팅 구조를 유지했다. 로컬 데이터 저장은 Hive를 사용하되, freezed와 json_serializable로 정의된 모델을 JSON 문자열 형태로 직렬화해 저장하는 방식을 채택했다.
프로젝트 구조는 app, core, features 단위로 명확히 분리되어 있다. core 영역에는 사주 데이터 모델, 저장소, 사주 계산 엔진 인터페이스와 구현체가 위치하고, features 영역에는 온보딩, 입력, 결과, 히스토리, 설정 등 화면 단위 기능이 분리돼 있다. 이러한 구조는 교육용 프로젝트로서 코드 가독성과 확장성을 동시에 고려한 설계다.
3. 플레이스홀더 사주 엔진의 의미
현재 사주 포켓은 실제 명리학 계산을 그대로 구현하지 않고, 결정론적(deterministic) 플레이스홀더 엔진을 사용한다. 생년월일시를 기반으로 고정된 규칙에 따라 사주 구조를 생성하며, 오행 분포, 십신, 상충 여부 등을 단순화된 방식으로 계산한다. 이는 알고리즘 검증이나 UI·UX 흐름 테스트를 목적으로 한 선택이다.
중요한 점은, 이 구조가 향후 실제 명리학 엔진으로 교체 가능하도록 인터페이스 기반으로 설계되어 있다는 점이다. FutureRealSajuEngine 스텁 파일을 통해 향후 절기 기준 음력 변환, 월주 계산, 대운·세운 로직을 단계적으로 추가할 수 있도록 여지를 남겨두었다.
4. 바이브코딩 교육용 퍼블릭 프로젝트로서의 의미
사주 포켓은 단순한 운세 앱 예제가 아니라, 아이디어 → MVP 구현 → 디버깅 → 실행 가능한 앱 구조 완성까지의 전 과정을 공개한 실전 사례다. Cursor, ChatGPT와 같은 AI 도구를 활용해 짧은 시간 안에 설계와 구현을 반복하는 바이브코딩 방식이 실제 모바일 앱 개발에 어떻게 적용될 수 있는지를 보여준다.
이 프로젝트는 Flutter 입문자, 바이브코딩 학습자, 그리고 모바일 앱 MVP를 빠르게 만들어보고 싶은 기획자·강연자·컨설턴트에게 좋은 참고 사례가 될 수 있다. 실제 명리학 정확도보다도, 제품 구조·아키텍처·MVP 완성 경험에 초점을 둔 점이 이 프로젝트의 핵심이다.
사주 포켓 프로젝트의 전체 소스 코드는 GitHub에 공개되어 있으며, 교육·연구·학습 목적으로 자유롭게 참고할 수 있다. 앞으로 이 프로젝트는 사주 카드 시각화, 목적별 리포트, AI 기반 액션 아이템 제안, 글로벌 사용자 대상 확장 등 다양한 방향으로 점진적 고도화를 실험하는 기반으로 활용될 예정이다.
사주 포켓 (Saju Pocket) – 한국의 사주, 명리학 이론에 기반한 개인 사주와 운세를 풀이해주는 Flutter 모바일 앱 프로젝트
https://github.com/junsang-dong/vibe_1224_saju_flutter
첫 포스팅: 2025.12.25 / 포스트 작성: JUN (naebon@naver.com)
