====== Architektur-Übersicht ======

Dieses Dokument beschreibt die Gesamtarchitektur der WvdS FPC RAD Studio Suite.

===== Design-Entscheidungen =====

==== Warum Pascal für VS Code Extensions? ====

**Motivation:**
  * Einheitliche Codebasis für alle Targets (GUI, TUI, Web, Extensions)
  * Starke Typisierung reduziert Laufzeitfehler
  * Entwickler-Know-how aus bestehenden Pascal-Projekten nutzen
  * pas2js ermöglicht hochwertige JavaScript-Ausgabe

**Alternativen betrachtet:**
^ Alternative ^ Entscheidung ^ Begründung ^
| TypeScript | Abgelehnt | Zwei Sprachen, mehr Komplexität |
| Rust + WASM | Abgelehnt | Komplexe Interop mit VSCode API |
| Delphi | Abgelehnt | Kommerziell, keine pas2js-Alternative |

==== Warum PXAML statt LFM? ====

**Motivation:**
  * Versionskontrolle: XML ist diff-freundlich
  * Multi-Target: Gleiches Markup für GUI, TUI, Web
  * Tooling: Standard-XML-Parser verfügbar
  * Bekannt: WPF/XAML-Syntax für Umsteiger

===== Schichtenarchitektur =====

<code>
┌─────────────────────────────────────────────────────────────────────┐
│                        Extension Layer                               │
│  (extension_main.pas - Entry Point, Command Handler, UI Integration) │
├─────────────────────────────────────────────────────────────────────┤
│                        Service Layer                                 │
│  (*.Service.pas - Geschäftslogik, Validierung, Operationen)         │
├─────────────────────────────────────────────────────────────────────┤
│                        Model Layer                                   │
│  (*.Models.pas - Records, Typen, Enums, keine Logik)                 │
├─────────────────────────────────────────────────────────────────────┤
│                     Infrastructure Layer                             │
│  (WvdS.VSCode.*, WvdS.Node.* - API Wrapper, Platform Abstraction)    │
└─────────────────────────────────────────────────────────────────────┘
</code>

==== Verantwortlichkeiten ====

^ Schicht ^ Inhalt ^ Abhängigkeiten ^
| Extension | UI-Interaktion, Command-Registrierung | Service, Model, Infrastructure |
| Service | Geschäftslogik, Validierung | Model |
| Model | Datenstrukturen | Keine |
| Infrastructure | VSCode/Node APIs | Nur externe APIs |

==== Regeln ====

<code>
ERLAUBT:   Extension -> Service -> Model
VERBOTEN:  Service -> Extension (Umkehr)
VERBOTEN:  Model -> Service (Logik in Model)
</code>

===== Abhängigkeitsgraph =====

<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 (Basis)
</code>

==== Extension-Abhängigkeiten im Detail ====

^ Extension ^ Abhängigkeiten ^ Rolle ^
| core | - | Basis: Toolchain, Logging, Shared Services |
| build | core | Kompilierung, Uses-Formatter |
| projects | core | Projektverwaltung, Templates |
| ui.meta | core | Komponenten-Registry |
| ui.designer | core | PXAML-Editor |
| ui.preview | core, ui.designer | Live-Vorschau |
| packaging | core, build | VSIX-Erstellung |

===== Monorepo-Struktur =====

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

