boc/landvex-plugin-architecture.md

# LandveX Enterprise Platform — Plugin-arkitektur

## Sammanfattning

En modulär, säker och kommunvänlig plugin-arkitektur som gör det enkelt för kommuner att integrera LandveX med befintliga system (ERP, GIS, ärendehantering) utan att kompromissa med säkerhet eller underhållbarhet.

---

## 1. Arkitekturskiss

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         LandveX Enterprise Platform                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   Core      │  │   Auth      │  │   Events    │  │   Plugin Manager    │ │
│  │   Engine    │  │   Service   │  │   Bus       │  │   (Lifecycle, API)  │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
│         │                │                │                    │            │
│         └────────────────┴────────────────┴────────────────────┘            │
│                                    │                                        │
│                         ┌──────────┴──────────┐                            │
│                         │   Plugin Sandbox    │                            │
│                         │  (Isolerad runtime) │                            │
│                         └──────────┬──────────┘                            │
│                                    │                                        │
│  ┌─────────────────────────────────┼─────────────────────────────────────┐ │
│  │         Plugin API Layer        │                                     │ │
│  │  ┌─────────┐ ┌─────────┐ ┌─────┴────┐ ┌─────────┐ ┌─────────────┐   │ │
│  │  │  Data   │ │  Auth   │ │  Events  │ │ Config  │ │  Logging    │   │ │
│  │  │  API    │ │  API    │ │  API     │ │  API    │ │  API        │   │ │
│  │  └────┬────┘ └────┬────┘ └────┬─────┘ └────┬────┘ └─────┬───────┘   │ │
│  └───────┼───────────┼───────────┼────────────┼────────────┼───────────┘ │
│          │           │           │            │            │              │
│  ┌───────┴───────────┴───────────┴────────────┴────────────┴───────────┐  │
│  │                    Plugin Registry & Store                           │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │  │
│  │  │  Visma   │ │  Agresso │ │  ArcGIS  ││  QGIS    │ │  SUST    │   │  │
│  │  │  Plugin  │ │  Plugin  │ │  Plugin  ││  Plugin  │ │  Plugin  │   │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘   │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Komponenter

| Komponent | Beskrivning |
|-----------|-------------|
| **Core Engine** | LandveX kärnplattform, affärslogik och datahantering |
| **Auth Service** | Centraliserad autentisering och auktorisation (OAuth2/OIDC) |
| **Event Bus** | Asynkron händelsebuss för kommunikation mellan komponenter |
| **Plugin Manager** | Livscykelhantering: installera, starta, stoppa, uppdatera, avinstallera |
| **Plugin Sandbox** | Isolerad runtime (WebAssembly/containers) för plugin-exekvering |
| **Plugin API Layer** | Standardiserade API:er som alla plugins använder |
| **Plugin Registry** | Katalog över tillgängliga och installerade plugins |

---

## 2. Plugin-API-specifikation

### 2.1 Plugin-manifest (`plugin.yaml`)

```yaml
apiVersion: landvex.io/plugin/v1
kind: Plugin
metadata:
  name: visma-erp-connector
  version: 2.1.0
  vendor: LandveX AB
  category: erp
  tags: [visma, ekonomi, fakturering]
  
spec:
  # Beskrivning för kommunadministratörer
  displayName: "Visma Ekonomi Integration"
  description: "Integrerar LandveX med Visma Administration och Visma.net"
  
  # Beroenden
  requires:
    landvex: ">= 4.2.0"
    plugins: []
  
  # API-version som plugin använder
  apiVersion: "v1"
  
  # Behörigheter som plugin begär
  permissions:
    - resource: data/economy
      actions: [read, write]
    - resource: events/economy.*
      actions: [publish, subscribe]
    - resource: config/plugin/visma-erp
      actions: [read, write]
  
  # Konfigurationsschema (JSON Schema)
  configSchema:
    type: object
    properties:
      apiEndpoint:
        type: string
        format: uri
        description: "Visma API endpoint"
      clientId:
        type: string
        description: "OAuth2 Client ID"
      syncInterval:
        type: integer
        default: 3600
        description: "Synkroniseringsintervall i sekunder"
    required: [apiEndpoint, clientId]
  
  # Hälsokontroll
  healthCheck:
    path: /health
    interval: 30
  
  # Resursgränser
  resources:
    memory: "256Mi"
    cpu: "500m"
    timeout: 30
```

