# 0002. ArchiveLink Content Server — backing storage

Date: 2026-04-15

## Status

Accepted

## Context

NOVA Invoice Suite implementa il protocollo SAP Content Server HTTP Interface 4.5 (`srv/integration/archivelink/ArchiveLinkContentServer.ts`) per esporre i documenti FatturaPA a S/4HANA tramite ArchiveLink. S/4 fa GET/POST/PUT/DELETE/HEAD/mCreate/attrSearch su NOVA come Content Server.

Lo storage backing è risolto via `DocumentAdapterFactory.getDocumentAdapter()` — qualsiasi adapter shipped può essere usato, ma serve scegliere il **default raccomandato** per documentazione, deployment templates, e scenari di onboarding customer.

Vincoli operativi:
- FatturaPA size: 50-100 KB XML + 5-50 KB PDF (tipico)
- Throughput peak: ~200 req/s su customer enterprise (anno fiscale chiusura)
- Latency budget: S/4 client timeout 30s, ma alert interni >500ms p99
- Retention operativa: ~5 anni (post-archive, S/4 livello caldo)
- Conservazione legale: separata su Conservatore italiano 10y (Blueprint 12)
- Multi-deployment: Kyma (primary), BTP CF, on-prem k3d, customer-hosted

Alternative considerate (matrix):

| Adapter | GET p50/p99 | POST p50/p99 | Cost scaling | Multi-deploy | Lock-in |
|---|---|---|---|---|---|
| `S3DocumentAdapter` (MinIO/S3) | 8/25 ms | 12/45 ms | Zero in-cluster | ✅ Kyma+CF+onprem | Nessuno |
| `FileSystemAdapter` (PVC) | 3/12 ms | 5/18 ms | Zero | ⚠️ Single-pod | Nessuno |
| `BTPDocumentAdapter` (DMS) | 35/180 ms | 70/350 ms | Per-volume | BTP CF only | BTP |
| `CMISDocumentAdapter` | 45/220 ms | 90/450 ms | Per-license | OK | Vendor CMS |
| `ArchiveLinkClientAdapter` | dipende dal CS cliente | — | — | OK | CS cliente |

## Decision

**Adottiamo `S3DocumentAdapter` (MinIO/S3) come default raccomandato** per il backing dell'ArchiveLink Content Server.

Configurazione canonica Kyma:

```yaml
DMS_ADAPTER: 's3'
DMS_S3_ENDPOINT: 'http://minio:9000'
DMS_S3_BUCKET: 'nova-archivelink'
DMS_S3_ACCESS_KEY: <from k8s secret>
DMS_S3_SECRET_KEY: <from k8s secret>
ARCHIVELINK_CS_ENABLED: 'true'
ARCHIVELINK_CS_VERIFY_SIGNATURE: 'true'
ARCHIVELINK_CS_PUBLIC_KEY: <S/4 STRUST cert PEM>
```

**Alternative supportate per scenari specifici** (non default):
- **Customer on-prem con NetApp / Pure / Dell ECS**: `s3` + endpoint customer S3-compatible
- **Customer "tutto BTP-managed"**: `btp` (accettiamo overhead, motivato da policy)
- **Customer ha già un CS dedicato (OpenText/SER)**: `archivelink` (NOVA è CLIENT, `ARCHIVELINK_CS_ENABLED=false`)

L'adapter è **pluggable runtime** via `SystemParameters.DMS_ADAPTER` — switch è una decisione di deploy, non richiede code change. La data migration tra adapter NON è automatica (script dedicato `scripts/dms-migration.sh` TBD).

Il backing **non è la conservazione legale**. Il documento dopo retention 5y resta accessibile via Conservatore (Blueprint 12) tramite il fallback chain in `sourceDocumentResolver.ts` § Stage 3.

## Consequences

### Positive

- **Zero cost in-cluster**: MinIO già presente per Conservatore archive → riutilizziamo
- **Latency 4-8x migliore** vs BTP DMS (8ms vs 35ms p50)
- **Multi-deployment uniforme**: stessa config funziona Kyma / BTP CF / on-prem
- **No vendor lock-in**: customer può sostituire MinIO con NetApp/Pure/Dell senza change code
- **Backup nativo**: MinIO bucket replication cross-region + lifecycle policy
- **Object key semantics naturale**: `<contRep>:<docId>:<compId>` mappa 1:1 a S3 key
- **Throughput**: 200 req/s sostenibile in-cluster (vs 50 req/s BTP DMS)