<code>
sources/
├── common/                     # Shared Code
│   ├── core/                   # Basis-Units (keine Abhängigkeiten)
│   │   ├── WvdS.System.pas
│   │   ├── WvdS.Collections.pas
│   │   └── WvdS.Strings.pas
│   │
│   ├── ui/                     # UI Framework
│   │   ├── controls/           # Basis-Controls
│   │   ├── components/         # Composite Components
│   │   ├── runtime/            # PXAML Runtime
│   │   └── targets/            # Renderer
│   │       ├── tui/            # Terminal UI
│   │       ├── gui/            # Desktop GUI
│   │       └── web/            # Browser
│   │
│   └── web/                    # Host Bridges
│       ├── nodejs/             # Node.js APIs
│       └── vscode/             # VSCode APIs
│
├── extensions/                 # VSIX-Pakete
│   └── wvds.vscode.{name}/
│       ├── pas/                # Pascal-Quellcode
│       ├── dist/               # Kompiliertes JS
│       ├── templates/          # HTML-Templates
│       ├── images/             # Icons, Grafiken
│       ├── package.json        # Extension-Manifest
│       └── build.cfg           # Build-Konfiguration
│
├── applications/               # Standalone-Apps
├── tools/                      # CLI-Tools
└── packages/                   # IDE-Packages
</code>

==== binaries/ - Build-Output ====

<code>
binaries/
├── out/{app}/{target}/{mode}/  # Build-Artefakte
│   ├── gen/                    # Generierter Code
│   ├── bin/                    # Ausführbare Dateien
│   └── assets/                 # Ressourcen
│
├── cache/                      # Compiler-Cache (.ppu, .o)
├── dist/                       # Release-Artefakte (.vsix)
└── logs/                       # Build-Protokolle
</code>

===== Extension-Anatomie =====

==== Verzeichnisstruktur ====

<code>
wvds.vscode.{name}/
├── pas/
│   ├── extension_main.pas      # Entry Point (PFLICHT)
│   ├── {Feature}.Models.pas    # Datenstrukturen
│   ├── {Feature}.Service.pas   # Geschäftslogik
│   └── {Feature}.Dialog.pas    # UI-Komponenten (optional)
│
├── dist/
│   ├── extension_main.js       # Kompiliertes JS
│   └── extension_main.js.map   # Source Map
│
├── templates/
│   └── *.html                  # WebView-Templates
│
├── images/
│   └── icon.png                # Extension-Icon
│
├── package.json                # VSCode-Manifest
├── build.cfg                   # Build-Konfiguration
└── README.md                   # Dokumentation
</code>

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

<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
  // Services initialisieren
  Initialize{Feature}Service;

  // Commands registrieren
  RegisterCommand('wvds.{feature}.{action}', @Handle{Action});

  // Output Channel
  ShowInfoMessage('WvdS {Name} aktiviert');
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>

===== Kommunikation zwischen Extensions =====

==== Via Shared Services ====

Extensions kommunizieren über die Core-Extension:

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

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

==== Via VSCode API ====

Für lose Kopplung:

<code pascal>
// Commands aufrufen
ExecuteCommand('wvds.build.run');

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

===== Build-Pipeline =====

<code>
┌──────────────────────────────────────────────────────────────┐
│                     BUILD PIPELINE                            │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  1. Policy-Check (wvds-lint)                                  │
│     - Keine .ts Dateien?                                      │
│     - Keine Duplikate?                                        │
│     - Wrapper nur in common?                                  │
│                                                               │
│  2. pas2js Kompilierung                                       │
│     - Unit-Auflösung                                          │
│     - Type-Checking                                           │
│     - JavaScript-Generierung                                  │
│                                                               │
│  3. Asset-Verarbeitung                                        │
│     - HTML-Templates kopieren                                 │
│     - Bilder optimieren                                       │
│     - package.json validieren                                 │
│                                                               │
│  4. Output                                                    │
│     - dist/extension_main.js                                  │
│     - dist/extension_main.js.map                              │
│                                                               │
│  5. VSIX-Packaging (optional)                                 │
│     - vsce package                                            │
│     - binaries/dist/*.vsix                                    │
│                                                               │
└──────────────────────────────────────────────────────────────┘
</code>

===== Siehe auch =====

  * [[.:pxaml-pipeline|PXAML-Pipeline]]
  * [[.:extension-architektur|Extension-Architektur im Detail]]
  * [[.:targets|Build-Targets]]
  * [[.:extension-entwicklung|Extension-Entwicklung]]