WolfDen Manager

Il Problema

Un amico gestisce una sala LAN e aveva bisogno di un sistema per monitorare i turni dei clienti alle postazioni. Il vecchio software, sviluppato in Java, era funzionale ma con un’interfaccia e un’esperienza utente spartana che rendeva l’uso quotidiano poco efficiente.

Ho deciso di fare un completo redesign e rework dell’applicazione, trasformandola in una moderna app desktop con Electron e Next.js, mantenendo tutte le funzionalità essenziali ma aggiungendo un’interfaccia intuitiva e funzionalità avanzate.

La Soluzione

WolfDen Manager è un’applicazione desktop cross-platform (Windows, macOS, Linux) costruita con Electron e Next.js 16, che permette di gestire in modo efficiente i turni dei clienti in una sala LAN. L’applicazione offre organizzazione in sezioni personalizzabili, sistema di timer avanzato con multiple modalità, shortcut da tastiera per operazioni rapide, supporto tema chiaro/scuro, e persistenza automatica dei dati in locale.

Come Funziona

L’applicazione permette di organizzare le postazioni in sezioni personalizzabili. Ogni sezione può contenere multiple postazioni, permettendo una gestione flessibile della sala. Il cuore dell’applicazione è il sistema di timer, che offre diverse modalità di gestione: timer con durata predefinita o personalizzata, timer con date/ora specifiche per impostazione precisa di inizio e fine turno, aggiunta/rimozione tempo per modifica dinamica del timer in corso, progress bar visiva con colori che cambiano in base al tempo rimanente, notifiche audio quando il timer scade, e scambio postazioni per trasferimento rapido del timer tra postazioni diverse.

Per velocizzare le operazioni quotidiane, l’applicazione supporta numerosi shortcut: Ctrl+E per attivare/disattivare modalità modifica, Ctrl+M per attivare/disattivare audio, Ctrl+1/2/3 per avviare timer o aggiungere tempo (1h, 2h, 30min) quando una card è selezionata, Ctrl+S per scambiare postazione quando timer attivo, Ctrl+R per resettare timer, e Ctrl+Scroll per aggiungere/rimuovere tempo con precisione al minuto.

Tutti i dati (sezioni, postazioni, timer attivi) vengono salvati automaticamente in locale, garantendo che nessuna informazione vada persa anche in caso di chiusura improvvisa dell’applicazione. Lo stato dell’applicazione è centralizzato in un Context Provider che gestisce sezioni e postazioni, timer attivi, e aggiornamenti in tempo reale con un singolo interval globale per ottimizzare le performance.

Le Sfide Tecniche

La gestione dello stato globale è stata una delle sfide principali. Ho implementato un Context Provider centralizzato che gestisce tutto lo stato dell’applicazione, evitando prop drilling e garantendo aggiornamenti efficienti. Per ottimizzare le performance, ho utilizzato un singolo interval globale che aggiorna tutti i timer attivi ogni secondo invece di creare un interval per ogni timer, riducendo drasticamente il consumo di risorse.

La persistenza dei dati in locale è stata implementata usando localStorage con serializzazione personalizzata per gestire strutture dati complesse come Map. Il sistema include versioning per future migrazioni e gestione degli errori per casi limite come quota exceeded. Il salvataggio è debounced a 500ms per evitare scritture eccessive durante modifiche rapide.

La gestione del tempo è stata complessa: ho implementato un sistema basato su ISO timestamps completi con supporto timezone (Europe/Rome) per gestire correttamente date e orari, incluso il crossing di mezzanotte. Il calcolo del progress è ottimizzato per mostrare la barra al 100% quando rimangono più di un’ora, poi diminuisce linearmente nell’ultima ora, e mostra valori oltre 100% quando il timer è scaduto per indicare visivamente il ritardo.

Architettura e Design Patterns

L’applicazione è stata strutturata secondo un principio di separazione di responsabilità. Le features contengono la logica di business isolata (cards, sections, timers) con servizi dedicati per operazioni complesse, i components sono componenti UI riutilizzabili e composabili basati su Radix UI per accessibilità, gli hooks contengono logica riutilizzabile per interazioni e calcoli (timer calculations, card interactions, global shortcuts), e i services gestiscono operazioni complesse come persistenza e calcoli dei timer.

L’uso di Next.js 16 in un contesto Electron ha richiesto configurazioni specifiche: output statico per generare file nella directory ‘out’, immagini non ottimizzate per compatibilità Electron, e gestione del routing statico. Ho utilizzato Tailwind CSS 4 per lo styling e Radix UI per i componenti accessibili, garantendo un’interfaccia moderna e professionale. Il sistema di build supporta packaging per Windows (portable, zip), macOS (dmg, zip) e Linux (appimage, zip) tramite electron-builder.

Dettagli Tecnici

1
wolfden-manager/
2
├── app/                    # Next.js app directory
3
├── components/             # Componenti UI riutilizzabili
4
│   ├── cards/              # Componenti specifici per cards
5
│   ├── sections/           # Componenti per sezioni
6
│   ├── layout/             # Layout components
7
│   ├── providers/          # Context providers
8
│   └── ui/                 # Radix UI components
9
├── features/               # Logica di business isolata
10
│   ├── cards/              # Servizi per gestione cards
11
│   ├── sections/           # Servizi per gestione sezioni
12
│   └── timers/             # Servizi per logica timer
13
├── hooks/                  # Custom hooks
14
│   ├── use-timer-calculations.ts
15
│   ├── use-global-shortcuts.ts
16
│   ├── use-card-interactions.ts
17
│   └── ...
18
├── lib/                    # Utilities e servizi
19
│   ├── storage/            # Servizio persistenza
20
│   └── utils/              # Utility functions (time, keyboard, sound)
21
├── store/                  # State management
22
│   └── app-store.tsx       # Context Provider centralizzato
23
├── main/                   # Electron main process
24
│   ├── main.js             # Entry point Electron
25
│   └── preload.js          # Preload script
26
└── types/                  # TypeScript types

1
interface SerializedState {
2
  version: number;                    // Versione per migrazioni future
3
  sections: Section[];                // Array di sezioni
4
  cardsBySection: Array<[number, UserCard[]>];  // Map serializzata come array
5
}