Quartz 4

FIRE 75.0054 ✨Composable Architecture Guide

4 min read

FIRE RENOVATION MANIFESTO: Towards a Sovereign Quant Platform

Versione: 1.0 (Draft) Data: 2025-12-20 Target: Core Team & Contributors Obiettivo: Definire i pilastri architetturali, funzionali e filosofici per la rifondazione di FIRE.

1. La Visione: Da “Tool” a “Piattaforma”

FIRE non è più solo una raccolta di script di backtesting. L’obiettivo è trasformarlo in una Piattaforma di Ricerca Quantitativa Sovrana.

  • Sovrana: L’utente possiede i dati (RAW), le strategie (Python) e le analisi. Nessuna “Scatola Nera”.
  • Estendibile: Il core del sistema è stabile, ma le funzionalità di analisi ed export sono moduli dinamici (“Scripts”) scritti e modificabili dall’utente.
  • Professionale: L’architettura garantisce determinismo, thread-safety e coerenza dei dati in ogni momento.

2. Pilastro I: Data Sovereignty (Smart Data Pipeline)

Il dato è l’asset più prezioso. La gestione deve essere rigorosa e agnostica rispetto al provider.

2.1. Ontologia del Dato

  • Storage RAW: I dati su disco (.csv / .parquet) devono essere sempre salvati nel loro formato grezzo originale.
  • Normalizzazione (Reverse Adjustment): Se un provider (es. Yahoo) invia dati rettificati, FIRE li “srettifica” matematicamente prima di salvarli, preservando la verità storica.
  • Metadata Sidecar: Ogni file dati è accompagnato da un .meta.json che contiene gli eventi corporativi (Split, Dividendi) e la provenienza.

2.2. Gestione Multi-Vendor

  • Namespacing: I file di cache includono il nome del provider (es. AAPL_1d_Yahoo.csv, AAPL_1d_Nasdaq.csv) per evitare conflitti e sovrascritture.
  • Waterfall Fetch: Il DataManager cerca i dati seguendo una priorità definita dall’utente (es. Prima Nasdaq, poi Yahoo).

3. Pilastro II: Architettura del Sistema (Core Stability)

Per garantire stabilità in un ambiente GUI Multithreaded (Qt), adottiamo un approccio ibrido pragmatico.

3.1. Gestione dello Stato (State Management)

  • Settings Singleton: La configurazione globale (SettingsManager) è un Singleton Thread-Safe. Esiste un’unica fonte di verità in memoria.
  • Composition Root DI: Nonostante il Singleton, le dipendenze principali (AppState, DataManager) vengono iniettate esplicitamente nel main.py per chiarezza architetturale.

3.2. Concorrenza Sicura (Snapshot Pattern)

I Worker asincroni non devono MAI leggere lo stato globale mutevole durante l’esecuzione.

  • Regola dello Snapshot: Il Worker riceve una copia congelata (“Snapshot”) dei parametri di configurazione (es. use_adjusted=True) nel suo costruttore (__init__).
  • Determinismo: Questo garantisce che se l’utente cambia impostazioni mentre un calcolo è in corso, il risultato del calcolo rimanga coerente con le condizioni di partenza.

4. Pilastro III: Workflow Operativo (Dual-Mode)

Riconosciamo che esistono due modalità di lavoro distinte che richiedono interfacce dedicate.

4.1. The Lab (Backtest Tab)

  • Scopo: Analisi profonda di una singola strategia.
  • Focus: Micro-analisi (Trade-by-trade, entry/exit points, debug grafico).
  • Interazione: Selezione singola modale. Grafico ed Equity Line sempre visibili.

4.2. The Arena (Strategy Tab)

  • Scopo: Confronto massivo e selezione (“Torneo”).
  • Focus: Macro-analisi (Ranking, Risk/Reward, Robustezza).
  • Interazione:
    • Master: Leaderboard ordinabile per confrontare N strategie.
    • Detail: Drill-down al click per vedere i dettagli della singola strategia.
    • Analytics: Dashboard Plotly in popup per visualizzazioni avanzate (Scatter, Radar).

5. Pilastro IV: Estendibilità (FIRE Script Engine)

Questo è il futuro di FIRE. Spostiamo la logica di business “periferica” (analisi statistiche, export, utility) fuori dal Core e dentro script utente.

5.1. Il Protocollo Script

Ogni script è un file Python autonomo che espone:

  1. YAML Frontmatter: Metadati che descrivono lo script (Titolo, Tipo, Tag, Target Context).
  2. Funzione run(context): L’entry point unico.

5.2. Context Injection

FIRE inietta nello script un oggetto Context sicuro che espone le API del Core (DataManager, Settings, Logger) senza esporre la complessità della GUI Qt. Lo script si concentra sulla logica (es. calcolare la volatilità), FIRE si occupa dell’infrastruttura.

5.3. Filosofia UI: “Script Hub”

Per evitare l’anarchia nell’interfaccia:

  • Hub Centrale: Tutti gli script risiedono in una libreria ricercabile (“Script Hub”).
  • No Auto-UI: Gli script non creano bottoni automaticamente.
  • Preferiti: L’utente sceglie quali script “pinnare” nella Toolbar o nei Menu Contestuali.
  • Contestualità: Gli script appaiono nei menu contestuali (es. tasto destro sul grafico) solo se il loro tag target corrisponde al contesto (es. target: chart).

6. Roadmap di Implementazione

  1. Refactoring Core: Consolidamento del Singleton/Snapshot e della Smart Data Pipeline (Completato).
  2. UI Segregation: Separazione definitiva tra Lab e Arena (Completato).
  3. Script Engine (Next Big Step):
    • Sviluppo del ScriptLoader (Parser YAML).
    • Definizione della classe ScriptContext API.
    • Creazione dello “Script Hub” UI.
    • Migrazione del POC “Volatility Analyzer” a primo Script ufficiale.

Graph View