poster-bash/DESIGN.md

# 🏗️ POSTER-BASH - MİMARİ TASARIM BELGESİ v1.0

## Doküman Versiyonu
- **Versiyon**: 1.0
- **Tarih**: 2025-02-04
- **Durum**: Taslak (Onay Bekliyor)

---

## 1. SİSTEM GENEL BAKIŞ

### 1.1 Mimari Tarz
```
┌─────────────────────────────────────────────────────────────────┐
│                     POSTER-BASH SYSTEM                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │   SCANNER   │───▶│    IGDB     │───▶│ DOWNLOADER  │          │
│  │  Module     │    │   Module    │    │   Module    │          │
│  └─────────────┘    └─────────────┘    └─────────────┘          │
│         │                   │                   │                │
│         ▼                   ▼                   ▼                │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │     UI      │    │   CONFIG    │    │    LOG      │          │
│  │   Module    │    │   Module    │    │  Module     │          │
│  └─────────────┘    └─────────────┘    └─────────────┘          │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘
```

### 1.2 Teknoloji Yığını
| Katman | Teknoloji | Açıklama |
|--------|-----------|----------|
| **Script** | Bash 4.0+ | POSIX uyumlu |
| **HTTP Client** | curl | API istekleri |
| **JSON Parser** | jq | JSON işleme |
| **ASCII Art** | figlet/toilet | 3D logo |
| **Colors** | ANSI Escape Codes | Renkli terminal |
| **Config** | bash variable export | Ayar yönetimi |

---

## 2. MODÜLER MİMARİ

### 2.1 Modül Hiyerarşisi
```
poster-bash (Main Entry Point)
│
├── lib/core.sh              # Core utilities & shared functions
├── lib/config.sh            # Config management
├── lib/logger.sh            # Logging system
├── lib/ui.sh                # Terminal UI & colors
├── lib/scanner.sh           # Directory & ISO scanner
├── lib/igdb.sh              # IGDB API integration
├── lib/downloader.sh        # Poster download & retry logic
└── lib/auth.sh              # OAuth token management
```

### 2.2 Modül Sorumlulukları

#### 2.2.1 Main Entry Point (`poster-bash`)
```bash
Sorumluluklar:
- Başlangıç kontrolü (dependencies, config)
- 3D logo gösterimi
- Ana iş akışı koordinasyonu
- Hata yakalama ve graceful exit

Interface:
main() → init → scan → process → download → report → cleanup
```

#### 2.2.2 Core Module (`lib/core.sh`)
```bash
Sorumluluklar:
- Global değişken tanımları
- Shared utility functions
- Error codes ve exit handling
- Network connectivity check

Public Functions:
- check_dependencies()
- check_internet()
- exit_with_code()
- sanitize_filename()

Exported Variables:
- SCRIPT_VERSION="1.0.0"
- RETRY_MAX=3
- TIMEOUT_SECONDS=30
```

#### 2.2.3 Config Module (`lib/config.sh`)
```bash
Sorumluluklar:
- Config dosyası okuma/yazma
- Environment variable loading
- Validation ve defaults

Public Functions:
- config_load()
- config_save()
- config_get(key)
- config_set(key, value)

Config Structure:
~/.game-bash.conf:
  IGDB_CLIENT_ID="..."
  IGDB_CLIENT_SECRET="..."
  IGDB_ACCESS_TOKEN=""       # Auto-filled
  IGDB_TOKEN_EXPIRES=""      # Auto-filled
  PROGRESS_MODE="both"
  LOG_LEVEL="info"
  RETRY_COUNT=3
```

#### 2.2.4 Logger Module (`lib/logger.sh`)
```bash
Sorumluluklar:
- Log dosyasına yazma
- Terminal çıktısı formatlama
- Log level filtering

Public Functions:
- log_info(message)
- log_warn(message)
- log_error(message)
- log_success(message)

Log Format:
[YYYY-MM-DD HH:MM:SS] LEVEL Message

Output:
- Terminal: Colored output
- File: ~/.game-bash.log
```

#### 2.2.5 UI Module (`lib/ui.sh`)
```bash
Sorumluluklar:
- ANSI renk yönetimi
- 3D ASCII logo gösterimi
- Progress bar çizimi
- Retro efektler

Public Functions:
- ui_show_logo()
- ui_print_header(text)
- ui_show_progress(current, total, text)
- ui_color_print(color, text)

Colors:
- RED: Errors
- GREEN: Success
- YELLOW: Warnings
- BLUE: Info
- MAGENTA: Headers
- CYAN: Progress

3D Logo:
- Font: "standard" (figlet) or "future" (toilet)
- Color: Cyan with bold
```

