# Studio di Dettaglio: Opzione 2 - Angular Workspace Monorepo

Questo documento descrive in dettaglio la strategia, la configurazione e i passaggi necessari per implementare la clonazione del progetto **canti** per la variante **stereocomics** attraverso l'**Opzione 2: Angular Workspace Monorepo**.

Con questo approccio, il repository viene strutturato per ospitare **due applicazioni distinte** (`canti` e `stereocomics`) e **una o più librerie condivise** (`shared-core`) che conterranno la logica di business comune (servizi audio, parser di testi, database locale, integrazioni API).

---

## 1. Architettura e Struttura delle Cartelle

Nel modello Monorepo, la struttura dei file viene riorganizzata per isolare l'interfaccia utente (pagine, componenti, temi) e condividere i servizi fondamentali.

```mermaid
graph TD
    subgraph Monorepo Workspace
        Shared[Libreria Condivisa: @shared/core]
        AppCanti[App 1: Canti]
        AppStereo[App 2: Stereocomics]
    end
    
    AppCanti --> Shared
    AppStereo --> Shared
```

La struttura delle cartelle diventerà simile alla seguente:
```text
canti/
├── angular.json
├── package.json
├── tsconfig.json
├── src/                      <-- Diventa l'applicazione Canti originale
│   ├── app/
│   │   ├── pages/            <-- Pagine specifiche di Canti
│   │   └── app.module.ts
│   └── assets/               <-- Asset di Canti
├── projects/
│   ├── shared-core/          <-- Libreria condivisa generata
│   │   ├── src/
│   │   │   ├── public-api.ts
│   │   │   └── lib/
│   │   │       └── services/ <-- AudioEngine, LyricsParser, CantiService, ecc.
│   └── stereocomics/         <-- Nuova applicazione Stereocomics
│       ├── src/
│       │   ├── app/
│       │   │   ├── pages/    <-- Pagine e UI customizzate di Stereocomics
│       │   │   └── app.module.ts
│       │   ├── assets/       <-- Asset di Stereocomics
│       │   └── theme/        <-- Fogli di stile di Stereocomics
```

---

## 2. Passaggi Operativi per l'Implementazione

### Passo 2.1: Inizializzazione della Libreria Condivisa
Generiamo una libreria Angular per ospitare i servizi condivisi.

```bash
ng generate library shared-core --prefix=shared
```

