물리미 (Mulimi)

• 앱스토어 링크: 링크

물리미는 HealthKit 기반으로 수분 섭취를 기록하고, 목표량 관리, 루틴, 챌린지, 위젯, Apple Watch 앱까지 한 흐름으로 연결한 수분 트래커입니다.

✨ 주요 기능

• HealthKit 기반 수분 기록 및 오늘 섭취량 집계
• 로그인 후 온보딩 -> HealthKit 권한 게이트 -> 메인 화면 흐름
• 일일 목표량 설정 및 AI 기반 목표량 추천
• 수분 기록 히스토리, 주간 리포트, 루틴 수행률 인사이트, 루틴 액션으로 연결되는 챌린지, 루틴 관리
• 홈 화면/잠금화면 위젯과 Apple Watch 앱 지원

🛠️ 기술 스택

• Swift 6.0, SwiftUI, Swift Concurrency
• Tuist 기반 모듈형 프로젝트
• HealthKit, WidgetKit, AppIntents
• Firebase Analytics, Firebase Crashlytics
• Swinject 기반 의존성 주입

🏗️ 아키텍처

물리미는 Clean Architecture + MVVM 기준으로 레이어를 분리합니다.

• App
  • 앱 진입점, ContentView, 루트 조립
  • iOS 앱, 위젯, watch 앱 타깃 정의
• Presentation
  • SwiftUI View / ViewModel
  • AppCoordinator, AppSession 등 화면 상태와 라우팅
• Domain
  • Entity, UseCase, Repository 인터페이스
  • UI/로컬라이제이션 의존성이 없는 비즈니스 규칙
• Data
  • Repository 구현체, HealthKit/UserDefaults/iCloud KVS 연동
• Shared
  • DependencyInjection, Localization, DesignSystem, Persistence, Utils
• Widget
  • 홈 화면/잠금화면 위젯과 AppIntent

앱 흐름

SignIn
  -> Onboarding
  -> HealthKitPermissionGate
  -> ContentView

• 루트 내비게이션은 ContentView의 단일 NavigationStack에서 관리합니다.
• 탭 간 공용 이동은 AppCoordinator와 AppRoute로 처리합니다.
• 인증 상태는 AppSession으로 관리하고, ViewModel 간 직접 결합을 줄였습니다.

💾 데이터/저장소 전략

항목	현재 원본 저장소	비고
수분 섭취 기록	HealthKit	앱/위젯/워치가 같은 수분 기록 기준을 봅니다.
신체 정보(키/몸무게)	HealthKit	추천 기능과 프로필 화면에서 사용합니다.
목표 수분량	iCloud KVS + App Group UserDefaults 미러	같은 Apple 계정 목표량 동기화용입니다.
mainIcon	App Group UserDefaults	앱과 위젯이 같은 메인 심볼 설정을 공유합니다.
온보딩 완료 여부	UserDefaults	로컬 상태입니다.
루틴	UserDefaults(JSON)	현재는 로컬 저장 기반입니다.
챌린지 배지 이력	UserDefaults(JSON)	완료 이력 표시용입니다.

📁 프로젝트 구조

Mulimi/
├── AGENTS.md
├── ARCHITECTURE.md
├── README.md
├── Project/
│   ├── App/
│   │   ├── Sources/
│   │   └── Watch/
│   ├── Domain/
│   │   ├── Interfaces/
│   │   ├── SharedInterfaces/
│   │   ├── Sources/
│   │   ├── WatchInterfaces/
│   │   └── WatchSources/
│   ├── Data/
│   │   ├── Sources/
│   │   └── WatchSources/
│   ├── Presentation/
│   │   ├── Sources/
│   │   ├── Tests/
│   │   └── WatchSources/
│   ├── Widget/
│   │   ├── Sources/
│   │   └── Resources/
│   └── Shared/
│       ├── DependencyInjection/
│       ├── DesignSystem/
│       ├── Localization/
│       ├── Persistence/
│       └── Utils/
├── Docs/
│   ├── index.md
│   ├── harness-engineering.md
│   ├── quality-gates.md
│   ├── documentation-maintenance.md
│   ├── security-privacy.md
│   ├── delivery-workflow.md
│   ├── product-specs/
│   ├── exec-plans/
│   └── skills/
├── Tuist/
├── XCConfig/
└── ci_scripts/

대표 모듈

• Project/App
  • Mulimi, WidgetExtension, MulimiWatch, MulimiWatchExtension
• Project/Domain
  • DomainLayerInterface, DomainLayer
  • WatchDomainLayerInterface, WatchDomainLayer
  • SharedInterfaces: 앱/워치가 같은 수분 단위, next-action, 루틴 수행률 계산을 보는 공용 소스
• Project/Data
  • DataLayer, WatchDataLayer
• Project/Presentation
  • PresentationLayer, WatchPresentationLayer
• Project/Shared/DependencyInjection
  • DependencyInjection, WatchDependencyInjection

🚀 시작하기

권장: Makefile 사용

make setup TEAM_ID=YOUR_APPLE_DEVELOPER_TEAM_ID

이 명령은 아래 작업을 순서대로 수행합니다.

1. XCConfig/Secrets.xcconfig 생성
2. tuist install
3. tuist generate
4. git hooks 경로 설정

수동 설정

1. 저장소 복제

git clone https://github.com/gaeng2y/Mulimi.git
cd Mulimi

2. Tuist 설치

curl https://mise.run | sh
mise install tuist

3. 팀 설정

• XCConfig/Secrets.xcconfig.template를 복사해 XCConfig/Secrets.xcconfig 생성
• DEVELOPMENT_TEAM 값을 본인 Apple Developer Team ID로 설정

4. 의존성 설치 및 프로젝트 생성

tuist install
tuist generate

5. 생성된 Mulimi.xcworkspace를 Xcode에서 엽니다.

개발용 명령

make hooks
make lint
make lint-fix
make arch-check
make verify

📖 문서 읽기 순서

처음 저장소에 들어오거나 큰 구조 변경을 시작할 때는 아래 순서를 권장합니다.

1. AGENTS.md
2. README.md
3. ARCHITECTURE.md
4. Docs/index.md
5. 작업 대상 이슈
6. 브랜치/PR 기준이 필요하면 Docs/delivery-workflow.md
7. 관련 Docs/product-specs/
8. 관련 Docs/skills/
9. 수정 대상 모듈의 Project.swift와 실제 구현

✅ 개발 환경 메모

• iOS 26.0+, watchOS 26.0+ 타깃을 사용합니다.
• iOS 26 SDK가 포함된 Xcode가 필요합니다.
• 일부 기능은 HealthKit, iCloud, Apple Watch, WidgetKit capability 설정이 필요합니다.

📚 문서

• 문서 허브
• 하네스 엔지니어링 구조
• 품질 게이트
• 문서 유지보수 규칙
• 보안/개인정보 운영 기준
• 이슈/PR 전달 흐름
• 아키텍처 SSOT
• 제품 스펙 인덱스
• 실행 계획 템플릿
• 실행 계획 / 기술 부채
• 구현 체크리스트 모음
• 프로필 정보 구조
• 개인화 챌린지 전략
• 챌린지 상태 모델
• Xcode Cloud Release Build