#### 2.2.6 Scanner Module (`lib/scanner.sh`)
```bash
Sorumluluklar:
- Recursive directory scanning
- .iso dosyası tespiti
- Oyun adı çıkarımı

Public Functions:
- scanner_scan_directory(path)
- scanner_find_iso(directory)
- scanner_extract_game_name(iso_path)

Data Structure:
ISO Entry:
{
  path: "/full/path/to/game.iso",
  directory: "/full/path/to",
  name: "Game Name",
  has_poster: false
}

Return: Array of ISO entries (space-separated)
```

#### 2.2.7 IGDB Module (`lib/igdb.sh`)
```bash
Sorumluluklar:
- OAuth token yönetimi
- Oyun arama
- Cover URL retrieval

Public Functions:
- igdb_authenticate()              # Get/refresh token
- igdb_search_game(name)           # Search by name
- igdb_search_with_vr(name)        # Search with VR suffix
- igdb_get_cover_url(game_id)      # Get cover image URL

API Endpoints:
POST https://id.twitch.tv/oauth2/token
  Request:  {"client_id":"...", "client_secret":"...", "grant_type":"client_credentials"}
  Response: {"access_token":"...", "expires_in":5045603, "token_type":"bearer"}

POST https://api.igdb.com/v4/games
  Headers:  {"Authorization":"Bearer ${token}", "Client-ID":"${client_id}"}
  Body:     search "${name}"; fields name,cover;
  Response: [{"id":123, "name":"Game", "cover":456}]

POST https://api.igdb.com/v4/covers
  Headers:  {"Authorization":"Bearer ${token}", "Client-ID":"${client_id}"}
  Body:     fields url,image_id; where id=${cover_id};
  Response: [{"id":456, "image_id":"abc123", "url":"..."}]

Image URL: https://images.igdb.com/igdb/image/upload/t_cover_big/${image_id}.jpg
```

#### 2.2.8 Downloader Module (`lib/downloader.sh`)
```bash
Sorumluluklar:
- Poster indirme
- Retry logic
- Dosya kaydetme

Public Functions:
- downloader_download_poster(url, output_path)
- downloader_retry_with_backoff(url, output_path, max_retries)
- downloader_check_if_exists(output_path)

Flow:
1. Check if poster.png exists → Skip if true
2. Download with curl
3. Validate file size (> 0)
4. On failure: Retry with exponential backoff (1s, 2s, 4s)
5. After max retries: Log and skip
```

#### 2.2.9 Auth Module (`lib/auth.sh`)
```bash
Sorumluluklar:
- Token lifecycle management
- Token refresh logic
- Token validation

Public Functions:
- auth_get_token()              # Returns valid token (refresh if needed)
- auth_is_expired()             # Check if token expired
- auth_refresh()                # Refresh from API
- auth_save_token()             # Save to config

Token Flow:
1. Check config for cached token
2. Check expiration
3. If expired or missing → refresh
4. Save new token to config
```

---

## 3. VERİ AKIŞI

### 3.1 Ana Akış Diyagramı
```
┌─────────────────────────────────────────────────────────────────────┐
│                        START                                        │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│  INITIALIZATION                                                     │
│  ├─ Check dependencies (curl, jq, figlet)                          │
│  ├─ Load config from ~/.game-bash.conf                            │
│  ├─ Check internet connectivity                                    │
│  ├─ Initialize logger                                              │
│  └─ Show 3D logo                                                   │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│  AUTHENTICATION                                                     │
│  ├─ Check cached token                                             │
│  ├─ Validate expiration                                            │
│  └─ Refresh if needed                                              │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│  SCANNING                                                           │
│  ├─ Scan current directory recursively                             │
│  ├─ Find all .iso files                                            │
│  ├─ Extract game names                                             │
│  └─ Build processing list                                          │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│  PROCESSING LOOP (for each ISO)                                    │
│  ├─ Show progress: [1/15] Game Name                               │
│  ├─ Check if poster.png exists → Skip if yes                       │
│  ├─ Search IGDB for game                                           │
│  ├─ Not found? → Retry with " VR" suffix                           │
│  ├─ Get cover URL from IGDB                                        │
│  ├─ Download poster with retry (3x)                                │
│  └─ Log result (success/fail)                                      │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│  REPORT                                                             │
│  ├─ Show summary                                                   │
│  │   ├─ Total games found                                          │
│  │   ├─ Posters downloaded                                         │
│  │   ├─ Skipped (already had poster)                               │
│  │   └─ Failed                                                     │
│  └─ Final message                                                  │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        END                                          │
└─────────────────────────────────────────────────────────────────────┘
```

