catdoku/docs/architecture.md

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:

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:

{
  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:

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

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:

// 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