물리미 (Mulimi)

• 앱스토어 링크: 링크

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

✨ 주요 기능

• HealthKit 기반 수분 기록 및 오늘 섭취량 집계
• 로그인 후 온보딩 -> 수분 알림 권한 게이트 -> HealthKit 권한 게이트 -> 메인 화면 흐름
• 첫 안내일부터 7일간 기록 확인·루틴 저장·빠른 기록 방법 선택을 돕는 스타터 플랜
• 일일 목표량 설정 및 AI 기반 목표량 추천
• 수분 기록 히스토리, 주간 리포트, 루틴 수행률 인사이트, 루틴 액션으로 연결되는 챌린지, 루틴 관리
• 홈 화면/잠금화면 위젯과 Apple Watch 앱 지원

🛠️ 기술 스택

• Swift 6.0, SwiftUI, Swift Concurrency
• Tuist 기반 모듈형 프로젝트
• HealthKit, WidgetKit, AppIntents
• 루틴 알림은 AlarmKit, 수분 리마인더는 UserNotifications
• PostHog Analytics, PostHog Error Tracking
• iOS는 Swinject 기반 의존성 주입, Watch는 별도 조립 루트에서 직접 주입

🏗️ 아키텍처

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

• App
  • 앱 진입점, ContentView, 루트 조립
  • iOS 앱, 위젯, watch 앱 타깃 정의
  • 전역 내비게이션(AppCoordinator, AppRoute) 소유
• Presentation
  • SwiftUI View / ViewModel
  • 화면 상태, 포맷된 표시 모델, feature 소유 라우트 값
• Domain
  • Entity, UseCase, Repository 인터페이스
  • UI/로컬라이제이션 의존성이 없는 비즈니스 규칙
• Data
  • Repository 구현체, HealthKit/UserDefaults/iCloud KVS 연동
• Features
  • Account, Hydration, Routine, Challenge, HydrationReminder의 Domain / Data / Presentation 수직 모듈
  • WatchHydration은 watchOS 전용 3개 레이어
• Core
  • Analytics, Platform, CloudKit, HealthKit, Keychain 시스템 인프라
  • 기능·UI를 소유하지 않는 Mulimi* 계약과 어댑터
• Shared
  • Localization, DesignSystem, Utils
  • Persistence·PersistenceWatch는 선언만 남은 미참조 타깃이며 현재 수분 기록 경로에서 사용하지 않음
• Widget
  • 홈 화면/잠금화면 위젯과 AppIntent

전체 구조도와 타깃 의존성

• 전체 구조 및 직접 의존성 목록: 타깃별 의존성, 소스 위치, 검토 기준 커밋
• 인터랙티브 구조도 HTML: 내려받아 브라우저에서 열면 검색·확대·라이트/다크 전환 가능

그림은 주요 관계를 묶은 개요입니다. 실제 타깃 선언은 각 Project.swift, 구조 규칙은 ARCHITECTURE.md를 기준으로 합니다.

앱 흐름

SignIn
  -> Onboarding
  -> HydrationReminderPermissionGate
  -> HealthKitPermissionGate
  -> ContentView

• 루트 내비게이션은 ContentView의 단일 NavigationStack에서 관리합니다.
• 탭 간 공용 이동은 AppCoordinator와 AppRoute로 처리합니다.
• 인증 상태는 AccountPresentation의 AppSession, 전역 라우팅은 MulimiNavigation의 AppCoordinator가 담당합니다.

💾 데이터/저장소 전략

항목	현재 원본 저장소	비고
수분 섭취 기록	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/
│   │   ├── Navigation/
│   │   ├── Watch/
│   │   └── DependencyInjection/
│   ├── Core/
│   │   ├── Analytics/
│   │   ├── Platform/
│   │   ├── CloudKit/
│   │   ├── HealthKit/
│   │   └── Keychain/
│   ├── Features/
│   │   ├── Account/
│   │   ├── Challenge/
│   │   ├── Hydration/
│   │   ├── HydrationReminder/
│   │   ├── Routine/
│   │   ├── WatchHydration/
│   │   └── TestSupport/         # 공용 Mock 소스, 독립 타깃 아님
│   ├── Widget/
│   │   ├── Sources/
│   │   └── Resources/
│   └── Shared/
│       ├── DesignSystem/
│       ├── Localization/
│       ├── Persistence/
│       └── Utils/
├── Docs/
│   ├── index.md
│   ├── project-architecture-and-dependencies.md
│   ├── diagrams/              # 구조도 JSON·HTML·검증 캡처
│   ├── 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(단일 watchOS 앱), MulimiNavigation(전역 내비게이션)
• Project/Core
  • Analytics: MulimiAnalytics(분석 계약), MulimiAnalyticsData(PostHog 구현)
  • Platform: MulimiPlatform(Bundle·WidgetCenter 어댑터)
  • CloudKit: MulimiCloudKit(iCloud KVS+미러 저장소, iOS·watchOS)
  • HealthKit: MulimiHealthKit(HealthKit quantity 저장소, iOS·watchOS)
  • Keychain: MulimiKeychain(String 키 Keychain 저장소)
• Project/Features/Account, Hydration, Routine, Challenge, HydrationReminder
  • 각 기능의 <Feature>Domain, <Feature>Data, <Feature>Presentation
• Project/Features/WatchHydration
  • WatchHydrationDomain, WatchHydrationData, WatchHydrationPresentation
  • HydrationServing, HydrationWriteResult, HydrationNextActionGuide 소스를 앱 수분 기능과 공유해 별도 컴파일하며 HydrationDomain 타깃에는 의존하지 않음
• Project/App/DependencyInjection
  • DependencyInjection, DependencyInjectionPreview, DependencyInjectionTesting, 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로 설정
• PostHog 이벤트를 검증하려면 POSTHOG_PROJECT_TOKEN과 POSTHOG_HOST를 설정
• 유효한 PostHog 설정이 없는 로컬·Debug 빌드는 NoOpAnalyticsRepository로 동작
• Xcode Cloud Release archive는 시작 전에 PostHog 필수 설정을 검증

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

tuist install
tuist generate

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

개발용 명령

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

코드 지식 그래프

저장소에는 Codex용 Graphify 스킬과 공유 지식 그래프가 포함됩니다.

uv tool install graphifyy
graphify query "LogWaterAppIntent DrinkWaterUseCase"

Codex에서는 $graphify로 그래프를 생성하거나 조회할 수 있습니다. 분석 범위는 .graphifyignore, 공유 산출물은 graphify-out/에서 관리합니다.

CLI 조회에는 실제 심볼·문서 이름을 사용합니다. Codex 스킬은 질문을 그래프에 있는 어휘로 확장해 조회합니다.

공유 그래프와 라벨 정보는 Git으로 관리하고, graphify-out/의 HTML·캐시·날짜별 백업·세션 기록은 로컬에만 둡니다. 배포용 구조도인 Docs/diagrams/와는 관리 범위가 다릅니다. 자세한 구분은 Graphify 산출물 관리와 구조도 산출물 관리를 따릅니다.

📖 문서 읽기 순서

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

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