Questo comando creerà la cartella `projects/shared-core/` e aggiornerà [angular.json](file:///Users/davidfrassi/SRC/agenti/canti/angular.json) e [tsconfig.json](file:///Users/davidfrassi/SRC/agenti/canti/tsconfig.json) inserendo il path alias (es. `@shared/core`).

---

### Passo 2.2: Migrazione dei Servizi Core
Sposteremo tutti i servizi non legati direttamente alla UI da `src/app/services/` a `projects/shared-core/src/lib/services/`.

Servizi da migrare:
* [audio-engine.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/audio-engine.service.ts)
* [canti.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/canti.service.ts)
* [lyrics-parser.service.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/services/lyrics-parser.service.ts)
* Eventuali altri helper o interfacce dati comuni.

Esponiamo i servizi nel file `projects/shared-core/src/public-api.ts`:
```typescript
export * from './lib/services/audio-engine.service';
export * from './lib/services/canti.service';
export * from './lib/services/lyrics-parser.service';
```

Aggiorneremo quindi gli import all'interno dell'applicazione principale `canti` (e successivamente `stereocomics`):
```typescript
// Da:
import { CantiService } from '../services/canti.service';
// A:
import { CantiService } from '@shared/core';
```

---

### Passo 2.3: Generazione della Nuova Applicazione Stereocomics
Creiamo la seconda applicazione all'interno del workspace:

```bash
ng generate application stereocomics --routing --style=scss
```

In [angular.json](file:///Users/davidfrassi/SRC/agenti/canti/angular.json) verrà aggiunto un nuovo progetto denominato `stereocomics`. 

#### Integrazione Ionic
Per abilitare le funzionalità Ionic (componenti UI, gesture, ecc.) nella nuova applicazione, occorre:
1. Importare `IonicModule.forRoot()` nel file `projects/stereocomics/src/app/app.module.ts`.
2. Copiare o adattare la struttura di theming da `src/theme/` a `projects/stereocomics/src/theme/`.

---

### Passo 2.4: Personalizzazione delle Pagine e dei Componenti
A differenza dell'Opzione 1 (dove le pagine HTML sono identiche), nell'Opzione 2 `stereocomics` ha le sue pagine indipendenti in `projects/stereocomics/src/app/pages/`. 

È possibile:
* Creare layout completamente differenti.
* Aggiungere nuove feature o pagine esclusive (es. una sezione "Comics" o "Store") senza intaccare minimamente l'applicazione `canti`.
* Importare i servizi core da `@shared/core` in ciascuna pagina per gestire la logica dei canti e dell'audio.

---

### Passo 2.5: Script in `package.json`
Modificheremo gli script di avvio e build per differenziare i target:

```json
"scripts": {
  "start:canti": "ng serve app --port=4200",
  "start:stereocomics": "ng serve stereocomics --port=4300",
  "build:shared": "ng build shared-core",
  "build:canti": "npm run build:shared && ng build app --configuration=production",
  "build:stereocomics": "npm run build:shared && ng build stereocomics --configuration=production"
}
```

---

### Passo 2.6: Gestione di Capacitor (Mobile Apps Separate)
Per compilare le due app per iOS/Android in modo totalmente indipendente:
1. L'app `canti` continuerà ad usare la configurazione di Capacitor a livello di root, oppure verrà spostata in una sottocartella.
2. Inizializziamo Capacitor specificamente per `stereocomics` posizionando un file `capacitor.config.ts` all'interno di `projects/stereocomics/`:

```typescript
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'it.stereocomics.app',
  appName: 'Stereocomics',
  webDir: '../../dist/stereocomics', // Punterà alla cartella di build di Angular
  bundledWebRuntime: false
};

export default config;
```

---

## 3. Vantaggi e Svantaggi dell'Opzione 2

### Vantaggi:
1. **Massima Libertà di Design e UX**: L'applicazione `stereocomics` può avere una struttura di navigazione, pagine e flussi utente completamente diversi da `canti`.
2. **Isolamento del Codice UI**: I cambiamenti estetici o le nuove feature di interfaccia introdotte su Stereocomics non rischiano di rompere l'applicazione Canti originale.
3. **Riutilizzo della Logica di Business**: Tutta la logica complessa dei database locali, del lettore audio e dei parser rimane centralizzata e testata una volta sola nella libreria `@shared/core`.

### Svantaggi:
1. **Sforzo Iniziale Elevato**: Richiede un refactoring iniziale importante per estrarre tutti i servizi e ridefinire i path di importazione in tutto il progetto.
2. **Build più Lente**: La compilazione richiede prima la build delle librerie condivise e poi dell'applicazione specifica.
3. **Gestione delle Dipendenze**: Sebbene condividano lo stesso `package.json`, l'aggiornamento di una libreria esterna (es. Ionic o Angular) deve essere testato su entrambe le applicazioni per evitare regressioni.

---

## 4. Criteri di Accettazione e Verifica (Verification Plan)

### Verifica dello Sviluppo Locale
1. Eseguire `npm run start:canti` -> Verificare il funzionamento completo dell'app principale sulla porta `4200`.
2. Eseguire `npm run start:stereocomics` -> Verificare che la nuova app risponda sulla porta `4300` con il layout personalizzato.

### Verifica della Compilazione Condivisa
1. Apportare una modifica al servizio `CantiService` (es. aggiungere un log).
2. Verificare che la modifica sia visibile ed efficace sia su `canti` che su `stereocomics` dopo aver compilato la libreria condivisa.