Charity Market

Origine del progetto

Charity Market è un progetto software personale nato dalla mia partecipazione a mercatini e fiere di beneficenza organizzati in un contesto di volontariato. Durante queste esperienze ho avuto modo di osservare da vicino alcune difficoltà pratiche nella gestione delle attività quotidiane: registrare gli oggetti ricevuti, ricordare da chi provengono, controllare quali articoli sono ancora disponibili, gestire le vendite e mantenere uno storico ordinato delle operazioni.

Da questa esigenza è nata l’idea di sviluppare un gestionale dedicato a piccole realtà benefiche, charity shop, mercatini solidali e iniziative temporanee di raccolta fondi. L’obiettivo non è creare un semplice esercizio dimostrativo, ma progettare un’applicazione il più possibile vicina a un caso d’uso reale, in grado di aiutare operatori e volontari a lavorare in modo più ordinato, riducendo la gestione manuale delle informazioni.

Il progetto rappresenta anche un’occasione per approfondire lo sviluppo di un software completo, partendo dall’analisi del problema fino alla realizzazione di un sistema con backend, database, autenticazione, ruoli utente, logica applicativa, deployment e possibili client multipiattaforma.

Cosa fa il software

Charity Market è pensato come un sistema gestionale centralizzato per la gestione di donazioni, inventario, utenti e vendite. Il software permette di registrare i donatori, catalogare gli articoli ricevuti, assegnare ogni articolo a un donatore, indicarne condizioni, prezzo suggerito e commenti, e seguirne lo stato fino alla vendita.

La gestione delle vendite consente di creare operazioni contenenti uno o più articoli, assegnare il prezzo finale di vendita, indicare il metodo di pagamento, calcolare il totale e mantenere uno storico delle vendite completate o annullate. Le vendite annullate non vengono eliminate, ma conservate nello storico, così da non perdere informazioni importanti su inventario e movimenti precedenti.

Il sistema include anche una gestione degli utenti basata su ruoli, in modo da separare le responsabilità operative. Un amministratore può gestire l’intero sistema, mentre altri profili possono occuparsi di inventario, gestione del mercato o registrazione delle vendite. Le autorizzazioni non vengono controllate solo dall’interfaccia, ma anche dal backend, così da rendere più coerente e sicura la gestione delle operazioni.

Stato attuale del progetto

Attualmente Charity Market è un prototipo funzionale desktop-first. La parte più completa è l’applicazione desktop per Windows, che può funzionare in modalità locale oppure collegarsi a un server remoto già attivo.

In modalità locale, un singolo computer può avviare l’applicazione desktop, il server Quarkus e un database SQLite. Questa configurazione è adatta a scenari semplici, test, dimostrazioni o piccole installazioni dove un solo dispositivo gestisce l’intero sistema.

In modalità remota, invece, l’applicazione desktop funziona come client e si collega a un backend eseguito separatamente, ad esempio tramite Docker. In questo scenario il server può utilizzare SQLite oppure PostgreSQL, permettendo una configurazione più adatta a più client e a un utilizzo più strutturato.

Sono già state implementate le funzionalità principali: autenticazione tramite username e password, gestione token JWT, creazione e sospensione degli utenti, assegnazione dei ruoli, protezione delle operazioni, gestione donatori, gestione articoli, inventario, vendite, annullamento vendite, impostazioni globali e supporto a database SQLite e PostgreSQL.

Il progetto dispone inoltre di una base per il deployment tramite Docker, con l’obiettivo di semplificare l’esecuzione del backend e rendere più ordinata la distribuzione del software in ambienti diversi.

Tecnologie utilizzate

Il backend del progetto è basato su Quarkus, utilizzato per realizzare l’API centrale, gestire la logica applicativa, l’autenticazione, le autorizzazioni, le regole di business e l’accesso ai dati. Questa scelta permette di lavorare su un backend moderno, strutturato e adatto a essere eseguito anche in container.

Per la gestione dei dati vengono utilizzati SQLite e PostgreSQL. SQLite è utile per installazioni semplici, locali o portabili, dove un singolo computer può gestire applicazione, server e database. PostgreSQL è invece pensato per scenari più strutturati, con più client, maggiore concorrenza, migliore gestione operativa e possibilità di backup più solide.

L’autenticazione è basata su username e password con utilizzo di token JWT. Il sistema prevede ruoli e permessi per separare le responsabilità degli utenti e impedire che account sospesi o non autorizzati possano continuare a modificare i dati.

