====== Pregled arhitekture ======

Ta dokument opisuje celotno arhitekturo paketa WvdS FPC RAD Studio.

===== Oblikovalske odločitve =====

==== Zakaj Pascal za razširitve VS Code? ====

**Motivacija:**
  * Enotna kodna baza za vse cilje (GUI, TUI, Web, razširitve)
  * Močna tipizacija zmanjšuje napake med izvajanjem
  * Izkoriščanje znanja razvijalcev iz obstoječih projektov Pascal
  * pas2js omogoča visokokakovosten izhod JavaScript

**Obravnavane alternative:**
^ Alternativa ^ Odločitev ^ Utemeljitev ^
| TypeScript | Zavrnjeno | Dva jezika, več kompleksnosti |
| Rust + WASM | Zavrnjeno | Kompleksna interoperabilnost z VSCode API |
| Delphi | Zavrnjeno | Komercialno, brez alternative pas2js |

==== Zakaj PXAML namesto LFM? ====

**Motivacija:**
  * Nadzor različic: XML je prijazen do diff
  * Več ciljev: Enako označevanje za GUI, TUI, Web
  * Orodja: Na voljo standardni razčlenjevalniki XML
  * Znano: Sintaksa WPF/XAML za prehajanje

===== Slojevita arhitektura =====

<code>
┌─────────────────────────────────────────────────────────────────────┐
│                        Extension Layer                               │
│  (extension_main.pas - Entry Point, Command Handler, UI Integration) │
├─────────────────────────────────────────────────────────────────────┤
│                        Service Layer                                 │
│  (*.Service.pas - Poslovna logika, validacija, operacije)           │
├─────────────────────────────────────────────────────────────────────┤
│                        Model Layer                                   │
│  (*.Models.pas - Zapisi, tipi, enumeracije, brez logike)            │
├─────────────────────────────────────────────────────────────────────┤
│                     Infrastructure Layer                             │
│  (WvdS.VSCode.*, WvdS.Node.* - API Wrapper, Platform Abstraction)    │
└─────────────────────────────────────────────────────────────────────┘
</code>

==== Odgovornosti ====

^ Sloj ^ Vsebina ^ Odvisnosti ^
| Extension | Interakcija z UI, registracija ukazov | Service, Model, Infrastructure |
| Service | Poslovna logika, validacija | Model |
| Model | Podatkovne strukture | Brez |
| Infrastructure | VSCode/Node API | Samo zunanji API |

==== Pravila ====

<code>
DOVOLJENO:   Extension -> Service -> Model
PREPOVEDANO:  Service -> Extension (obrat)
PREPOVEDANO:  Model -> Service (logika v Model)
</code>

===== Graf odvisnosti =====

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

==== Podrobnosti odvisnosti razširitev ====

^ Razširitev ^ Odvisnosti ^ Vloga ^
| core | - | Osnova: Toolchain, beleženje, skupne storitve |
| build | core | Prevajanje, formater Uses |
| projects | core | Upravljanje projektov, predloge |
| ui.meta | core | Register komponent |
| ui.designer | core | Urejevalnik PXAML |
| ui.preview | core, ui.designer | Živi predogled |
| packaging | core, build | Ustvarjanje VSIX |

===== Struktura Monorepo =====

==== sources/ - Enoten vir resnice ====

<code>
sources/
├── common/                     # Skupna koda
│   ├── core/                   # Osnovne enote (brez odvisnosti)
│   │   ├── WvdS.System.pas
│   │   ├── WvdS.Collections.pas
│   │   └── WvdS.Strings.pas
│   │
│   ├── ui/                     # UI ogrodje
│   │   ├── controls/           # Osnovni kontrolniki
│   │   ├── components/         # Sestavljene komponente
│   │   ├── runtime/            # PXAML Runtime
│   │   └── targets/            # Upodabljalniki
│   │       ├── tui/            # Terminal UI
│   │       ├── gui/            # Desktop GUI
│   │       └── web/            # Brskalnik
│   │
│   └── web/                    # Host Bridges
│       ├── nodejs/             # Node.js API
│       └── vscode/             # VSCode API
│
├── extensions/                 # Paketi VSIX
│   └── wvds.vscode.{name}/
│       ├── pas/                # Izvorna koda Pascal
│       ├── dist/               # Prevedeni JS
│       ├── templates/          # Predloge HTML
│       ├── images/             # Ikone, grafike
│       ├── package.json        # Manifest razširitve
│       └── build.cfg           # Konfiguracija gradnje
│
├── applications/               # Samostojne aplikacije
├── tools/                      # CLI orodja
└── packages/                   # Paketi IDE
</code>

