# 아키텍처 문서

## 디렉토리 구조

```
lib/
├── main.dart                 # 앱 진입점
├── data/                     # 정적 데이터 (Config.dfm 추출)
│   ├── pq_config_data.dart
│   ├── race_data.dart
│   ├── class_data.dart
│   └── skill_data.dart
├── l10n/                     # i18n 생성 파일
└── src/
    ├── app.dart              # MaterialApp 설정
    ├── core/                 # 도메인 레이어
    │   ├── animation/        # ASCII 애니메이션
    │   ├── audio/            # 오디오 서비스
    │   ├── engine/           # 게임 로직
    │   ├── model/            # 데이터 모델
    │   ├── storage/          # 저장/로드
    │   └── util/             # 유틸리티
    ├── features/             # 프레젠테이션 레이어
    │   ├── arena/            # 아레나 화면
    │   ├── front/            # 프론트 화면
    │   ├── game/             # 게임 화면
    │   ├── hall_of_fame/     # 명예의 전당
    │   ├── new_character/    # 캐릭터 생성
    │   └── settings/         # 설정
    └── shared/               # 공통 위젯/스타일
```

## 레이어 구조 (Clean Architecture)

```
┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Screens   │  │   Widgets   │  │     Controllers     │  │
│  │  (features/)│  │  (widgets/) │  │  (game_session_     │  │
│  │             │  │             │  │   controller.dart)  │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
└─────────┼────────────────┼───────────────────┼──────────────┘
          │                │                   │
          ▼                ▼                   ▼
┌─────────────────────────────────────────────────────────────┐
│                      Domain Layer                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Models    │  │   Services  │  │      Managers       │  │
│  │  (model/)   │  │  (engine/)  │  │  (game/managers/)   │  │
│  │             │  │             │  │                     │  │
│  │ - GameState │  │ - Progress  │  │ - Statistics        │  │
│  │ - Equipment │  │ - Combat    │  │ - SpeedBoost        │  │
│  │ - Skills    │  │ - Item      │  │ - ReturnRewards     │  │
│  └─────────────┘  └─────────────┘  │ - Resurrection      │  │
│                                    │ - HallOfFame        │  │
│                                    └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
          │                │                   │
          ▼                ▼                   ▼
┌─────────────────────────────────────────────────────────────┐
│                       Data Layer                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Static     │  │   Storage   │  │     External        │  │
│  │  Data       │  │             │  │     Services        │  │
│  │  (data/)    │  │  (storage/) │  │                     │  │
│  │             │  │             │  │ - AdService         │  │
│  │ - Config    │  │ - SaveMgr   │  │ - IAPService        │  │
│  │ - Races     │  │ - HallOfFame│  │ - AudioService      │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## GameSessionController 매니저 구조

```
┌──────────────────────────────────────────────────────────────┐
│                   GameSessionController                       │
│                        (526 LOC)                             │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  핵심 책임:                                              │  │
│  │  - 게임 루프 관리 (startNew, pause, resume)             │  │
│  │  - 콜백 처리 (_onPlayerDied, _onGameComplete)          │  │
│  │  - 상태 관리 (GameState, MonetizationState)            │  │
│  └────────────────────────────────────────────────────────┘  │
│                           │                                  │
│           ┌───────────────┼───────────────┐                  │
│           ▼               ▼               ▼                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ Statistics  │  │ SpeedBoost  │  │  Return     │          │
│  │  Manager    │  │  Manager    │  │  Rewards    │          │
│  │  (140 LOC)  │  │  (190 LOC)  │  │  (180 LOC)  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│           │               │               │                  │
│           ▼               ▼               ▼                  │
│  ┌─────────────┐  ┌─────────────┐                           │
│  │Resurrection │  │ HallOfFame  │                           │
│  │  Manager    │  │  Manager    │                           │
│  │  (160 LOC)  │  │  (130 LOC)  │                           │
│  └─────────────┘  └─────────────┘                           │
└──────────────────────────────────────────────────────────────┘
```

### 매니저별 책임

| 매니저 | 파일 | 책임 |
|--------|------|------|
| `GameStatisticsManager` | `game_statistics_manager.dart` | 세션/누적 통계, 레벨업/골드/처치 추적 |
| `SpeedBoostManager` | `speed_boost_manager.dart` | 광고 배속, 버프 만료 체크 |
| `ReturnRewardsManager` | `return_rewards_manager.dart` | 복귀 보상 계산, 상자 보상 적용 |
| `ResurrectionManager` | `resurrection_manager.dart` | 일반/광고 부활, 자동부활 조건 |
| `HallOfFameManager` | `hall_of_fame_manager.dart` | 명예의 전당 등록, 테스트 캐릭터 |

## 게임 루프 흐름

```
┌─────────────┐
│  startNew() │
└──────┬──────┘
       │
       ▼
┌──────────────────┐
│   ProgressLoop   │◄──────┐
│    (50ms tick)   │       │
└────────┬─────────┘       │
         │                 │
         ▼                 │
┌──────────────────┐       │
│ ProgressService  │       │
│    .tick()       │       │
└────────┬─────────┘       │
         │                 │
    ┌────┴────┐            │
    │         │            │
    ▼         ▼            │
┌───────┐ ┌───────┐        │
│ Task  │ │ Quest │        │
│Process│ │/Plot  │        │
└───┬───┘ └───┬───┘        │
    │         │            │
    └────┬────┘            │
         │                 │
         ▼                 │
┌──────────────────┐       │
│  State Stream    │───────┘
│  → UI Update     │
└──────────────────┘
         │
         ▼
┌──────────────────┐
│   AutoSave       │
│   (30초 간격)     │
└──────────────────┘
```

## 데이터 흐름

```
User Action
     │
     ▼
┌─────────────────┐
│ GamePlayScreen  │
│   (UI Layer)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ GameSession     │
│ Controller      │
└────────┬────────┘
         │
    ┌────┴────┬────────┬────────┐
    │         │        │        │
    ▼         ▼        ▼        ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
│Progres│ │Stats  │ │Resurre│ │HallOf │
│sLoop  │ │Manager│ │ction  │ │Fame   │
└───┬───┘ └───────┘ │Manager│ │Manager│
    │               └───────┘ └───────┘
    ▼
┌─────────────────┐
│ProgressService  │
│ (Game Logic)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   GameState     │
│  (Immutable)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   SaveManager   │
│  (Persistence)  │
└─────────────────┘
```

## 원본 PQ 알고리즘 매핑

| PQ 원본 (Delphi) | 포팅 위치 |
|-----------------|----------|
| `Main.pas:MonsterTask` | `progress_service.dart:_createMonsterTask()` |
| `Main.pas:StartTimer` | `progress_loop.dart:tick()` |
| `NewGuy.pas:RerollClick` | `character_roll_service.dart` |
| `Config.dfm` 데이터 | `data/pq_config_data.dart` |