Docker viene utilizzato per rendere più semplice il deployment del server e del database, soprattutto negli scenari in cui il backend deve essere eseguito su una macchina dedicata o condiviso da più client. La containerizzazione permette di rendere l’ambiente più riproducibile e più facile da distribuire.

La parte desktop è pensata per Windows e rappresenta attualmente il client principale del progetto. In futuro il sistema dovrà evolvere verso una maggiore separazione tra componenti desktop-specifiche e codice condiviso, così da permettere lo sviluppo di un client Android senza duplicare eccessivamente logica applicativa, modelli dati e gestione delle sessioni.

Roadmap attuale

La roadmap attuale si concentra sul consolidamento delle basi già implementate. Il primo obiettivo è rendere più robusto il sistema desktop-first, migliorando stabilità, organizzazione del codice, gestione degli errori, esperienza utente e coerenza tra interfaccia e backend.

Un’altra area importante riguarda la sicurezza. Il progetto dovrà evolvere verso un utilizzo più adatto a scenari reali, includendo HTTPS, configurazioni più sicure per il reverse proxy, gestione più robusta delle chiavi JWT, criteri password più forti, scadenza e rinnovo dei token, limitazione dei tentativi di login e maggiore controllo sull’accesso al database.

È prevista anche una maggiore attenzione alla tracciabilità delle operazioni. L’obiettivo è introdurre una audit history più completa, capace di registrare chi crea, modifica, vende, annulla o aggiorna informazioni importanti. Questo aspetto è fondamentale per un software che gestisce inventario, vendite e dati collegati ai donatori.

Dal punto di vista dei dati, il progetto dovrà passare da una gestione ancora parzialmente affidata ad aggiornamenti automatici dello schema a migrazioni database più strutturate e controllate. Questo permetterà di rendere il software più affidabile nel tempo e più adatto a futuri aggiornamenti.

Roadmap futura

Nel lungo periodo, Charity Market dovrà diventare una piattaforma multi-dispositivo. L’idea è avere un backend centrale condiviso, una desktop app per amministratori e responsabili dell’inventario, e un client Android per venditori o operatori mobili.

Il client Android dovrà permettere di configurare l’indirizzo del server, effettuare il login, cercare articoli nell’inventario, consultare i donatori, registrare vendite e utilizzare la scansione di codici a barre o QR code. In questo modo, durante un mercatino o una fiera, gli operatori potrebbero lavorare da smartphone o tablet senza dipendere esclusivamente da una postazione desktop.

Sono previste anche funzionalità avanzate per reportistica e amministrazione: vendite per periodo, ricavi per metodo di pagamento, riepiloghi per donatore, articoli invenduti, vendite annullate, attività degli utenti ed esportazione dei dati in formati come CSV o PDF.

Un’altra area futura riguarda backup e recovery. Il progetto dovrà includere procedure semplici per il salvataggio e il ripristino dei dati, sia per installazioni SQLite sia per installazioni PostgreSQL. Questo aspetto è essenziale perché i volumi Docker preservano i dati, ma non sostituiscono una vera strategia di backup.

Infine, una versione più matura del software dovrebbe includere release numerate, installer Windows più rifiniti, eventuali APK Android firmati, controlli di compatibilità tra client e server, notifiche di aggiornamento, test automatici e procedure di rollback.

Utilizzo dell’intelligenza artificiale

Durante lo sviluppo di Charity Market sto utilizzando strumenti di intelligenza artificiale come supporto al processo di progettazione e sviluppo. L’AI non viene utilizzata come sostituto della comprensione tecnica, ma come assistente per ragionare meglio sulle scelte architetturali, analizzare problemi, migliorare la struttura del codice, produrre documentazione e pianificare le evoluzioni future.

L’utilizzo dell’AI mi aiuta soprattutto nelle fasi di confronto e revisione: posso descrivere un problema, valutare più possibili soluzioni, individuare rischi, migliorare la chiarezza della documentazione e trasformare idee iniziali in roadmap più ordinate. Questo approccio mi permette di lavorare in modo più consapevole, mantenendo comunque il controllo sulle decisioni tecniche e sulla direzione del progetto.

Charity Market è quindi anche un progetto attraverso cui sto imparando a integrare l’intelligenza artificiale in un workflow reale di sviluppo software, utilizzandola per aumentare produttività, qualità della documentazione e capacità di analisi, senza perdere attenzione alla sicurezza, alla manutenibilità e alla comprensione del codice.