### 2.2 Core API:er

#### Data API
```typescript
interface DataAPI {
  // Läsa data med query
  query<T>(collection: string, filter: QueryFilter): Promise<T[]>;
  
  // Läsa enskild entitet
  get<T>(collection: string, id: string): Promise<T | null>;
  
  // Skriva data (kräver write-behörighet)
  create<T>(collection: string, data: T): Promise<T>;
  update<T>(collection: string, id: string, data: Partial<T>): Promise<T>;
  delete(collection: string, id: string): Promise<void>;
  
  // Transaktioner
  transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
}
```

#### Auth API
```typescript
interface AuthAPI {
  // Verifiera användartoken
  verifyToken(token: string): Promise<UserContext>;
  
  // Kontrollera behörighet
  checkPermission(user: UserContext, resource: string, action: string): Promise<boolean>;
  
  // Hämta användarens organisation
  getOrganization(user: UserContext): Promise<Organization>;
  
  // Plugin-egen identitet (service account)
  getServiceAccount(): Promise<ServiceAccount>;
}
```

#### Events API
```typescript
interface EventsAPI {
  // Publicera händelse
  publish(event: Event): Promise<void>;
  
  // Prenumerera på händelser
  subscribe(pattern: string, handler: EventHandler): Subscription;
  
  // Schemalägg återkommande jobb
  schedule(cron: string, job: ScheduledJob): JobHandle;
}

interface Event {
  type: string;           // t.ex. "economy.invoice.created"
  source: string;         // plugin-id
  timestamp: ISO8601;
  payload: unknown;
  correlationId?: string;
}
```

#### Config API
```typescript
interface ConfigAPI {
  // Hämta plugin-konfiguration (krypterad vid behov)
  get<T>(key: string): Promise<T>;
  
  // Sätt konfiguration
  set<T>(key: string, value: T): Promise<void>;
  
  // Validera mot schema
  validate(config: unknown): Promise<ValidationResult>;
}
```

### 2.3 Plugin SDK (TypeScript)

```typescript
import { Plugin, DataAPI, EventsAPI } from '@landvex/plugin-sdk';

export default class VismaPlugin implements Plugin {
  private data: DataAPI;
  private events: EventsAPI;
  private config: ConfigAPI;

  async initialize(context: PluginContext): Promise<void> {
    this.data = context.data;
    this.events = context.events;
    this.config = context.config;
  }

  async start(): Promise<void> {
    // Prenumerera på händelser
    this.events.subscribe('economy.invoice.*', async (event) => {
      await this.syncToVisma(event.payload);
    });

    // Schemalägg synkronisering
    this.events.schedule('0 */6 * * *', async () => {
      await this.fullSync();
    });
  }

  async stop(): Promise<void> {
    // Cleanup
  }

  async health(): Promise<HealthStatus> {
    const vismaStatus = await this.checkVismaConnection();
    return {
      status: vismaStatus.ok ? 'healthy' : 'unhealthy',
      details: vismaStatus
    };
  }

  private async syncToVisma(invoice: Invoice): Promise<void> {
    // Implementera synkronisering
  }
}
```

---

## 3. Färdiga plugins — exempel

### 3.1 Visma Ekonomi Integration (ERP)