### 3.2 Detaylı Akış (Oyun İşleme)
```
For each ISO file:
┌──────────────────────────────────────────────────────────────────┐
│ scanner_find_iso() → Returns: /path/to/Game/Game.iso            │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│ scanner_extract_game_name() → Returns: "Game"                   │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│ downloader_check_if_exists("/path/to/Game/poster.png")          │
│   ├─ Exists? → Skip, log "Already has poster"                   │
│   └─ Not exists? → Continue                                      │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│ igdb_search_game("Game")                                         │
│   ├─ Found? → Get cover_id                                       │
│   └─ Not found? → igdb_search_game("Game VR")                    │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│ igdb_get_cover_url(cover_id)                                     │
│   ├─ Returns: https://images.igdb.com/.../image_id.jpg          │
│   └─ Not found? → Log "No cover available", skip                 │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│ downloader_retry_with_backoff(url, "/path/to/Game/poster.png", 3)│
│   ├─ Try 1: curl download                                        │
│   ├─ Fail? → Wait 1s → Try 2                                    │
│   ├─ Fail? → Wait 2s → Try 3                                    │
│   ├─ Fail? → Wait 4s → Try 4                                    │
│   └─ All fail? → Log error, skip                                 │
└──────────────────────────────────────────────────────────────────┘
```

---

## 4. API ENTEGRASYON DETAYLARI

### 4.1 IGDB API Spesifikasyonu

#### 4.1.1 OAuth Token Request
```bash
# Endpoint
POST https://id.twitch.tv/oauth2/token

# Request Parameters (application/x-www-form-urlencoded)
client_id=buyzvv6qoyzj7rmauwkfom79h7fvpx
client_secret=tivj7d6b21vqybpb4fx1oe85nffibt
grant_type=client_credentials

# Expected Response (200 OK)
{
  "access_token": "eyJhbGciOiIXVCJ9...",
  "expires_in": 5045603,
  "token_type": "bearer"
}

# Error Response (400 Bad Request)
{
  "status": 400,
  "message": "invalid client"
}
```

#### 4.1.2 Games Search
```bash
# Endpoint
POST https://api.igdb.com/v4/games

# Headers
Authorization: Bearer ${ACCESS_TOKEN}
Client-ID: buyzvv6qoyzj7rmauwkfom79h7fvpx
Accept: application/json

# Request Body (APICalc query format)
search "Cyberpunk 2077";
fields name,cover;
limit 1;

# Expected Response (200 OK)
[
  {
    "id": 10904,
    "name": "Cyberpunk 2077",
    "cover": 12345
  }
]

# Empty Response (no results)
[]
```

#### 4.1.3 Covers Query
```bash
# Endpoint
POST https://api.igdb.com/v4/covers

# Headers (same as games)
Authorization: Bearer ${ACCESS_TOKEN}
Client-ID: buyzvv6qoyzj7rmauwkfom79h7fvpx

# Request Body
fields url,image_id;
where id = 12345;

# Expected Response
[
  {
    "id": 12345,
    "image_id": "co1abc",
    "url": "//images.igdb.com/igdb/image/upload/t_cover_big/co1abc.jpg"
  }
]

# Final Image URL
https://images.igdb.com/igdb/image/upload/t_cover_big/co1abc.jpg
```

### 4.2 Image Size Options
| Size | URL Pattern | Dimensions | Use Case |
|------|-------------|------------|----------|
| cover_small | t_cover_small | 90x128 | Thumbnails |
| cover_big | **t_cover_big** | 264x374 | **Default (our choice)** |
| screenshot_med | t_screenshot_med | 569x320 | Not used |
| screenshot_big | t_screenshot_big | 889x500 | Not used |

### 4.3 Error Handling Strategy
```bash
HTTP Code | Action
----------|--------------------------------------------------
200       | Success, process response
400       | Invalid request, check token
401       | Unauthorized, refresh token
403       | Forbidden, check client credentials
404       | Not found (no games/covers), skip with warning
429       | Rate limit, wait and retry
500+      | Server error, retry with backoff
```

---

## 5. VERİ YAPILARI

