Flutter MVVM 아키텍쳐 추천(Riverpod과 Freezed)

Flutter에서 MVVM 아키텍처를 기반으로 Riverpod과 Freezed를 활용하는 폴더 구조를 추천해 드리겠습니다.

📂 Flutter MVVM + Riverpod + Freezed 아키텍처 폴더 구조

lib/
│── main.dart                     # 앱 진입점
│── app.dart                      # 앱 전체 구성 (MaterialApp)
│
├── core/                         # 공통 유틸 및 설정
│   ├── config/                   # 앱 환경설정 (API, 라우트, 상수 등)
│   │   ├── environment.dart       # 개발/운영 환경 구분
│   │   ├── app_routes.dart        # 라우팅 설정
│   │   ├── app_theme.dart         # 테마 설정
│   │   ├── constants.dart         # 앱에서 사용하는 상수
│   │   ├── logger.dart            # 로깅 유틸리티
│   │   ├── providers.dart         # 글로벌 Provider 등록
│   │   ├── dependencies.dart      # 의존성 주입 설정
│   │
│   ├── utils/                     # 공통 유틸리티
│   │   ├── date_formatter.dart     # 날짜 포맷 유틸
│   │   ├── network_checker.dart    # 네트워크 상태 확인
│   │   ├── validators.dart         # 입력값 검증
│   │
│   ├── network/                   # 네트워크 관련 설정
│   │   ├── api_client.dart         # Dio 클라이언트 설정
│   │   ├── api_endpoints.dart      # API 엔드포인트 정의
│   │   ├── api_interceptors.dart   # 인터셉터 설정
│   │
│   ├── database/                   # 로컬 DB 관련
│   │   ├── firebase_service.dart   # Firebase 연동
│   │   ├── local_storage.dart      # SharedPreferences or Hive
│
├── models/                        # 데이터 모델 (Freezed 이용)
│   ├── user_model.dart             # 사용자 모델
│   ├── post_model.dart             # 게시글 모델
│
├── repository/                     # 데이터 처리 계층
│   ├── auth_repository.dart        # 로그인/회원가입 관련 처리
│   ├── post_repository.dart        # 게시글 데이터 처리
│
├── providers/                      # Riverpod 상태 관리
│   ├── auth_provider.dart          # 로그인 상태 관리
│   ├── post_provider.dart          # 게시글 상태 관리
│   ├── theme_provider.dart         # 테마 상태 관리
│
├── features/                       # 주요 기능별 폴더 (MVVM 구조 적용)
│   ├── auth/                       # 로그인 관련 화면 및 로직
│   │   ├── data/                   # 데이터 계층
│   │   │   ├── auth_repository.dart
│   │   │   ├── auth_service.dart
│   │   ├── domain/                 # 비즈니스 로직 계층
│   │   │   ├── auth_usecase.dart
│   │   ├── presentation/           # UI 및 ViewModel
│   │   │   ├── auth_screen.dart
│   │   │   ├── auth_viewmodel.dart
│
│   ├── home/                       # 홈 화면 관련 폴더
│   │   ├── data/
│   │   ├── domain/
│   │   ├── presentation/
│
│   ├── post/                       # 게시글 관련 기능
│   │   ├── data/
│   │   ├── domain/
│   │   ├── presentation/
│
├── widgets/                        # 공통 위젯 폴더
│   ├── custom_button.dart
│   ├── custom_textfield.dart
│   ├── loading_indicator.dart
│
├── localization/                   # 다국어 지원 관련 폴더
│   ├── app_localizations.dart
│   ├── en.json
│   ├── ko.json
│
├── test/                           # 테스트 코드
│   ├── unit/                       # 유닛 테스트
│   ├── widget/                     # 위젯 테스트
│   ├── integration/                 # 통합 테스트
│
└── assets/                         # 정적 파일 저장소
    ├── images/                     # 이미지 리소스
    ├── fonts/                      # 폰트 파일
    ├── icons/                      # 아이콘 파일

---

📌 폴더 구조 설명

✅ MVVM 패턴 적용

• features/{기능} 폴더에서 data/domain/presentation로 구분하여 유지보수 용이
• data → API 및 데이터 저장소
• domain → 비즈니스 로직
• presentation → UI 및 ViewModel

✅ Riverpod 활용

• providers/ 폴더에서 전역 상태 관리
• 개별 기능(예: features/auth)에서도 독립적인 Provider 사용 가능

✅ Freezed 적용

• models/ 폴더 내에서 데이터 모델을 Freezed로 정의하여 불변성 유지
• repository/에서 API 데이터를 모델에 매핑하여 제공

✅ Firebase 연동 고려

• database/firebase_service.dart를 두어 Firebase 연동

✅ 유틸리티 및 공통 기능 분리

• core/utils/ → 날짜 포맷, 네트워크 상태 체크 등
• widgets/ → 공통 UI 위젯

✅ 테스트 구조 명확화

• test/unit → 모델 및 서비스 로직 테스트
• test/widget → UI 테스트
• test/integration → 실제 API 연동 테스트

---

🎯 이 구조의 장점

1. 확장성과 유지보수 용이 → MVVM 패턴 + 기능별 분리
2. 상태 관리 최적화 → Riverpod으로 효율적 관리
3. 데이터 모델의 안정성 → Freezed를 통한 불변 데이터 모델 적용
4. 테스트 가능성 증가 → 기능별 테스트 코드 작성 용이
5. Firebase & API 연동 최적화 → 별도의 서비스 계층 분리

---

이 폴더 구조로 시작하면 깔끔한 코드 관리 + 유지보수 용이성을 확보할 수 있습니다.