# Architettura del Sistema

## Panoramica

CatDoku è un'applicazione web single-page (SPA) costruita con HTML, CSS e JavaScript vanilla. L'architettura segue un pattern MVC semplificato dove la logica di gioco, il rendering e lo stato sono separati ma comunicano attraverso funzioni ben definite.

## Struttura dei File

```
catdoku/
├── index.html          # Entry point principale
── style.css           # Foglio di stile globale
├── game.js             # Logica di gioco (IIFE)
├── leaderboard.html    # Pagina classifica (standalone)
└── docs/               # Documentazione
```

## Moduli Principali

### 1. Game State (Model)

Lo stato del gioco è gestito attraverso un oggetto `state` che contiene:

```javascript
let state = {
  size: 8,              // Dimensione griglia (6-12)
  grid: [],             // Array 2D delle celle
  solution: [],         // Array delle posizioni soluzione
  errors: 3,            // Errori rimanenti
  maxErrors: 3,         // Errori massimi
  catsPlaced: 0,        // Gatti piazzati
  totalCats: 0,         // Gatti totali (= size)
  level: 1,             // Livello corrente
  score: 0,             // Punteggio totale
  hints: 3,             // Suggerimenti rimanenti
  gameOver: false,      // Flag game over
  won: false,           // Flag vittoria
  playerName: '',       // Nome giocatore
  levelStartTime: null, // Timestamp inizio livello
  levelTime: 0,         // Tempo trascorso (secondi)
  sessionRecords: []    // Record della sessione
};
```

### 2. Grid Cell Structure

Ogni cella della griglia è un oggetto con:

```javascript
{
  color: 0-11,          // Indice colore (0-11)
  hasCat: boolean,      // Contiene un gatto?
  hasX: boolean,        // Contiene una X?
  isSolution: boolean   // È parte della soluzione?
}
```

### 3. Generator Module

Il generatore di puzzle è composto da tre funzioni principali:

#### generateSolution(size)
- **Input**: Dimensione griglia
- **Output**: Array di posizioni {row, col}
- **Algoritmo**: Backtracking randomizzato
- **Complessità**: O(n!) nel worst case, ma con pruning efficiente

#### generateColors(size, solution)
- **Input**: Dimensione griglia e soluzione
- **Output**: Griglia 2D di indici colore
- **Algoritmo**: Flood fill simultaneo BFS
- **Garantisce**: Regioni contigue e connesse

#### generatePuzzle(size)
- **Input**: Dimensione griglia
- **Output**: Oggetto {grid, solution}
- **Processo**: Combina solution + colors + stato iniziale

### 4. Validation Module

Funzioni di validazione per le regole del gioco:

```javascript
isValidPlacement(row, col) {
  // Controlla:
  // 1. Cella non ha X
  // 2. Nessun gatto nella riga
  // 3. Nessun gatto nella colonna
  // 4. Nessun gatto nello stesso colore
  // 5. Nessun gatto adiacente (8 direzioni)
}
```

### 5. UI/Rendering Module

#### renderGrid()
- Ricostruisce completamente il DOM della griglia
- Applica colori di background dalle costanti COLORS
- Aggiunge event listeners per interazioni

#### updateUI()
- Aggiorna contatori (livello, punteggio, tempo, gatti)
- Aggiorna indicatori errori (cuori)
- Aggiorna badge suggerimenti

### 6. Input Handling Module

Gestisce due tipi di interazione:

#### Mouse Events
- `mousedown`: Avvia timer per long press
- `mouseup`: Se long press non attivato → toggle X
- `mouseleave`: Cancella timer

#### Touch Events
- `touchstart`: Avvia timer per long press
- `touchend`: Se long press non attivato → toggle X
- `touchcancel`: Cancella timer

**Long press threshold**: 500ms

### 7. Timer Module

```javascript
startTimer() {
  // Avvia setInterval che aggiorna levelTime ogni secondo
}

stopTimer() {
  // Ferma il timer
}

formatTime(seconds) {
  // Converte secondi in formato mm:ss
}
```

### 8. Storage Module

Utilizza `localStorage` per persistenza:

```javascript
// Key: 'catdoku_records'
// Value: JSON array di record
{
  playerName: string,
  level: number,
  gridSize: number,
  time: number,      // secondi
  score: number,
  errors: number,
  hintsUsed: number,
  date: ISO string
}
```

## Flusso di Gioco

```
1. Avvio
   ↓
2. Input nome giocatore
   ↓
3. Selezione dimensione griglia
   ↓
4. Generazione puzzle
   ↓
5. Avvio timer
   ↓
6. Loop di gioco (input → validazione → render)
   ↓
7. Vittoria o Game Over
   ↓
8. Salvataggio record
   ↓
9. Prossimo livello o nuova partita
```

## Gestione Errori

Il sistema gestisce errori in due modi:

1. **Errori di gioco** (posizionamento invalido):
   - Decrementa contatore errori
   - Flash rosso sulla cella
   - Game Over se errori = 0

2. **Errori di sistema**:
   - Try-catch non utilizzato (codice sincrono)
   - Fallback nel generatore (se backtracking fallisce 100 volte)

## Performance Considerations

- **Rendering**: Ricostruzione completa DOM ad ogni azione (accettabile per griglie ≤12×12)
- **Generazione**: Backtracking con pruning, media <100ms per griglia 10×10
- **Storage**: localStorage è sincrono, operazioni rapide per piccoli dataset

## Security Considerations

- Nessun dato sensibile trasmesso
- localStorage è locale al browser
- No eval() o codice dinamico
- Input nome giocatore sanitizzato (trim, maxlength)

## Browser Compatibility

Testato e compatibile con:
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

Requisiti:
- ES6+ support
- CSS Grid support
- localStorage support