Vijfpas documentation index¶

This is the landing page for Vijfpas platform documentation.

This monorepo is the current authoritative source for Vijfpas platform documentation. The earlier split docs repository is retained only as archival reference during the rollback period and must not be treated as canonical.

Documentation is split into two tracks:

Architecture/policy track: concepts, environment boundaries, service and product catalogs, security model, operations policy, and decision baseline
Implementation track: concrete deployment details such as inventory, addressing, interfaces/ports, and live rollout state

For the public docs portal, these two authoring tracks are presented as:

Platform
Infrastructure

That keeps the site easier to navigate while the monorepo remains the stricter source-of-truth model.

0. Documentation map (Mermaid)¶

flowchart TD
  IDX[platform.md]
  IDX --> ARCH[Architecture/policy track]
  IDX --> IMPL[Implementation track]

  ARCH --> C[concepts.md]
  ARCH --> D[dimensions.md]
  ARCH --> A[architecture.md]
  ARCH --> BR[backup-restore.md]
  ARCH --> GR[gitlab-repository-architecture.md]
  ARCH --> CM[collaboration-model.md]
  ARCH --> S[services.md]
  ARCH --> P[products.md]
  ARCH --> HA[ha.md]
  ARCH --> O[operations.md]
  ARCH --> SEC[security.md]
  ARCH --> CONF[confidentiality-model.md]
  ARCH --> CONFR[confidentiality-register-seed.md]
  ARCH --> TEM[tenant-exposure-matrix.md]
  ARCH --> TM[threat-models.md]
  IMPL --> I[inventory.md]
  IMPL --> IN[implementation-network.md]
  IMPL --> ISI[implementation-services-interfaces.md]
  IMPL --> IDEP[implementation-deployments.md]
  P --> S
  HA --> O
  HA --> S
  HA --> P
  A --> S
  C --> SEC

1. Documentation structure¶

1.1 What goes where¶

Architecture/policy track:

Dimensions: canonical naming, architecture, and policy axes, plus composition rules
Concepts & glossary: shared language, environments, trust-domains, tiers, privilege-tiers, and naming conventions
Architecture: trust boundaries, flows, and target topology
Backup/restore architecture: authoritative recovery sources, recovery layers, restore scopes, and dependency order
GitLab repository architecture: repository-scope history, archived split-repo plan, and current repository-authority notes
Platform services: reusable building blocks and owners
Products: first-party and third-party product catalogs
HA profiles: HA patterns and baseline resiliency per component and product
Operations: policy baselines for patching, backup, DR, and incident handling
Security & SoD: access policy, tier controls, and security guardrails
Confidentiality model & register: classification baseline and applied service/product data register
Decision log (ADRs): major architecture and policy decisions

Implementation track:

Inventory: factual hardware/network inventory and current configuration
Runbooks: step-by-step operational procedures
Service interfaces: concrete ports/protocols/routes
Addressing plan: VLAN IDs, subnet ranges, and IP assignments
Deployment specs: environment-specific manifests/values and rollout notes

1.2 Document map¶

Architecture/policy track:

2. Platform goals¶

operate a secure customer-facing development SaaS and application runtime on one Proxmox + Ceph substrate
enforce separate environments for nfr, pfm, dev, acc, and prd
keep reproducible infrastructure via IaC (Ansible/Terraform)
maintain high availability where business-critical
keep backup and recovery repeatable, tested, and independently restorable

3. Design principles¶

prefer declarative and reproducible deployments
treat customer workspace and CI execution as untrusted by default
keep customer development execution boundaries stronger than namespace-only isolation
separate internal and customer development control paths where external customer code execution is present
keep dev, acc, and prd credentials and deployment authority separated
keep secrets out of Git and centralize secret handling
reduce special cases with standard images, naming, and sizing profiles

4. Decision baseline (accepted)¶

PBS on dedicated off-cluster host with NAS replication (ADR-0001).
Initial Kubernetes separation model adopted two clusters (dmz-k8s + core-k8s) as baseline (ADR-0002), later extended by trust-domain runtime split (ADR-0016).
OpenBao selected for machine secrets (ADR-0003).
Hybrid certificate trust model (ADR-0004).
OpenSearch selected for centralized logging (ADR-0005).
Async replication as database HA default (ADR-0006).
Tiered SoD model adopted (ADR-0007).
OpenSearch is split into app/search and logging clusters, with Kafka decoupling where needed (ADR-0008).
OpenBao recovery-key custody uses Shamir 3-of-5 split (ADR-0009).
Critical CVE remediation uses exposure-based SLA (ADR-0010).
Infrastructure DBs are separated from application DBs per environment (ADR-0011).
Tenant isolation baseline uses shared-plane logical isolation within a trust domain, with strong tenant controls (ADR-0012 with architecture update context from 2026-03).
Tenant-facing authorization requires explicit tenant_id context (ADR-0013).
Tenant data partitioning baseline is service-aligned across data planes (ADR-0014).
Customer development SaaS execution isolation defines split internal and customer GitLab domains, tenant-scoped runner/workspace execution, and brokered production deployment authority (ADR-0015).
Development runtime is split by trust domain into k8s-dev-internal and k8s-dev-customer, with separate k8s-acc and k8s-prd environments in the current architecture baseline.

Public portal boundary¶

The public docs portal intentionally excludes:

runbooks/
adrs/
adrlog.md

Those remain authoritative internal documents in the monorepo and in Git history, but they are not part of the published public site navigation.

5. Decision map (Mermaid)¶

flowchart LR
  ADR1[ADR-0001 PBS] --> INFRA[Infrastructure]
  ADR2[ADR-0002 K8s split] --> RUNTIME[Runtime]
  ADR3[ADR-0003 OpenBao] --> SEC[Security]
  ADR4[ADR-0004 Cert model] --> SEC
  ADR5[ADR-0005 OpenSearch] --> OBS[Observability]
  ADR6[ADR-0006 DB HA async] --> DATA[Data]
  ADR7[ADR-0007 SoD tiers] --> GOV[Governance]
  ADR8[ADR-0008 OpenSearch split + Kafka] --> OBS
  ADR8 --> DATA
  ADR9[ADR-0009 OpenBao Shamir 3-of-5] --> SEC
  ADR10[ADR-0010 CVE SLA by exposure] --> SEC
  ADR10 --> GOV
  ADR11[ADR-0011 DB domain split] --> DATA
  ADR11 --> SEC
  ADR12[ADR-0012 Tenant isolation model] --> GOV
  ADR12 --> RUNTIME
  ADR13[ADR-0013 Tenant identity and RBAC] --> SEC
  ADR13 --> GOV
  ADR14[ADR-0014 Tenant data partitioning] --> DATA
  ADR14 --> SEC
  ADR15[ADR-0015 Customer dev SaaS execution isolation] --> GOV
  ADR15 --> RUNTIME
  ADR15 --> SEC
  ADR16[ADR-0016 Nonprod runtime split by trust domain] --> RUNTIME
  ADR16 --> SEC