Arhitectura Iris — v2

v2 · 24 August 2026 · încorporează review-ul Prodi + fluxul Nucleului · sursa: iris-arhitectura.md

24 August 2026 · v2 — încorporează review-ul Prodi (24 Aug) + reîncadrarea proiectului · BONO × SOLO · Confidențial Autor: BGN + Claude · Complementar cu prd-iris-mvp-manual.md (spec-ul funcțional al Fazei 1)

0. Contextul v2: un experiment, spus explicit

Iris este și un test de organizație: un modul dezvoltat de BGN + Claude Code, cu ajutorul echipei IT pe arhitectură (acest document e dovada — review-ul Prodi a schimbat v1 în bine), dar fără implicare de implementare sau mentenanță din partea echipei.

Criteriile de decizie derivate din acest obiectiv, aplicate consecvent în tot documentul:

Simplitate — cât mai puține piese mobile; capabilități native ale serviciilor, nu add-on-uri construite de noi
Zero operare umană — totul pe servicii gestionate (managed); nimeni nu e on-call
Reparabil de Claude Code — totul e cod în repo + servicii accesibile prin CLI/API; niciun click-in-consolă nereproductibil
Integrare cu platforma BONO exclusiv prin API — Iris consumă serviciile ecosistemului (iam, directory, forex) prin contracte; nu rulează pe infrastructura echipei și nu-i cere nimic operațional

Ținta de scalare rămâne neschimbată din v1: zeci de mii de clienți finali, sute de mii de documente/lună (~750k/lună ≈ 2–3 doc/sec la vârf), cu plafonul arhitecturii la 10–15× peste țintă.

Cine este „tenantul" — fluxul documentelor (decizia Nucleului, 4 aug 2026, BGN + Prodi)

Iris nu vorbește cu shell-urile (Dublin, Vertigo, Falcon). Per organizație există un singur sistem-partener:

Clientul încarcă în Dublin ──┐
SPV / eFactură ──────────────┤
Facturare (emise) ───────────┼──▶  NUCLEU (BONO)  ──▶ ProcessingRequest ──▶ IRIS
Extrase (upload/OpenBanking)─┘    system of record:                          │
                                   stochează documentele,                    │
                                   registrul firmelor,        ◀── note ──────┘
                                   jurnalul de evenimente
                                        │
                          Dublin și Vertigo citesc din Nucleu

BONO: tenantul = Nucleul (system of record + hub — decizia din 4 aug; detalii pe dublin.bgn.ro/prd, tabul Arhitectura §4.0.c). *Interim, până e gata Nucleul: backend-ul Vertigo, pe același contract.*
SOLO: tenantul = backend-ul Jedi.
Consecință: un singur punct de integrare, o pereche de credențiale iam și un consumator de webhooks per tenant; contractele Tenant-in/Tenant-out rămân neschimbate indiferent cine e apelantul.
De sincronizat cu Prodi: calendarul Nucleului vs. calendarul pilotului Iris (cine e primul apelant real).

Changelog v1 → v2

Subiect	v1	v2	Sursa deciziei
Stack backend	de decis (propus .NET)	.NET 10, stil minimal modern	Prodi confirmă; dezbaterea TS vs .NET tranșată pe merite (vezi §1)
Baza de date	Postgres (nespecificat)	Neon — Postgres gestionat, Frankfurt	criteriul zero-ops; capabilități native (RLS)
Compute	de decis	Railway (containere Linux, UE)	criteriul zero-ops; deploy prin CLI
Storage documente	S3-compatibil	Cloudflare R2 (UE), swap path AWS S3 documentat	simplitate + cont existent; API S3-compatibil
Autentificare tenant	chei API în Iris	OAuth2 M2M via iam.bono.ro; Iris = resource server	Prodi — serviciu existent
ANAF / BNR	cache construit în Iris	directory.bono.ro + forex.bono.ro (existente, cache-uite)	Prodi — servicii existente
Criptare documente	envelope + crypto-shredding	doar SSE la storage; fără criptare aplicativă în v1	Prodi — cost/simplitate; condiție: fereastra de backup în DPA
Nr. afișare BN-YYYY-NNNNN	schiță	mecanica Prodi + decizii: NU gapless; anul = data ingestului	Prodi (mecanică) + BGN (decizii)
HA / failover DB	primary + replică	gestionat de Neon (PITR din bifă); nimic de operat	dizolvat de alegerea managed
Bulk import	de decis	manifest NDJSON + presigned URLs (de validat cu SOLO)	propunere BGN, aliniată la reformularea Prodi