```yaml
# plugin.yaml
metadata:
  name: visma-erp-connector
  category: erp
  
spec:
  displayName: "Visma Ekonomi"
  description: "Synkroniserar fakturor, leverantörsreskontra och betalningar med Visma"
  
  permissions:
    - resource: data/invoices
      actions: [read, write]
    - resource: data/suppliers
      actions: [read, write]
    - resource: events/economy.*
      actions: [publish, subscribe]
  
  configSchema:
    properties:
      vismaProduct:
        type: string
        enum: ["visma-administration", "visma-net", "visma-business"]
      apiEndpoint:
        type: string
      syncDirection:
        type: string
        enum: ["to-visma", "from-visma", "bidirectional"]
        default: "bidirectional"
```

**Funktioner:**
- Automatisk fakturasynkronisering
- Leverantörsreskontra i realtid
- Stöd för Visma Administration, Visma.net och Visma Business
- Avstämning av betalningar
- Momsrapportering

### 3.2 ArcGIS/QGIS Integration (GIS)

```yaml
# plugin.yaml
metadata:
  name: gis-connector
  category: gis
  
spec:
  displayName: "GIS Integration"
  description: "Kopplar samman fastighetsdata med geografisk information"
  
  permissions:
    - resource: data/properties
      actions: [read]
    - resource: data/maps
      actions: [read, write]
    - resource: events/property.*
      actions: [subscribe]
  
  configSchema:
    properties:
      gisProvider:
        type: string
        enum: ["arcgis", "qgis-server", "geoserver"]
      wmsEndpoint:
        type: string
      layerMappings:
        type: array
        items:
          type: object
          properties:
            landvexType: string
            gisLayer: string
```

**Funktioner:**
- Visualisering av fastigheter på karta
- Lagerhantering (byggnader, tomter, zonering)
- Import/export av GeoJSON/Shapefile
- Realtidsuppdatering vid fastighetsförändringar
- Mätk verktyg och areaberäkning

### 3.3 SUST Ärendehantering Integration

```yaml
# plugin.yaml
metadata:
  name: sust-case-connector
  category: case-management
  
spec:
  displayName: "SUST Ärendehantering"
  description: "Integrerar bygglov och förvaltningsärenden med SUST"
  
  permissions:
    - resource: data/cases
      actions: [read, write]
    - resource: data/case-types
      actions: [read]
    - resource: events/case.*
      actions: [publish, subscribe]
  
  configSchema:
    properties:
      sustEndpoint:
        type: string
      caseTypeMappings:
        type: object
        additionalProperties:
          type: string
```

**Funktioner:**
- Skapa ärenden i SUST från LandveX
- Statussynkronisering i realtid
- Dokumentöverföring
- Automatiska påminnelser och eskalering
- Rapportering och statistik

---

## 4. Säkerhet och accesskontroll

### 4.1 Säkerhetsmodell

```
┌─────────────────────────────────────────┐
│           Säkerhetslager                │
├─────────────────────────────────────────┤
│  1. Nätverksisolering                 │
│     - Plugin sandbox i separat nätverk │
│     - Endast utgående trafik till      │
│       godkända endpoints               │
├─────────────────────────────────────────┤
│  2. Runtime-isolering                  │
│     - WebAssembly eller containers     │
│     - CPU/minnesgränser per plugin     │
│     - Timeout på alla operationer      │
├─────────────────────────────────────────┤
│  3. API-behörigheter                   │
│     - Deklarativa permissions i manifest│
│     - RBAC (Role-Based Access Control) │
│     - Principen om minsta privilegium  │
├─────────────────────────────────────────┤
│  4. Datakryptering                     │
│     - Krypterad lagring av secrets     │
│     - TLS för all extern kommunikation │
│     - Fältnivåkryptering vid behov     │
├─────────────────────────────────────────┤
│  5. Audit logging                      │
│     - Alla API-anrop loggas            │
│     - Spårbarhet av dataändringar      │
│     - SIEM-integration                 │
└─────────────────────────────────────────┘
```

### 4.2 Autentisering flöde

