# VNOS — High-Level Design (HLD)
**Version:** 0.3.0 (architecture documentation)  
**State:** Target architecture / reviewed design baseline; **not** an as-built system  
**Architecture priority:** Headless, API-First, Metadata-Driven, Configuration-First, Multi-Enterprise, Modular, Source-Agnostic.

## 1. Scope and system identity
VNOS is a **Value Network Operating System** for configurable cross-enterprise value networks across industries. It is **not** a generic website/app builder and not an Ard Varamin-specific supply-chain application. Ard Varamin, Samira, and Ofogh Kourosh are pilot organization records, not code-specific modules.

This document corrects the prior simplified overview diagrams where a single UI entry point, synchronous dependencies, and a linear order-to-sale-to-ledger chain could be mistaken for mandatory system behavior.

## 2. HLD diagrams (editable Mermaid sources)
1. [Platform Context & Containers](01-platform-context.mmd): `Experience → API / Control Plane / Runtime → Modules / Infrastructure` with independent external API consumers and governed configuration publication.
2. [Value Network Domain Interactions](02-value-network-domains.mmd): non-linear domain topology with independent inventory, custody, ownership, evidence, contract, ledger, and settlement responsibilities.
3. [Configuration Publication Lifecycle](03-configuration-lifecycle.mmd): draft, validate, migration impact, approval, governed schema migration, activate and audit.

[Open diagrams on the website](../../hld.html). Original Mermaid source files live in this repository and should remain editable.

## 3. Key architectural decisions (HLD review)
| Area | Decision / correction | Invariant |
|---|---|---|
| Platform API | Both UI and third-party clients use the **same** versioned application APIs; partner integrations use scoped ingress | No UI-owned business logic |
| Control Plane | God Admin is the **panel**; Control Plane is the underlying metadata/policy/configuration services | Do not conflate presentation and architecture |
| Runtime | Configuration is published and versioned before use | Draft schema/config never automatically changes live transactions |
| Metadata / SQL | SQL Server relational-first; safe schema changes via governed Schema Engine; JSON only for supporting/config metadata | Never execute arbitrary DDL from clients |
| Modularization | Modular Monolith as initial deployment topology, with enforceable module boundaries and optional later extraction | Modules do not read/write each other's tables directly |
| Integrations | Manual, CSV and API sources share mapping/validation/provenance rules | POS SKU signal does not prove batch lineage |
| Events | Outbox records committed atomically with domain transactions; consumers idempotent | An event is not proof of downstream success |
| Ownership | Legal ownership, physical custody, contractual obligation, inventory position are distinct | A warehouse receipt does not necessarily transfer title |
| Financial | Finance eligibility configurable by approved contract and event type; double-entry postings balanced; external settlement independently verified | Sale need not be mandatory trigger for receivables |
| Blockchain | Optional proof/attestation extension and never a prerequisite for a domain transaction | A hash is not automatically a legal ownership record |
| Identity | tenant/org membership, role/policy, record scope, delegated access and audit | Never expose other organizations' data by default |

## 4. Main responsibilities
- **Experience Layer:** Persian RTL God Admin Panel; partner portals; optional third-party frontends. Any renderer is replaceable.
- **API Layer:** auth, authorization, versioning, validation, idempotency, errors, OpenAPI contract, correlation IDs.
- **Control Plane:** define & publish models, fields, relations, workflow/rule versions, roles/policies, integrations and UI slots; change-management governance.
- **Runtime / Application Services:** commands and queries executed against active definition versions; never import UI code.
- **Domain Engines:** Network/Organization; Commercial Contract; Demand/Order; Sourcing/Quality; Lot & Genealogy; Manufacturing; Inventory/Custody; Logistics/Receipt; Retail Evidence; Financial Calculation; Ledger/Receivables; Reconciliation/Disputes.
- **Infrastructure:** SQL Server, transactional outbox, event broker/workers, secret vault, telemetry/audit, backup/recovery and external adapters.

## 5. Interfaces / patterns
- UI → API: HTTPS JSON with tenant/org scope, RBAC/ABAC enforcement, conflict/version responses. No direct database access.
- Third-party source → ingress: source authentication, mapping version, external record IDs, idempotency, validation, quarantine and replay.
- Control Plane → Runtime: published configuration references/version and effective date, not unmanaged direct data mutation.
- Module → module: application contract / domain event; no cross-module DB writes.
- Domain transaction → Event transport: outbox committed in same SQL transaction; worker forwards, consumer deduplicates.
- Ledger → external settlement: generate receivable/payable and reconcile evidence; no assumption that VNOS itself moves funds.
- Optional blockchain: evidence-only adapter after formal technology and legal approval.

## 6. Boundary conditions and open design decisions
- The demand-led versus supply-led business start is **open**; either may trigger different configurations.
- BOM and quality tolerance, currency/units, title transfer, accrual trigger, pricing basis, settlement dates and partner approvals are not predefined constants.
- The exact API Gateway product, hosting topology, identity provider, broker sizing, resilience SLO, blockchain choice and data-retention rules require ADRs/PoCs before production selection.
- Future industry extensions must use supported metadata/domain-engine contracts or explicit versioned plugins rather than silent Core changes.

## 7. Nonfunctional acceptance
Every vertical slice must prove: standalone headless API; configurable field/rule at supported scope; second-organization reuse; data-isolation negative tests; audit & provenance; duplicate/retry handling; relevant concurrency; migration safety; OpenAPI documentation. The HLD describes **intended architecture**, not implemented features.

## 8. Revision log
- **v0.3.0:** replaced linear value-chain assumption with event/evidence-based domain interaction; clarified API vs integration transport, financial/event independence, optional blockchain, control plane vs God Admin panel and governed metadata publication.