1. Stack: .NET 10 minimal + React/TypeScript

Backend: .NET 10 — decizie luată după o dezbatere reală TS vs. .NET, câștigată de .NET pe argumente, nu pe conformism:

Lanțul de aprovizionare (argumentul decisiv): biblioteca standard .NET acoperă HTTP, JSON, criptografie, DI, logging, scheduling — dependențe externe de ~10× mai puține decât echivalentul npm. Pentru un sistem cu date financiare, suprafața supply-chain e decizie de securitate de rangul 1.
Tipuri reale la runtime — modelul canonic de date (piesa centrală cerută de review) nu poate fi „mințit" la execuție.
Stabilitate de corpus — un singur fel canonic de a face lucrurile (vs. straturile geologice ale ecosistemului JS); Claude Code scrie C# modern la același nivel cu TS.
Reziliența ca infrastructură — Polly (circuit breaker, retry, timeout), OpenTelemetry, workers — mature și integrate.

Stilul: .NET modern minimal, nu convențiile istorice ale platformei — minimal APIs + EF Core + records + Guid.CreateVersion7(); explicit NU NHibernate/hbm.xml/CQRS ceremonios. Luăm limbajul echipei, nu tot bagajul — zona de maxim corpus pentru Claude Code.

Invariant de dependențe (răspuns la supply chain, valabil și în .NET): lista de pachete externe rămâne scurtă (<15), fixată în versiuni, auditată în CI la fiecare PR.

