# Music Monitor — Documentazione Architetturale

Music Monitor è un monolite modulare enterprise sviluppato con Laravel 13, Vue 3 (Inertia.js), TypeScript e PostgreSQL. L'architettura è progettata secondo i principi del **Domain-Driven Design (DDD)** e del **Clean Code**, garantendo scalabilità, testabilità e manutenibilità a lungo termine.

---

## 1. Architettura dei Domini (`app/Domain/`)

Il progetto suddivide la logica di business in 8 domini isolati e coesi:

1. **Identity**: Gestione di utenti (`User`), organizzazioni (`Organization`), membri (`OrganizationMember`), impostazioni (`Setting`) e audit log (`AuditLog`).
2. **Profiles**: Profili professionali (`Profile`), generi musicali (`Genre`), capacità (`ProfileCapability`), etichette (`Label`), produzioni discografiche (`Production`) e brani musicali (`Track`).
3. **Opportunities**: Opportunità di booking/collaborazione (`Opportunity`), generi associati (`OpportunityGenre`), shortlist (`Shortlist`) e elementi di shortlist (`ShortlistItem`).
4. **Events**: Eventi musicali (`Event`), location/locali (`Venue`) e partecipanti agli eventi (`EventParticipant`).
5. **Matching**: Richieste di matching (`MatchRequest`) e risultati strutturati (`MatchResult`) guidati dal motore deterministico.
6. **Cira**: Modulo di caching intelligente, gate decision log (`CiraGateDecision`, `CiraCacheEntry`, `CiraCacheDependency`) e invalidazione guidata dalle dipendenze.
7. **Notifications**: Notifiche in-database ed email asincrone (`Notification`).
8. **Verification**: Registri di verifica dell'identità e dei dati (`DataVerificationRecord`).

---

## 2. MatchEngine: Pipeline Deterministica in 4 Fasi

Il `MatchEngine` (`app/Domain/Matching/Services/MatchEngine.php`) non si affida a modelli probabilistici per il ranking primario, garantendo affidabilità e trasparenza:

1. **Normalizzazione**: Estrazione e sanitizzazione dei parametri da `structured_query` (target, generi, città, paese, capability, budget).
2. **Filtro Rigido (Eloquent)**: Applicazione di clausole SQL precise (stato attivo, geolocalizzazione, corrispondenza generi e capability).
3. **Ranking Deterministico a Pesi**: Calcolo del punteggio (0.00 - 10.00) basato su bonus cumulativi:
   - Corrispondenza generi/tag (+3.00)
   - Vicinanza territoriale (+1.50)
   - Freschezza e verifica del profilo (+0.50)
4. **Spiegazione Strutturata**: Generazione di un report testuale leggibile che elenca i criteri soddisfatti (`matched_criteria`) e mancanti (`missing_criteria`).

---

## 3. CIRA Gateway: Caching Intelligente e Gate Decisions

Il gateway `DatabaseCiraGateway` ottimizza le performance del sistema:
- **Fingerprinting**: Calcolo di un hash SHA-256 univoco basato sulla `structured_query`.
- **Cache Hit / Miss**: Se esiste una voce valida in `cira_cache_entries` (non scaduta e non invalidata), viene restituita istantaneamente (`ExactHit`). Altrimenti, viene eseguito il `MatchEngine` (`Miss`).
- **Audit e Decisioni**: Ogni transazione è registrata in `cira_gate_decisions` per tracciare latenza, costi stimati e punteggi di similarità.
- **Invalidazione**: Il servizio `CiraCacheInvalidator` invalida selettivamente la cache quando entità dipendenti (es. generi o profili) subiscono modifiche.

---

## 4. Frontend TypeScript (`resources/js/Types/matching.ts`)

Il layer frontend adotta TypeScript rigoroso con interfacce speculari ai modelli del backend:
- `User`, `Organization`, `Profile`, `MatchRequest`, `MatchResult`.
- Supporto nativo per gli Enum di dominio (es. `OrganizationType`, `ProfileType`, `MatchRequestStatus`, `CiraCacheStatus`).
- Layout `AdminLayout.vue` in modalità scura underground (Tailwind CSS, `bg-zinc-950`) e console interattiva `MatchDashboard.vue` con feedback in tempo reale.
