SSoT for the K8s Project

Architectural Design Specifications

1. Core Architecture & Local Runtime Environment

The entire platform is built as a distributed microservice system running inside an enterprise-grade local sandbox. The underlying infrastructure uses k3d to spin up a multi-node, lightweight K3s (Kubernetes) cluster directly inside Docker on your laptop. To eliminate external internet dependencies and network bottlenecks, a built-in local container registry is bound directly to the k3d cluster nodes. The local development life cycle is orchestrated entirely by Skaffold, which watches local source directories, coordinates container builds, injects live code updates via hot-reloading directly into running containers, and automates local manifest application.

2. Service Breakdown & Polyglot Storage Strategy

The business logic is decoupled into distinct, containerized microservices to ensure individual scalability and fault isolation:

• Frontend Service (React): The client-side user interface responsible for store browsing, user authentication, and shopping cart interactions.
• Product Catalog Service: A read-intensive microservice managing item definitions, technical specifications, and merchant inventory counts. It relies on a document-oriented MongoDB database cluster due to its highly flexible, schema-less properties.
• Order Processing Service: A highly transactional microservice handling secure checkout states, billing, and customer invoices. It relies on PostgreSQL to enforce strict ACID compliance and relational integrity.

3. Data Sovereignty & Geographic Infrastructure Sharding

To strictly comply with global data protection regulations (such as GDPR, CCPA, and DPDP), the system uses Geographic Sharding to ensure sensitive user data is physically stored within its region of origin.

• Implementation: The system leverages a composite shard key consisting of [tenant_id, country_code].
• Database Layers: MongoDB automates horizontal scaling using its native mongos routing query routers and config servers. PostgreSQL implements true multi-node horizontal sharding across independent physical cloud clusters by using the Citus open-source database extension.

4. Complex Multi-Tenancy Strategy

The platform supports multiple commercial merchants (tenants) sharing a unified, cost-efficient infrastructure via a Hybrid Multi-Tenancy Architecture:

• Compute Tier: All tenants share the same running microservice container pods inside the Kubernetes cluster. The system dynamically identifies the active tenant by decoding a tenant_id claim baked directly into the user’s cryptographically signed identity token.
• Product Storage Tier (Shared Catalogue, Private Overlay): To prevent duplicate entries of universal products, the platform separates data. The core products collection holds global, shared item details (SKU, brand, images). A separate merchant_listings collection stores tenant-specific commercial overrides (price, current stock, active flag) tied to a unique tenant_id.
• Order Storage Tier (Isolated Shards): Financial and customer transaction histories are isolated across independent database shards managed by Citus and MongoDB clustering based on the tenant's risk profile and scale.

5. Application-Level Geo-Fencing (Country Restrictions)

When compliance or licensing restricts specific products from being sold in certain countries, the system avoids infrastructural sharding for public catalog data and handles rules at the application layer.

• An explicit geo_restrictions schema matrix containing inclusion or exclusion lists (e.g., whitelist or blacklist arrays of ISO country codes) is attached directly to the global product or merchant listing document.
• At runtime, the cluster edge (API Ingress) captures the user's origin country via GeoIP or profile data and passes an X-User-Country header down to the Product Service. The backend appends a dynamic mongo filter (e.g., $ne: userCountry) to eliminate blocked items before delivering responses to the client.

6. Scalable Redis Caching Strategy

To protect the primary databases from intensive read operations, an ultra-fast Redis in-memory data cache sits directly in front of MongoDB.

• Key Namespacing: To prevent data leaks across distinct merchants and countries, Redis uses strict composite composite keys following a colon-separated namespace: tenant:<tenant_id>:country:<country_code>:catalog
• Cache Patterns: The system enforces a Cache-Aside (Lazy Loading) pattern with a mandatory Time-To-Live (TTL) expiration limit of 1 hour.
• Day-2 Operational Safety: The Product Service implements a Mutex Lock mechanism to block "Cache Stampedes" by ensuring only one backend worker can re-query MongoDB on a cache miss while parallel concurrent requests wait. Whenever a merchant alters an item or a country rule, the backend executes targeted cache eviction using background scans matching tenant:<tenant_id>:country:*:catalog.

7. Eventual Data Synchronization & Change Data Capture (CDC)

• Instead of forcing application code to double-write to multiple networks, the system implements a modern Change Data Capture (CDC) model.
• The Debezium framework hooks directly into the database transaction logs (the Postgres Write-Ahead Log [WAL] and the MongoDB Oplog) in real-time, translating row modifications into structured JSON event streams. These streams are safely fed into an Apache Kafka cluster, allowing reporting data warehouses or regional caches to sync automatically.

8. API Gateway Management & Versioning Strategy

• Ingress & Validation: Traefik acts as the API Gateway. It validates incoming JSON Web Tokens (JWT) signatures at the cluster edge, dropping unauthorized traffic instantly.
• API Evolution: The platform enforces strict URL Path Versioning (e.g., /api/v1/orders vs. /api/v2/orders). Breaking structural API payload changes require incrementing the major path version, allowing Traefik to route legacy and modern variants cleanly to distinct Kubernetes deployment groups.

9. Unified Identity Provider (IdP) & Application RBAC

• Authentication (AuthN): Handled completely outside the custom microservices by deploying Keycloak (OpenID Connect / OIDC provider). Users register, authenticate, and manage passwords against Keycloak, which hands back a secure JWT.
• Authorization (AuthZ): Inside our custom application code, granular Role-Based Access Control (RBAC) is evaluated by decoding the roles array contained within the token (e.g., separating standard customer reading routes from inventory-manager mutation actions).

10. Left-Shift Security & Automated Quality Gates

