====== Panoramica dell'architettura ======

Questo documento descrive l'architettura complessiva della suite WvdS FPC RAD Studio.

===== Decisioni di design =====

==== Perché Pascal per le estensioni VS Code? ====

**Motivazione:**
  * Base di codice unificata per tutti i target (GUI, TUI, Web, estensioni)
  * Tipizzazione forte riduce gli errori a runtime
  * Sfruttare il know-how degli sviluppatori da progetti Pascal esistenti
  * pas2js permette output JavaScript di alta qualità

**Alternative considerate:**
^ Alternativa ^ Decisione ^ Motivazione ^
| TypeScript | Rifiutato | Due linguaggi, maggiore complessità |
| Rust + WASM | Rifiutato | Interop complessa con API VSCode |
| Delphi | Rifiutato | Commerciale, nessuna alternativa pas2js |

==== Perché PXAML invece di LFM? ====

**Motivazione:**
  * Controllo versione: XML e diff-friendly
  * Multi-target: stesso markup per GUI, TUI, Web
  * Tooling: parser XML standard disponibili
  * Familiare: sintassi WPF/XAML per chi migra

===== Architettura a strati =====

<code>
┌─────────────────────────────────────────────────────────────────────┐
│                        Extension Layer                               │
│  (extension_main.pas - Entry Point, Command Handler, UI Integration) │
├─────────────────────────────────────────────────────────────────────┤
│                        Service Layer                                 │
│  (*.Service.pas - Logica di business, validazione, operazioni)       │
├─────────────────────────────────────────────────────────────────────┤
│                        Model Layer                                   │
│  (*.Models.pas - Record, tipi, enum, nessuna logica)                 │
├─────────────────────────────────────────────────────────────────────┤
│                     Infrastructure Layer                             │
│  (WvdS.VSCode.*, WvdS.Node.* - API Wrapper, Platform Abstraction)    │
└─────────────────────────────────────────────────────────────────────┘
</code>

==== Responsabilita ====

^ Strato ^ Contenuto ^ Dipendenze ^
| Extension | Interazione UI, registrazione comandi | Service, Model, Infrastructure |
| Service | Logica di business, validazione | Model |
| Model | Strutture dati | Nessuna |
| Infrastructure | API VSCode/Node | Solo API esterne |

==== Regole ====

<code>
CONSENTITO:   Extension -> Service -> Model
VIETATO:  Service -> Extension (inversione)
VIETATO:  Model -> Service (logica nel Model)
</code>

===== Grafo delle dipendenze =====

<code>
                    wvds.vscode.packaging
                           │
                           ▼
wvds.vscode.ui.preview ─► wvds.vscode.build
         │                      │
         ▼                      │
wvds.vscode.ui.designer         │
         │                      │
         └───────┬──────────────┘
                 ▼
         wvds.vscode.projects
                 │
                 ▼
         wvds.vscode.ui.meta
                 │
                 ▼
         wvds.vscode.core (Base)
</code>

==== Dettaglio dipendenze estensioni ====

^ Estensione ^ Dipendenze ^ Ruolo ^
| core | - | Base: toolchain, logging, servizi condivisi |
| build | core | Compilazione, formattatore uses |
| projects | core | Gestione progetti, template |
| ui.meta | core | Registry componenti |
| ui.designer | core | Editor PXAML |
| ui.preview | core, ui.designer | Anteprima live |
| packaging | core, build | Creazione VSIX |

===== Struttura monorepo =====

==== sources/ - Single Source of Truth ====

<code>
sources/
├── common/                     # Codice condiviso
│   ├── core/                   # Unit base (nessuna dipendenza)
│   │   ├── WvdS.System.pas
│   │   ├── WvdS.Collections.pas
│   │   └── WvdS.Strings.pas
│   │
│   ├── ui/                     # UI Framework
│   │   ├── controls/           # Controlli base
│   │   ├── components/         # Componenti compositi
│   │   ├── runtime/            # Runtime PXAML
│   │   └── targets/            # Renderer
│   │       ├── tui/            # Terminal UI
│   │       ├── gui/            # Desktop GUI
│   │       └── web/            # Browser
│   │
│   └── web/                    # Host Bridges
│       ├── nodejs/             # API Node.js
│       └── vscode/             # API VSCode
│
├── extensions/                 # Pacchetti VSIX
│   └── wvds.vscode.{name}/
│       ├── pas/                # Sorgente Pascal
│       ├── dist/               # JS compilato
│       ├── templates/          # Template HTML
│       ├── images/             # Icone, grafica
│       ├── package.json        # Manifesto estensione
│       └── build.cfg           # Configurazione build
│
├── applications/               # App standalone
├── tools/                      # Strumenti CLI
└── packages/                   # Pacchetti IDE
</code>