Frontend: React 19 + TypeScript (Workbench-ul operatorului), cu clientul de API generat din OpenAPI — modelul canonic are o singură sursă de adevăr (C#), tipurile frontend derivă mecanic.

Forma aplicației: monolit modular cu porturi — neschimbat din v1:

Iris (.NET 10, un serviciu + workers)
├── Ingest        — API tenant, validare, dedup hash, triaj
├── Storage       — fișiere (R2), retenție, presigned URLs
├── Workbench API — coada de lucru, conspectare, interpretare, dubii
├── Engines       — porturile IExtraction / IInterpretation / IRules + routerul de cascadă
├── Rules         — taxonomia + tabelul Adam, versionate
├── Memory        — istoricul per (tenant, client, furnizor, descriere)
├── Export        — outbox, webhooks, GET note
├── Identity      — RBAC operatori umani (tenants/chei = iam.bono.ro, NU aici)
└── Telemetry     — evenimente, metrici, cost/doc, SLO

Porturile motoarelor (contracte care rulează din ziua 1, cu implementări manuale în Faza 1) și cele 5 contracte cu regulile lor (schema_version, doar aditiv, confidence nullable, trace_id, fixtures de aur) — neschimbate din v1.

2. Coloana vertebrală: evenimente + proiecții + outbox — neschimbată

Jurnalul de evenimente = sursa adevărului; tabelele de stare = proiecții. Transactional outbox pentru tot ce iese (webhooks semnate, retry + backoff, consum idempotent). Corecțiile post-export = evenimente noi (nota.corrected), notele emise sunt imutabile. Audit record-ul imutabil = evenimente. *(Detalii în v1 — secțiunea rămâne integral valabilă.)*

3. Date: Neon (Postgres gestionat, Frankfurt)

De ce Postgres gestionat, după ce review-ul propusese MariaDB: argumentele MariaDB („echipa o operează", „standardul platformei") nu se aplică unui modul pe care echipa nu îl operează. Sub criteriile §0 câștigă Postgres:

Row-Level Security nativă — izolarea tenanților garantată de motor. Păstrăm și stratul propus de Prodi (gateway-ul de acces care injectează tenant_id, plus test de izolare în CI) → două straturi independente de apărare.
Partiționare declarativă pe lună (events, documents, lines) de la prima migrare; coada în Postgres (FOR UPDATE SKIP LOCKED) cu fairness per tenant; JSONB pe evenimente; UUIDv7 ca PK intern.
Operare zero: backup + point-in-time recovery din bifă (fereastra de retenție = setare, documentată în DPA), failover gestionat de Neon → punctul „single primary fără HA" din review se dizolvă: primim protecția fără să operăm nimic.
Branching de bază — orice migrare se testează pe o ramură a bazei reale, apoi se aruncă (fluxul natural de lucru cu Claude Code).

Anexă de compatibilitate MariaDB (din maparea Prodi, păstrată ca plan de portare): mecanica secvențelor, partiționarea RANGE, SKIP LOCKED (10.6+), UUID — toate există și în MariaDB; singura piesă fără echivalent e RLS, compensată exact de stratul aplicativ pe care îl păstrăm oricum. Dacă Iris e predat vreodată echipei și se dorește alinierea la platformă, portarea pierde doar stratul redundant, nu modelul de securitate.

Numărul de afișare BN-2026-00003 — mecanica din review, adoptată integral: rând de secvență (tenant, an) cu SELECT … FOR UPDATE în aceeași tranzacție cu insertul; tranzacție minimă (zero procesare sub lock); alocare după dedup; ordinea lock-urilor consecventă. Deciziile cerute: (1) NU gapless — e handle de afișare/tracking, numerele fiscale reale rămân pe documentele originale; (2) anul = data ingestului — importurile istorice primesc numere în anul curent, în ordinea intrării.

Memoria = tabele normale cu exact-match pe (tenant, client, furnizor_cui, descriere_normalizată) — fără vector DB în v1. Retenție: 12 luni rolling, automată (politici în DB + lifecycle în R2).

4. Compute: Railway (containere Linux, regiunea UE)

API-ul + workerii (coadă, outbox, cron) rulează ca containere .NET pe Railway: deploy dintr-o comandă, loguri/restart/secrete prin CLI — integral operabil de Claude Code. Workbench-ul (SPA React) pe Vercel (fluxul și domeniul există deja). Preview environments: branch de cod (Railway/Vercel) + branch de bază (Neon) = un Iris complet de test per schimbare.

Fluxul, cozile și eșecurile — neschimbate din v1: totul asincron (202 + id instant), idempotență peste tot, fairness per tenant, dead-letter pentru poison documents, circuit breakers. Dependențele externe devin serviciile interne BONO (per review): directory.bono.ro (ANAF, cache-uit) și forex.bono.ro (BNR) — consumate prin porturile ICompanyDirectory / IForexProvider, endpoint-uri în config; indisponibilitate → flag „neverificat", nu blocare. SLO-uri per tenant, măsurate din evenimente, calibrate onest la modelul de operare (natura asincronă iartă: dacă Iris e jos o oră, tenantul retrimite, nimic nu se pierde).

Observabilitate: loguri structurate cu trace_id propagat cap-coadă + un serviciu gestionat de logging (Axiom / Better Stack) — Claude citește logurile prin API când depanează.

5. Storage documente: Cloudflare R2 (UE), cu swap path S3

Criptare la repaus implicită (mereu pornită), TLS în tranzit, token-uri scoped per bucket, presigned URLs cu viață scurtă, prefix per tenant, jurisdicție UE setată explicit (GDPR), lifecycle policy pentru retenția de 12 luni.
Fără criptare aplicativă în v1 (decizia din review, adoptată): consecința — ștergerea GDPR = ștergere reală + expirarea backup-urilor; fereastra de retenție a backup-urilor (R2 + Neon) se fixează la un număr concret (propunere: 30 zile) și se scrie în DPA — ea este, de facto, termenul de ștergere completă.
Swap path documentat: API-ul fiind S3-compatibil, mutarea pe AWS S3 (dacă apare vreodată o cerință de Object Lock / SSE-KMS pentru conformitate avansată) e schimbare de endpoint + credențiale, nu de cod. Auditul imutabil trăiește oricum în jurnalul de evenimente din DB, nu în storage.
Costuri la țintă: ~70 $/lună (stocare) + egress gratuit.

6. Securitate

Perimetru / autentificare tenant: OAuth2 M2M via iam.bono.ro (per review): tenantul schimbă (client key, secret) pe JWT; Iris = resource server — validează token-ul (JWKS local + TTL scurt), nu stochează nicio credențială de tenant; tenant_id vine exclusiv din claim-urile validate; rate limiting pe claim.
Izolare: RLS în Postgres + gateway-ul aplicativ + test de izolare în CI (două straturi + verificare mecanică).
Webhooks outbound: semnate HMAC cu secret per tenant, generat la onboarding, ținut în secrets-ul Railway (iam nu acoperă direcția outbound).
Oameni: SSO + 2FA operatori; operatorul vede doar coada tenantului lui; fără export bulk pentru operatori; CNP/IBAN mascate unde nu servesc deciziei; access log append-only pe vizualizări; accesul cross-tenant (Admin Iris) logat integral.
AI: taxonomie închisă (output validat ca enum — apărarea structurală anti prompt-injection), deciziile cu bani la motorul determinist, minimizare în prompt, zero-data-retention + DPA cu Anthropic.
Supply chain: invariantul de dependențe din §1 + audit automat în CI.
Conformitate: GDPR acum (Iris = împuternicit; DPA per tenant — avocat; harta datelor; retenție automată; fereastra de backup ca termen de erasure); SOC 2 mai târziu, cu obiceiurile pornite de acum (schimbări doar prin PR, loguri păstrate, fără date reale în dev).
Cerere punctuală către echipa IT (singura): un security review one-off pe perimetru (integrarea iam + expunerea API) înainte de pilot.

7. Economia procesării — neschimbată din v1

Piramida: determinist (parsare + istoric + reguli, cost 0) → Haiku → Sonnet → om (ordinele de mărime: omul e 100× AI-ul scump). Zero-Touch-ul ieftin vine din memorie, nu din inteligență. Lansare cu un singur model (Sonnet); routerul de cascadă există din ziua 1; cascada se activează pe felii, pe datele eval dataset-ului. Shadow mode + feature flags per tenant × categorie = mecanismul de conectare a motoarelor (niciun motor nu primește frâiele direct). Cost/doc = metrică de gradul 1 în Telemetry.

8. Riscurile modelului de operare — spuse onest

Bus factor = BGN. Mitigare: totul în repo (config, migrări, politici — reproductibil), contracte curate, documentele vii pe iris.bgn.ro. Contractele sunt exact ce face posibilă o predare ulterioară către echipă.
Nimeni nu e on-call. SLO-uri oneste + natura asincronă a sistemului (retrimitere idempotentă) + servicii gestionate cu SLA-urile lor.
Cod de securitate scris cu AI. Perimetru minimizat prin design (iam externalizează credențialele, RLS păzește izolarea) + security review-ul punctual cerut la §6.
Divergență de standard (infrastructură proprie într-o casă on-prem). Nu e accident — e ipoteza testului; granița e API-ul, comunicată explicit.

9. Ordinea de execuție — neschimbată ca fazare

Fundația: repo + CI + schema DB (partiționată, RLS, events + outbox) + cele 5 contracte cu fixtures + ingest/export cu tenant fake + coada
Workbench manual (UI-ul prototipat pe iris.bgn.ro/concept-*) + reguli deterministe (tabelul Adam)
Memoria → Descrieri contabile precompletate + fluxul de dubii
Pilotul BONO (documente reale prin Nucleu/Vertigo) + telemetria de cost
Motoarele pe porturi, în shadow mode → precompletare → Zero-Touch pe felii

Pasul 0, înaintea tuturor (concluzia review-ului, adoptată integral): modelul canonic de date — nucleul comun + extensiile per cele 6 tipuri de documente (extrasul de cont = testul polimorfismului), modelul de context (master data), contractele derivate din el. Draft: BGN + Claude; sesiune de shaping cu Prodi + Cristi pe strawman.

10. Statusul deciziilor

Închise în v2: stack (.NET 10 minimal) · DB (Neon Postgres) · compute (Railway) · storage (R2 + swap path) · auth (iam) · ANAF/BNR (directory/forex) · criptare v1 (SSE only) · numere de afișare (mecanică + nu-gapless + an ingest) · contract Tenant-out (Iris definește, destinatarii implementează) · HA (gestionat).

Rămase deschise: formatul final bulk import — manifest NDJSON + presigned ca propunere principală, de validat cu SOLO · numărul concret al ferestrei de backup pentru DPA (propunere: 30 zile) · security review-ul punctual pe perimetru (cerere către Prodi) · modelul canonic de date (pasul 0, în lucru).