```
┌─────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────┐
│  Plugin │────▶│  Plugin     │────▶│  Auth       │────▶│  Core   │
│         │     │  Manager    │     │  Service    │     │  API    │
└─────────┘     └─────────────┘     └─────────────┘     └─────────┘
     │                │                   │                  │
     │ 1. Starta med  │                   │                  │
     │    service acc │                   │                  │
     │───────────────▶│                   │                  │
     │                │ 2. Hämta token    │                  │
     │                │──────────────────▶│                  │
     │                │                   │ 3. Verifiera     │
     │                │                   │    mot IdP       │
     │                │                   │─────────────────▶│
     │                │                   │◀─────────────────│
     │                │◀──────────────────│                  │
     │◀───────────────│                   │                  │
     │ 4. JWT token   │                   │                  │
     │    för API-    │                   │                  │
     │    anrop       │                   │                  │
```

### 4.3 Signering och verifiering

Alla plugins måste vara signerade:

```bash
# Signera plugin
landvex plugin sign \
  --plugin ./visma-erp-connector.lvpkg \
  --key /secure/signing-key.pem \
  --cert /secure/signing-cert.pem

# Verifiera vid installation
landvex plugin install \
  --source ./visma-erp-connector.lvpkg \
  --verify --trust-store /etc/landvex/trusted-certs
```

---

## 5. Drift och underhåll för kommuner

### 5.1 Installation (ett kommando)

```bash
# Via CLI
landvex plugin install visma-erp-connector --version 2.1.0

# Via webbgränssnitt
# Admin → Plugins → Marknadsplats → Installera

# Automatisk uppdatering
landvex plugin update --auto --channel stable
```

### 5.2 Konfiguration

```bash
# Interaktiv konfiguration
landvex plugin config visma-erp-connector --interactive

# Eller via fil
landvex plugin config visma-erp-connector --file ./visma-config.yaml
```

### 5.3 Övervakning

```bash
# Plugin-status
landvex plugin status

# Loggar
landvex plugin logs visma-erp-connector --follow

# Hälsokontroll
landvex plugin health visma-erp-connector
```

### 5.4 Backup/Återställning

```bash
# Exportera plugin-konfiguration
landvex plugin export visma-erp-connector --output ./backup/

# Importera
landvex plugin import ./backup/visma-erp-connector-backup.tar.gz
```

---

## 6. Plugin-paketstruktur

```
visma-erp-connector.lvpkg (zip/tar.gz)
├── plugin.yaml              # Manifest
├── dist/
│   ├── index.js             # Plugin-kod
│   ├── index.wasm           # Om WebAssembly
│   └── assets/              # Statiska resurser
├── migrations/              # Databasmigrationer
│   ├── 001_initial.sql
│   └── 002_add_indexes.sql
├── tests/
│   └── integration.test.js
├── docs/
│   ├── README.md
│   └── CONFIGURATION.md
└── signatures/
    └── manifest.sig         # Kryptografisk signatur
```

---

## 7. Versionshantering och kompatibilitet

| LandveX-version | API-version | Kompatibilitet |
|----------------|-------------|----------------|
| 4.x            | v1          | ✅ Stöds       |
| 5.x            | v2          | 🔄 Planerad    |

Plugins deklarerar vilken LandveX-version de kräver. Plugin Manager verifierar kompatibilitet vid installation.

---

## 8. Sammanfattning av fördelar

| Aspekt | Lösning |
|--------|---------|
| **Enkelhet** | Ett kommando för installation, webbgränssnitt för konfiguration |
| **Standardisering** | Gemensamma API:er för alla integrationer |
| **Säkerhet** | Sandbox, RBAC, signering, audit logging |
| **Skalbarhet** | Isolerade plugins med resursgränser |
| **Underhåll** | Automatiska uppdateringar, health checks |
| **Extensibilitet** | Öppet SDK för tredjepartsutvecklare |

---

*Dokumentversion: 1.0*
*Senast uppdaterad: 2026-07-02*