• Pre-Commit / Early CI: ESLint/Ruff/Golangci-lint checks syntax, while TruffleHog/Gitleaks blocks commits if high-entropy cloud secrets are exposed in plain text.
• Static Security & Dependencies: SonarQube/Semgrep executes Static Application Security Testing (SAST), while Snyk/Dependabot reviews open-source application dependency trees for Software Composition Analysis (SCA).
• Container Security: During image creation, Trivy audits the operating system container base layers for vulnerabilities (CVEs).
• Manifest Auditing: Before manifests are committed to Git, Datree/Kube-linter scans the Kubernetes YAML files to block infrastructure misconfigurations (e.g., missing resource limits, privilege escalation vectors).
• Runtime Security: Automated OWASP ZAP runs Dynamic Application Security Testing (DAST) web vulnerability injection attacks against running staging namespaces.

11. Tiered Testing Strategy

• Unit Tests: Handled natively via modern test runners (Vitest/PyTest/Go Test) to check decoupled pure business logic and algorithms with zero dependencies.
• Integration Tests: Enabled by Testcontainers. During test execution, Testcontainers invokes the local Docker API to spin up real, ephemeral, completely pristine instances of Redis, MongoDB, and PostgreSQL. The microservice test suite runs its queries against these short-lived native databases, ensuring integration testing accurately mirrors true cloud environments before disposing of the containers.

12. GitOps Delivery & Infrastructure Control

• Environment Orchestration: Managing differing requirements across development, staging, and production environments is isolated using Kustomize. Kustomize maintains a single source base/ configuration file structure and maps changes (replicas, ingress domains, configuration values) through declarative, non-destructive overlays/.
• Continuous Deployment (CD): The platform rejects manual push actions (kubectl apply) in favor of a pull-based GitOps engine powered by Argo CD running inside the cluster. Argo CD constantly checks the state of your infrastructure Git repository against the active state of the cluster, pulling, validating, and auto-correcting drift instantly.

---

Architectural Design Matrix

Category	Component Layer	Chosen Technology	Architectural Function & Single Source of Truth Rules
Runtime	Local Cluster Infrastructure	k3d (K3s in Docker) + Local Registry	Provisions a local multi-node cluster and secure loopback repository to eliminate external cloud network lag.
Workflow	Developer Inner Loop	Skaffold	Automates container tracking, handles image orchestration, and triggers live hot-reloading into k3d.
Microservices	Frontend Core	React	Client browser rendering engine managing secure sessions and UI visual flows.
Microservices	Catalog Backend	Node.js / Go / Python	Controls item inventories and references. Pairs strictly with unstructured storage.
Microservices	Transactional Backend	Node.js / Go / Python	Processes state-driven consumer purchase checkouts and compliance-driven invoicing.
Data Layer	Product Storage	MongoDB (Cloud-Ready)	Document database housing global reference products alongside multi-tenant listings.
Data Layer	Order Ledger	PostgreSQL + Citus	Sharded relational engine executing horizontal table partitioning and row routing across servers.
Data Layer	Distributed Fast Cache	Redis	Accelerates data reads via lazy-loading. Resolves cache stampedes via Mutex locks.
Architecture	Data Sovereignty	Geo-Sharding via [tenant_id, country_code]	Restricts sensitive relational transaction logs to country boundaries via database-level shards.
Architecture	Multi-Tenancy	Composite JWT Token Mapping	Leverages a single shared compute container layer while using logical document IDs and Postgres tables to segregate clients.
Architecture	Geo-Fencing	API X-User-Country Header Matrix	Filters catalog displays by querying a blacklist/whitelist array inside item metadata to meet geographic constraints.
Data Flow	Asynchronous Sync	Debezium + Apache Kafka	Executes infrastructure-level Change Data Capture (CDC) via live log tracking to sync remote data analytics.
Traffic Gate	API Gateway & Routing	Traefik	Performs URL path validation, checks edge JWT signatures, and separates /v1 and /v2 microservice endpoints.
Identity	AuthN & AuthZ	Keycloak (OIDC)	Decouples core systems from user credentials by centralizing authentication and providing cryptographically signed JWT tokens.
Quality/QA	Code Linters	ESLint / Ruff / Golangci-lint	Enforces structural code patterns and identifies structural code smells before code review.
Quality/QA	Secret Interception	TruffleHog / Gitleaks	Evaluates local git histories and blocks commits if unencrypted security tokens are caught.
Quality/QA	Logic Testing	Vitest / PyTest / Go Test	Executes ultra-fast, local testing of functions without firing external infrastructure networks.
Quality/QA	Environment Testing	Testcontainers	Spins up live Docker containers of real databases (Mongo/Postgres/Redis) for clean integration tests.
Quality/QA	Static Code Security	SonarQube / Semgrep (SAST)	Audits codebase syntax trees for OWASP top-10 programming vulnerabilities during pull requests.
Quality/QA	Dependency Audit	Snyk / Dependabot (SCA)	Discovers and alerts developers to security issues in open-source third-party application modules.
Quality/QA	Container Integrity	Trivy	Reviews target container base filesystems for known CVE vulnerability patches during the build process.
Quality/QA	Runtime Testing	OWASP ZAP (DAST)	Fires automated pen-testing payload injections against live staging application endpoints.
Quality/QA	Manifest Evaluation	Datree / Kube-linter	Evaluates local Kubernetes configuration YAML layouts for misconfigurations before application.
Deployment	Environment Variant Overlay	Kustomize	Declares a standard base configurations directory and merges targeted environment patches natively.
Deployment	GitOps Delivery	Argo CD	Automates the complete delivery loop by monitoring Git changes and auto-correcting active cluster drift.