### Negative

- **Operations responsibility**: bucket creation/replication/lifecycle gestiti dal customer (non SAP-managed)
- **Backup compliance burden**: customer deve dimostrare retention policy a auditor (mitigato da MinIO lifecycle rules + audit log)
- **Onboarding step extra**: customer deve provisionare bucket prima del deploy (vs BTP DMS che è "binding e via")
- **Spazio**: archivelink storage può crescere fino a 500GB+ per anno fiscale enterprise → richiede pianificazione

### Neutral

- BTP DMS resta supported, ma documentato come "scelta motivata da policy", non default
- Customer che ha già un Content Server (Opzione D) non installa NOVA come CS — `ArchiveLinkClientAdapter` invece. Questo è un caso d'uso parallelo, non un'alternativa al backing.

## Alternatives considered

### Alternativa A — FileSystemAdapter (PVC) come default
**Scartata per produzione**: PVC è single-pod, multi-pod sharding manuale, backup via cronjob custom. OK per dev/test, non per prod multi-pod.

### Alternativa B — BTP DMS come default
**Scartata**: latency 4-8x peggiore, costo per-volume, lock-in BTP CF. Spreco di feature DMS (versioning, OData layer, search index) che NOVA non usa per ArchiveLink CS.

### Alternativa C — CMIS Bridge
**Scartata**: doppio bridge protocol (CS 4.5 → CMIS) → debugging complicato, latency aggiuntiva. CMIS ha senso solo se customer ha già repository CMIS-native non-S3.

### Alternativa D — Hybrid (S3 caldo + Glacier-like freddo)
**Deferred**: S3 lifecycle policy + cold tier (S3 Glacier / MinIO tiering) — interessante per 5y+ retention ma aggiunge complessità ops. Adottabile in futuro come parametro `DMS_S3_COLD_TIER_DAYS` senza ADR aggiuntivo.

## Operational checklist

Prima di abilitare `ARCHIVELINK_CS_ENABLED=true` in produzione:

- [ ] Backing storage configurato (MinIO bucket o BTP DMS comm arrangement)
- [ ] `ARCHIVELINK_CS_PUBLIC_KEY` caricato (PEM da S/4 STRUST cert)
- [ ] `ARCHIVELINK_CS_ALGORITHM` selezionato (DSA-SHA1 legacy / RSA-SHA256 modern)
- [ ] APIRule Kyma `/archivelink/{**}` con TLS termination + (raccomandato) mTLS
- [ ] S/4 OAC0 Content Repository configurato con URL = `https://nova.cluster/archivelink`
- [ ] S/4 CSADMIN cert exchange completato (cert NOVA → S/4 trust store)
- [ ] S/4 OACT linkage DocType ↔ Repository (es. `Z_FATPA` → BUS2081)
- [ ] S/4 OAA3 link object type ↔ DocType
- [ ] Smoke test E2E: S/4 GET /info + GET document via signed URL
- [ ] Backup policy attiva sul backing storage
- [ ] Cert rotation runbook (quarterly) calendarized in [TOKEN_ROTATION.md](../runbooks/TOKEN_ROTATION.md)
- [ ] Monitoring: alert su 4xx/5xx rate `/archivelink/*` + cert scadenza T-30d

## References

- ADR correlato: [0003. DMS S/4HANA integration](0003-dms-s4hana-integration.md)
- Implementation: [srv/integration/archivelink/ArchiveLinkContentServer.ts](../../srv/integration/archivelink/ArchiveLinkContentServer.ts)
- Signature verification: [srv/integration/archivelink/secKeyVerifier.ts](../../srv/integration/archivelink/secKeyVerifier.ts)
- S3 adapter: [srv/dms/S3DocumentAdapter.ts](../../srv/dms/S3DocumentAdapter.ts)
- Document analitico originale: [docs/architecture/archivelink-cs-storage-backing.md](../architecture/archivelink-cs-storage-backing.md)
- SAP Note 1854675 (PKCS#7 DSS), SAP Note 2002263 (SHA256 migration)
- [SAP Help: ArchiveLink Content Server URL Signing](https://help.sap.com/docs/SAP_NETWEAVER_750/19f8f05a3a934adc863a9b39bdd45ad9/4787c5dad9c70be9e10000000a4450e5.html)