### 5.1 ISO Entry Structure
```bash
# Bash array representation (space-separated)
ISO_ENTRY_FORMAT="{path}|{directory}|{name}|{has_poster}"

# Example
"/path/to/Game/Game.iso|/path/to/Game|Game|0"

# Access pattern
IFS='|' read -r path directory name has_poster <<< "$entry"
```

### 5.2 Config Structure
```bash
# Key-value pairs in bash source file
export IGDB_CLIENT_ID="buyzvv6qoyzj7rmauwkfom79h7fvpx"
export IGDB_CLIENT_SECRET="tivj7d6b21vqybpb4fx1oe85nffibt"
export IGDB_ACCESS_TOKEN=""
export IGDB_TOKEN_EXPIRES=""
export PROGRESS_MODE="both"
export LOG_LEVEL="info"
export RETRY_COUNT=3
```

### 5.3 Summary Statistics
```bash
# Runtime statistics (stored in variables)
TOTAL_GAMES=0
DOWNLOADED=0
SKIPPED=0
FAILED=0
```

---

## 6. KULLANICI ARAYÜZÜ TASARIMI

### 6.1 Terminal Düzeni
```
┌────────────────────────────────────────────────────────────────┐
│                    ╔═══════════════════╗                       │
│                    ║   GAME POSTER    ║                       │
│                    ╚═══════════════════╝                       │
│                                                                │
│  📂 Scanning: /home/user/Games                                 │
│  🎮 Found: 15 ISO files                                        │
│                                                                │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━     │
│                                                                │
│  [1/15] Cyberpunk 2077                    [██████░░░░] 40%     │
│  ✓ Downloaded: poster.png                                     │
│                                                                │
│  [2/15] Elden Ring                        [████████░░] 53%     │
│  ℹ Already has poster, skipping...                             │
│                                                                │
│  [3/15] Unknown Game                        [███░░░░░░] 20%    │
│  ⚠ Game not found, retrying with VR suffix...                 │
│  ⚠ Not found in IGDB                                          │
│                                                                │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━     │
│                                                                │
│  📊 SUMMARY                                                    │
│  ✓ Downloaded: 12                                              │
│  ℹ Skipped: 2                                                  │
│  ✗ Failed: 1                                                   │
│                                                                │
│  📝 Log saved to: ~/.game-bash.log                            │
└────────────────────────────────────────────────────────────────┘
```

### 6.2 Renk Paleti
```bash
# ANSI Color Codes
COLOR_RESET='\033[0m'
COLOR_RED='\033[0;31m'      # Errors
COLOR_GREEN='\033[0;32m'    # Success
COLOR_YELLOW='\033[0;33m'   # Warnings
COLOR_BLUE='\033[0;34m'     # Info
COLOR_MAGENTA='\033[0;35m'  # Headers
COLOR_CYAN='\033[0;36m'     # Progress/Logo
COLOR_BOLD='\033[1m'
COLOR_DIM='\033[2m'

# Usage
echo -e "${COLOR_GREEN}✓ Success message${COLOR_RESET}"
echo -e "${COLOR_RED}✗ Error message${COLOR_RESET}"
```

### 6.3 Progress Bar Implementation
```bash
show_progress_bar() {
    local current=$1
    local total=$2
    local width=40
    local percentage=$((current * 100 / total))
    local filled=$((width * current / total))
    local empty=$((width - filled))

    printf "["
    printf "%${filled}s" | tr ' ' '█'
    printf "%${empty}s" | tr ' ' '░'
    printf "] %d%%\r" "$percentage"
}
```

---

## 7. HATA YÖNETİMİ

### 7.1 Exit Code Convention
```bash
EXIT_SUCCESS=0           # Normal exit
EXIT_ERROR_GENERAL=1     # General error
EXIT_ERROR_DEPS=2        # Missing dependencies
EXIT_ERROR_NETWORK=3     # Network error
EXIT_ERROR_AUTH=4        # Authentication failed
EXIT_ERROR_CONFIG=5      # Config error
EXIT_ERROR_API=6         # API error
```

### 7.2 Error Recovery Flow
```
Error Occurs
      │
      ▼
Check Type
      │
      ├─ Network Error → Check internet → Exit if offline
      ├─ Auth Error → Refresh token → Retry → Exit if fail
      ├─ API Error → Log warning → Skip current game → Continue
      ├─ Download Error → Retry (3x) → Log → Skip → Continue
      └─ Config Error → Show message → Exit
```

### 7.3 Graceful Degradation
```bash
# Fallback behaviors
figlet not found → Use simple echo with colors
jq not found → Fatal error (required dependency)
curl not found → Fatal error (required dependency)
Token refresh fail → Exit with auth error
Internet down → Exit with network error
```