==== binaries/ - Izhod gradnje ====

<code>
binaries/
├── out/{app}/{target}/{mode}/  # Artefakti gradnje
│   ├── gen/                    # Generirana koda
│   ├── bin/                    # Izvršljive datoteke
│   └── assets/                 # Viri
│
├── cache/                      # Predpomnilnik prevajalnika (.ppu, .o)
├── dist/                       # Artefakti izdaje (.vsix)
└── logs/                       # Dnevniki gradnje
</code>

===== Anatomija razširitve =====

==== Struktura map ====

<code>
wvds.vscode.{name}/
├── pas/
│   ├── extension_main.pas      # Vstopna točka (OBVEZNO)
│   ├── {Feature}.Models.pas    # Podatkovne strukture
│   ├── {Feature}.Service.pas   # Poslovna logika
│   └── {Feature}.Dialog.pas    # UI komponente (opcijsko)
│
├── dist/
│   ├── extension_main.js       # Prevedeni JS
│   └── extension_main.js.map   # Source Map
│
├── templates/
│   └── *.html                  # Predloge WebView
│
├── images/
│   └── icon.png                # Ikona razširitve
│
├── package.json                # Manifest VSCode
├── build.cfg                   # Konfiguracija gradnje
└── README.md                   # Dokumentacija
</code>

==== Vzorec 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
  // Inicializacija storitev
  Initialize{Feature}Service;

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

  // Izhodni kanal
  ShowInfoMessage('WvdS {Name} aktiviran');
end;

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

procedure Deactivate;
begin
  // Čiščenje
end;

initialization
  ExportActivateDeactivate(@Activate, @Deactivate);

end.
</code>

===== Komunikacija med razširitvami =====

==== Preko skupnih storitev ====

Razširitve komunicirajo preko razširitve Core:

<code pascal>
// V razširitvi A
CoreService.PublishEvent('build.completed', BuildResult);

// V razširitvi B
CoreService.SubscribeEvent('build.completed', @OnBuildCompleted);
</code>

==== Preko VSCode API ====

Za šibko sklopljenost:

<code pascal>
// Klic ukazov
ExecuteCommand('wvds.build.run');

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

===== Cevovod gradnje =====

<code>
┌──────────────────────────────────────────────────────────────┐
│                     CEVOVOD GRADNJE                          │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  1. Preverjanje politike (wvds-lint)                         │
│     - Brez datotek .ts?                                       │
│     - Brez dvojnikov?                                         │
│     - Wrapperji samo v common?                                │
│                                                               │
│  2. Prevajanje pas2js                                         │
│     - Razreševanje enot                                       │
│     - Preverjanje tipov                                       │
│     - Generiranje JavaScript                                  │
│                                                               │
│  3. Obdelava sredstev                                         │
│     - Kopiranje predlog HTML                                  │
│     - Optimizacija slik                                       │
│     - Validacija package.json                                 │
│                                                               │
│  4. Izhod                                                     │
│     - dist/extension_main.js                                  │
│     - dist/extension_main.js.map                              │
│                                                               │
│  5. Pakiranje VSIX (opcijsko)                                 │
│     - vsce package                                            │
│     - binaries/dist/*.vsix                                    │
│                                                               │
└──────────────────────────────────────────────────────────────┘
</code>

===== Glejte tudi =====

  * [[.:pxaml-pipeline|Cevovod PXAML]]
  * [[.:extension-architektur|Podrobna arhitektura razširitev]]
  * [[.:targets|Cilji gradnje]]
  * [[.:extension-entwicklung|Razvoj razširitev]]