==== binaries/ - Output build ====

<code>
binaries/
├── out/{app}/{target}/{mode}/  # Artefatti build
│   ├── gen/                    # Codice generato
│   ├── bin/                    # File eseguibili
│   └── assets/                 # Risorse
│
├── cache/                      # Cache compilatore (.ppu, .o)
├── dist/                       # Artefatti release (.vsix)
└── logs/                       # Protocolli build
</code>

===== Anatomia di un'estensione =====

==== Struttura directory ====

<code>
wvds.vscode.{name}/
├── pas/
│   ├── extension_main.pas      # Entry Point (OBBLIGATORIO)
│   ├── {Feature}.Models.pas    # Strutture dati
│   ├── {Feature}.Service.pas   # Logica di business
│   └── {Feature}.Dialog.pas    # Componenti UI (opzionale)
│
├── dist/
│   ├── extension_main.js       # JS compilato
│   └── extension_main.js.map   # Source Map
│
├── templates/
│   └── *.html                  # Template WebView
│
├── images/
│   └── icon.png                # Icona estensione
│
├── package.json                # Manifesto VSCode
├── build.cfg                   # Configurazione build
└── README.md                   # Documentazione
</code>

==== Pattern extension_main.pas ====

<code pascal>
unit extension_main;

{$mode objfpc}{$H+}

interface

uses
  JS,
  VSCode.API,
  VSCode.Commands,
  VSCode.ExtensionExports,
  {Feature}.Service,
  {Feature}.Models;

procedure Activate(AContext: TExtensionContext);
procedure Deactivate;

implementation

procedure DoActivate(AContext: TExtensionContext);
begin
  // Inizializzare i servizi
  Initialize{Feature}Service;

  // Registrare i comandi
  RegisterCommand('wvds.{feature}.{action}', @Handle{Action});

  // Output Channel
  ShowInfoMessage('WvdS {Name} attivato');
end;

procedure Activate(AContext: TExtensionContext);
begin
  try
    DoActivate(AContext);
  except
    on E: Exception do
      ShowErrorMessage(Format(rsActivationFailed, [E.Message]));
  end;
end;

procedure Deactivate;
begin
  // Cleanup
end;

initialization
  ExportActivateDeactivate(@Activate, @Deactivate);

end.
</code>

===== Comunicazione tra estensioni =====

==== Tramite servizi condivisi ====

Le estensioni comunicano tramite l'estensione Core:

<code pascal>
// Nell'estensione A
CoreService.PublishEvent('build.completed', BuildResult);

// Nell'estensione B
CoreService.SubscribeEvent('build.completed', @OnBuildCompleted);
</code>

==== Tramite API VSCode ====

Per accoppiamento lasco:

<code pascal>
// Chiamare comandi
ExecuteCommand('wvds.build.run');

// Eventi
OnDidChangeConfiguration(@HandleConfigChange);
</code>

===== Pipeline di build =====

<code>
┌──────────────────────────────────────────────────────────────┐
│                     BUILD PIPELINE                            │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  1. Controllo policy (wvds-lint)                              │
│     - Nessun file .ts?                                        │
│     - Nessun duplicato?                                       │
│     - Wrapper solo in common?                                 │
│                                                               │
│  2. Compilazione pas2js                                       │
│     - Risoluzione unit                                        │
│     - Type checking                                           │
│     - Generazione JavaScript                                  │
│                                                               │
│  3. Elaborazione asset                                        │
│     - Copiare template HTML                                   │
│     - Ottimizzare immagini                                    │
│     - Validare package.json                                   │
│                                                               │
│  4. Output                                                    │
│     - dist/extension_main.js                                  │
│     - dist/extension_main.js.map                              │
│                                                               │
│  5. Packaging VSIX (opzionale)                                │
│     - vsce package                                            │
│     - binaries/dist/*.vsix                                    │
│                                                               │
└──────────────────────────────────────────────────────────────┘
</code>

===== Vedi anche =====

  * [[.:pxaml-pipeline|Pipeline PXAML]]
  * [[.:extension-architektur|Architettura estensioni in dettaglio]]
  * [[.:targets|Target di build]]
  * [[.:extension-entwicklung|Sviluppo estensioni]]