---

## 8. PERFORMANS VE SKALABİLİTE

### 8.1 Performance Targets
| Metric | Target | Notes |
|--------|--------|-------|
| Startup time | < 2s | Logo + auth + scan |
| Per-game processing | 1-3s | API call + download |
| Memory usage | Minimal | Bash processes |
| Concurrent games | 1 | Sequential processing |

### 8.2 Optimization Strategies
```bash
1. Token Caching
   - Store in config, reuse until expired
   - Reduces auth overhead

2. Skip Existing Posters
   - Check file existence before API call
   - Saves bandwidth and time

3. Minimal Dependencies
   - Only curl, jq, figlet required
   - Fast startup, low overhead

4. Sequential Processing
   - No parallel processing (bash limitation)
   - Better error handling
```

---

## 9. GÜVENLİK

### 9.1 Security Considerations
```bash
1. Credential Protection
   - Config file: ~/.game-bash.conf (chmod 600)
   - .gitignore: Prevent git commit
   - Never log tokens/secrets

2. Input Sanitization
   - Escape game names before API call
   - Validate paths before file operations

3. File Operations
   - Check file exists before overwrite
   - Use safe temp directories

4. Network Security
   - HTTPS only for API calls
   - Validate SSL certificates
```

### 9.2 File Permissions
```bash
# Config file
chmod 600 ~/.game-bash.conf

# Script
chmod 755 poster-bash

# Library files
chmod 644 lib/*.sh
```

---

## 10. TEST STRATEJİSİ

### 10.1 Unit Test Coverage
```bash
# Test categories
1. Config Tests
   - Load valid config
   - Handle missing config
   - Save and reload

2. Scanner Tests
   - Find ISO files
   - Extract game names
   - Handle empty directories

3. IGDB Tests
   - Token refresh
   - Game search
   - Cover URL retrieval

4. Downloader Tests
   - Download success
   - Retry logic
   - File existence check

5. Logger Tests
   - All log levels
   - File writing
   - Terminal output
```

### 10.2 Integration Test Scenarios
```bash
1. End-to-End Flow
   - Multiple games
   - Mix of found/not found
   - VR suffix retry

2. Error Scenarios
   - No internet
   - Invalid credentials
   - API rate limit

3. Edge Cases
   - Special characters in game names
   - Very long directory names
   - Permission denied
```

---

## 11. DEPLOYMENT

### 11.1 Installation
```bash
# Clone or download
git clone https://github.com/user/poster-bash.git
cd poster-bash

# Make executable
chmod +x poster-bash

# Copy to PATH (optional)
sudo cp poster-bash /usr/local/bin/

# First run (creates config)
./poster-bash
```

### 11.2 Directory Structure After Install
```
~/.game-bash.conf          # User config
~/.game-bash.log           # Log file
/usr/local/bin/poster-bash # Executable (if installed)
```

---

## 12. BAKIM VE EVRİM

### 12.1 Version Strategy
```
Semantic Versioning: MAJOR.MINOR.PATCH

- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes

Current: v1.0.0
```

### 12.2 Future Enhancements
```
Planned Features:
- [ ] Parallel processing (background jobs)
- [ ] Custom poster size selection
- [ ] Multiple image sources fallback
- [ ] Interactive mode (select games manually)
- [ ] Database cache for faster lookups
- [ ] GUI mode (optional)
```

---

## 13. REFERANSLAR

### 13.1 External Documentation
- [IGDB API Documentation](https://api-docs.igdb.com/)
- [Twitch OAuth Documentation](https://dev.twitch.tv/docs/authentication/)
- [Bash Style Guide](https://google.github.io/styleguide/shellguide.html)

### 13.2 Related Documents
- `REQUIREMENTS.md` - Functional requirements
- `README.md` - User documentation (to be created)
- `CHANGELOG.md` - Version history (to be created)

---

## 14. ONAY KONTROL LİSTESİ

- [x] Modüler yapı tanımlandı
- [x] API entegrasyonu tasarlandı
- [x] Veri akışı diagramı oluşturuldu
- [x] Hata yönetimi stratejisi belirlendi
- [x] Güvenlik önlemleri tanımlandı
- [x] UI/UX tasarımı tamamlandı
- [ ] Implementasyon onayı bekliyor
- [ ] Kodlama aşamasına hazır

---

_v1.0 - 2025-02-04 | Tasarım Onayı Bekliyor_