Portfolio Insights

Per avere una comprensione più completa e approfondita dell’andamento del mio portfolio di investimento ho creato una web app che fornisce delle metriche e analisi aggiuntive rispetto a quelle di base fornite dal broker Directa.

Oltre al valore attuale del patrimonio, con il suo andamento nel tempo, ho aggiunto degli indicatori di performance:

• TWR (Time-Weighted Rate of Return: rendimento composto geometrico)
• CAGR (tasso di crescita annuo composto)
• una vista sulla distribuzione dei mesi e anni migliori e peggiori

L’app fornisce anche un’analisi dei rischi, con

• Volatilità
• Sharpe ratio (rendimento in eccesso sul risk-free rate su volatilità)
• Dettagli sui drawdown.

Per assicurare che la composizione del portfolio sia sempre allineata all’obiettivo di allocazione, ho realizzato anche una funzionalità per disegnare l’allocazione target e identificare automaticamente se la composizione del portfolio si sta allontanando da questa, con i relativi consigli di ribilanciamento quando necessari.

I dati in ingresso, necessari per calcolare e rappresentare tutti questi indicatori, sono resi disponibili dal sito del broker Directa tramite report scaricabili: l’elenco dei movimenti, lo storico del valore del portfolio, e la composizione attuale con le ultime valutazioni.

La procedura di importazione dei report è specifica per il broker Directa, perché è quello che sto usando per i miei investimenti; adattando le funzioni di parsing dei report, il resto dell’app resta comunque usabile con qualsiasi altro broker.

Una volta importati i tre report, tramite una procedura guidata, l’app elabora i dati caricati e presenta le informazioni finanziarie in 6 sezioni: 

1. Dashboard: una vista d’insieme con il valore totale del portfolio e la variazione rispetto al capitale investito, un grafico dell’andamento nel tempo del valore totale del portfolio, del capitale investito e del TWR, zoomabile su periodi di tempo (ultimo mese, tre mesi, sei mesi, anno, totale); la Dashboard include anche una rappresentazione della composizione del portfolio, per asset e tipologie.
2. Portfolio: una vista dettagliata di tutti gli asset presenti in portfolio, con i prezzi medi di carico di ciascuno, il loro valore attuale, la variazione in valore e percentuale; è presente anche una funzione per classificare manualmente il tipo di asset (obbligazioni, azioni, materie prime, fondi, liquidità), necessario alla prima importazione.
3. Allocazione: questa sezione permette di definire la composizione obiettivo del portfolio (asset allocation) con percentuali target per ogni tipo di asset; in base all’obiettivo definito, l’app analizza le differenze tra allocazione attuale e obiettivo, applicando una soglia di tolleranza definita dall’utente, e suggerisce interventi di ribilanciamento per tipo di asset, se necessario.
4. Performance e Rischio: offre una analisi approfondita della performance del portfolio, calcolando il rendimento cumulativo annuo (CAGR), e la distribuzione dei rendimenti mensili e annuali, identificando i mesi e anni migliori e peggiori; la sezione include anche l’analisi degli indicatori di rischio: volatilità, Sharpe ratio con tasso “risk free” configurabile dall’utente, e analisi del massimo drawdown, con date di inizio e di picco, durata e tempo di recupero.
5. Movimenti: in questa sezione sono elencati tutti i flussi di cassa, ordinabili e filtrabili: versamenti e prelievi, dividendi, cedole, commissioni, bolli, tasse…
6. Import: qui è possibile importare i tre report del broker Directa necessari per l’analisi del portfolio: elenco dei movimenti, storico del valore del portfolio, e composizione attuale.

Stack tecnologico, architettura e workflow di sviluppo 

Portfolio Insights è una applicazione web monoutente, da installare localmente (self-hosting) con interfaccia accessibile tramite browser. 

L’architettura è basata su un backend in Node.js + Express e database SQLite, e su un frontend in React + TypeScript + Vite, con Recharts per i diagrammi.

Il progetto è stato sviluppato nell’ambiente di sviluppo VSCode usando il plugin Cline come agente di coding AI con i modelli LLM di DeepSeek v4 Fast e Qwen 3.7 tramite Openrouter. 

L’attività di coding assistito da agente AI è partita dalla scrittura di un documento di design con obiettivi, funzionalità, formule necessarie, e i casi di test con i relativi criteri di accettazione.

Per assicurare una scrittura accurata del codice da parte degli agenti AI, ogni funzionalità è stata suddivisa in una serie di task autoconsistenti e consequenziali, la cui implementazione poteva essere completata e testata prima di procedere con il passo successivo, quando tutte le condizioni (definition of done) erano verificate. 

Ogni funzionalità e ogni decisione su architettura, modello dati, endpoint delle API e scelte tecnologiche è stata formalizzata nella documentazione di progetto.  

Le principali sfide tecnologiche

Sviluppando Portfolio Insights mi sono trovato a dover risolvere alcune sfide:

• La semantica dei flussi di cassa: per assicura il corretto calcolo degli indicatori di performance e di rischio, è stato necessario distinguere le variazioni di valore del portfolio dovute ai flussi di cassa (versamenti e prelievi) dalle quelle dovute a variazioni di valore degli asset.
• L’idempotenza dell’import: l’importazione di aggiornamenti successivi dei report non deve creare duplicazioni: solo i dati più recenti devono essere aggiunti al database. Ho quindi realizzato un sistema di filtri rispetto ai dati già presenti nel database.
• La gestione della valuta: alcuni asset possono essere in valuta diversa da EUR (per esempio azioni del mercato USA quotare in USD). Per assicurare coerenza, ho implementato la conversione in EUR usando una API con i tassi di cambio giornalieri messa a disposizione da BCE.

Cosa ho imparato creando Portfolio Insights

Gli agenti AI possono scrivere codice in autonomia, ma ogni decisione architetturale resta una responsabilità di chi crea l’applicazione: per evitare che l’agente scriva codice senza certezze sui requisiti, introducendo incoerenze ed errori, è fondamentale una iniziale definizione dei requisiti (design document) e poi un approfondimento dei requisiti, casi di test e criteri di accettazione, prima dell’avvio di ogni task.

Per essere sicuro che la scrittura del codice procedesse in modo controllato, senza introdurre divergenze ed errori, ho deciso di suddividere l’implementazione di ogni funzionalità in numerose fasi con perimetro limitato, il cui completamento con successo poteva essere verificato con test oggettivi e build funzionante. In caso di malfunzionamento, era facile identificare quale attività ne era responsabile e fare rollback rispetto al precedente commit. 

Il risultato finale di questa esperienza è stata la creazione di Portfolio Insights, un’app di analisi del portfolio fatta su misura per le mie esigenze, che uso periodicamente per avere una vista completa e approfondita dell’andamento dei miei investimenti. 

Ma il risultato più interessante per me è stato fare esperienza del workflow di coding assistito da un agente AI: ho imparato a istruire correttamente un agente per ottenere una serie di rilasci successivi che hanno implementato progressivamente tutte le funzionalità previste.

Ho quindi potuto realizzare in pochi giorni un progetto complesso che altrimenti sarebbe stato fuori dalla portata delle mie competenze, o avrebbe richiesto mesi di lavoro manuale.

⚠️ Disclaimer — Progetto amatoriale e sperimentale

Portfolio Insights è un progetto personale, amatoriale e sperimentale, sviluppato principalmente per uso personale e didattico. Non è un software professionale né un prodotto finanziario.

Il progetto è stato sviluppato anche attraverso un approccio AI-assisted / “vibe coding” e, nonostante siano presenti test e verifiche, possono esserci errori, imprecisioni o comportamenti inattesi, inclusi errori nei calcoli o nell’interpretazione dei dati.

Le informazioni, le metriche e gli eventuali suggerimenti di Portfolio Insights sono forniti esclusivamente a scopo informativo e non costituiscono consulenza finanziaria, fiscale o di investimento, né una raccomandazione ad acquistare o vendere strumenti finanziari.

Il software è fornito “AS IS”, senza garanzie espresse o implicite sulla correttezza, completezza, accuratezza o affidabilità dei risultati. L’utilizzo del software e qualsiasi decisione presa sulla base dei suoi risultati sono sotto la piena responsabilità dell’utente.

Non viene fornita alcuna garanzia, assistenza professionale o assicurazione circa l’assenza di errori o la disponibilità del software.

⚠️ Nota importante: le metriche e i risultati mostrati da Portfolio Insights sono calcolati automaticamente a partire dai dati importati e hanno esclusivamente finalità informative. Non devono essere interpretati come consulenza finanziaria o come base unica per prendere decisioni di investimento.