2099 01 Requirements 239c9d32

# Step 1: Requirements - pci-dss-gw

> Generated by Requirements agent | 2026-02-09

---

## Project Overview

### Business Context

| Attribute | Value |
| --- | --- |
| **Project Name** | pci-dss-gw |
| **Industry** | Financial Services — Payment Processing |
| **Company Size** | Enterprise (500+) *(assumption — validate)* |
| **System Type** | Payment Gateway — high-throughput transaction processing |
| **Scenario** | Greenfield |
| **Description** | A highly available payment gateway processing 10,000 transactions per second (TPS). The system must meet PCI-DSS compliance requirements and provide sub-second latency for payment authorization, capture, and settlement workflows. |

### Stakeholders

| Role | Responsibility | Notes |
| --- | --- | --- |
| Product Owner | Business requirements, acceptance criteria | *(To be confirmed)* |
| Security/Compliance Lead | PCI-DSS audit readiness, security controls | *(To be confirmed)* |
| Platform Engineering | Azure infrastructure, deployment pipelines | *(To be confirmed)* |
| DevOps / SRE | Monitoring, incident response, runbooks | *(To be confirmed)* |

### Workload Pattern

| Attribute | Value |
| --- | --- |
| **Pattern** | Container (Enterprise Tier) |
| **Justification** | User specified ACA/AKS compute; 10k TPS throughput requires container orchestration with horizontal scaling. PCI-DSS CDE isolation is best achieved via dedicated node pools and network policies in AKS. |
| **Detection Signals** | "payment gateway", "10,000 TPS", "containers", "AKS/ACA", "PostgreSQL", "Cosmos DB" |

---

## Functional Requirements

### Core Capabilities

| ID | Requirement | Priority | Notes |
| --- | --- | --- | --- |
| FR-01 | Process payment authorization requests at 10,000 TPS sustained | P0 | Peak capacity should target 15,000 TPS *(assumption)* |
| FR-02 | Support payment capture and settlement workflows | P0 | Batch settlement window TBD |
| FR-03 | Provide idempotent transaction processing (exactly-once semantics) | P0 | Critical for financial accuracy |
| FR-04 | Expose RESTful API endpoints for payment operations | P0 | OpenAPI 3.x specification |
| FR-05 | Store transaction records in PostgreSQL with full ACID compliance | P0 | Primary persistent store |
| FR-06 | Use Cosmos DB for distributed session state and caching | P1 | Low-latency reads for token/session lookup |
| FR-07 | Support webhook notifications for async payment events | P1 | Event-driven notification to merchants |
| FR-08 | Implement retry and dead-letter queue for failed transactions | P0 | Azure Service Bus for messaging |
| FR-09 | Provide health check and readiness endpoints | P0 | Kubernetes liveness/readiness probes |
| FR-10 | Support API versioning for backward compatibility | P1 | URL path or header-based versioning |

### Integration Points

| System | Direction | Protocol | Notes |
| --- | --- | --- | --- |
| Card Networks (Visa, MC, etc.) | Outbound | HTTPS/mTLS | PCI-DSS encrypted channels |
| Merchant Systems | Inbound | REST API | OAuth 2.0 / API key authentication |
| Banking / Settlement | Outbound | SFTP / HTTPS | Batch settlement files |
| Monitoring (Azure Monitor) | Internal | OTLP / SDK | Distributed tracing, metrics |

> [!NOTE]
> External integration details (card network endpoints, banking protocols) are assumptions and must be validated with the integration team.

---

## Non-Functional Requirements (NFRs)

### Performance

| Metric | Target | Measurement |
| --- | --- | --- |
| **Throughput** | 10,000 TPS sustained | Requests per second at load balancer |
| **Peak Throughput** | 15,000 TPS *(assumption)* | 1.5× sustained for burst handling |
| **P50 Latency** | ≤ 100 ms | End-to-end API response time |
| **P99 Latency** | ≤ 500 ms | Tail latency under sustained load |
| **P99.9 Latency** | ≤ 1,000 ms | Extreme tail during peak |
| **Database Query Latency** | ≤ 20 ms (P95) | PostgreSQL read/write operations |
| **Cosmos DB Latency** | ≤ 10 ms (P99) | Session/cache reads |

### Availability & Reliability

| Metric | Target | Notes |
| --- | --- | --- |
| **SLA Target** | 99.99% (≈ 4.3 min downtime/month) | Financial-grade availability |
| **RTO** | ≤ 30 minutes | Recovery Time Objective |
| **RPO** | ≤ 5 minutes | Recovery Point Objective (near-zero data loss) |
| **Failover** | Automatic | Active-passive with geo-redundant database |
| **Health Monitoring** | Real-time | Sub-minute alerting on degradation |

> [!IMPORTANT]
> 99.99% SLA requires zone-redundant deployments across availability zones and careful SLA composition of all dependent services. AKS with availability zones + zone-redundant PostgreSQL Flexible Server achieves this.

### Scalability

| Dimension | Approach | Notes |
| --- | --- | --- |
| **Horizontal Pod Autoscaling** | CPU/memory + custom metrics (TPS) | KEDA for event-driven scaling |
| **Database Scaling** | PostgreSQL: read replicas; Cosmos DB: autoscale RU/s | Read-heavy cache offloaded to Cosmos DB |
| **Cluster Scaling** | AKS cluster autoscaler (min 3 → max 20 nodes) | *(Node count assumption — validate)* |
| **Connection Pooling** | PgBouncer sidecar or Azure-native pooling | Prevent connection exhaustion at 10k TPS |

### Data Requirements

| Attribute | Value |
| --- | --- |
| **Data Classification** | PCI DSS Level 1 (cardholder data) |
| **Retention — Transactions** | 7 years *(regulatory requirement — validate)* |
| **Retention — Logs** | 1 year minimum (PCI-DSS § 10.7) |
| **Encryption at Rest** | AES-256 (Azure platform encryption + CMK for cardholder data) |
| **Encryption in Transit** | TLS 1.2+ mandatory on all channels |
| **Data Residency** | EU (Sweden / Germany) |

---

## Compliance & Security Requirements

### Compliance Frameworks

| Framework | Status | Scope | Notes |
| --- | --- | --- | --- |
| **PCI-DSS v4.0** | **Mandatory** | Full CDE (Cardholder Data Environment) | Level 1 merchant/processor — annual ROC audit |
| **SOC 2 Type II** | Recommended | Trust Services Criteria | Security, Availability, Processing Integrity |
| **GDPR** | Mandatory | EU data residency, data subject rights | swedencentral primary region ensures EU residency |

### PCI-DSS Specific Controls

| PCI-DSS Requirement | Azure Implementation | Priority |
| --- | --- | --- |
| **Req 1**: Network segmentation | AKS network policies + NSGs, dedicated CDE subnet, Azure Firewall | P0 |
| **Req 2**: No vendor defaults | Hardened container images, CIS benchmarks, no default credentials | P0 |
| **Req 3**: Protect stored cardholder data | Encryption at rest (CMK), tokenization, data masking in non-prod | P0 |
| **Req 4**: Encrypt transmission | TLS 1.2+ enforced, mTLS for service-to-service, no public endpoints for data tier | P0 |
| **Req 5**: Anti-malware | Microsoft Defender for Containers, image vulnerability scanning | P0 |
| **Req 6**: Secure development | Container image scanning (Trivy/Defender), no known CVEs in prod | P0 |
| **Req 7**: Restrict access (need-to-know) | Azure RBAC, Kubernetes RBAC, PIM for admin access | P0 |
| **Req 8**: Identify & authenticate | Entra ID + managed identity, MFA enforced, no shared accounts | P0 |
| **Req 9**: Physical access | Azure datacenter controls (Microsoft responsibility) | N/A |
| **Req 10**: Logging & monitoring | Azure Monitor + Log Analytics, 1-year log retention, tamper-proof audit | P0 |
| **Req 11**: Regular testing | Penetration testing, vulnerability scanning, Azure Load Testing | P0 |
| **Req 12**: Security policy | Documented InfoSec policy, incident response plan | P1 |

### Security Controls

| Control | Implementation | Notes |
| --- | --- | --- |
| **Identity** | Entra ID with managed identity for all service-to-service auth | No passwords or connection strings in code |
| **Secrets Management** | Azure Key Vault (Premium SKU for HSM) | PCI-DSS requires HSM for cryptographic keys |
| **Network Isolation** | Private endpoints for PostgreSQL, Cosmos DB, Key Vault, ACR | No public endpoints for data services in production |
| **WAF** | Azure Front Door Premium with WAF policy | OWASP 3.2 rule set, bot protection, rate limiting |
| **DDoS Protection** | Azure DDoS Protection Standard | Mandatory for internet-facing payment endpoint |
| **Container Security** | Microsoft Defender for Containers, admission control (Azure Policy for AKS) | Image allow-listing, no privileged containers |
| **Audit Logging** | Azure Activity Log + Diagnostic Settings → Log Analytics | Immutable audit trail, 1-year retention |
| **Vulnerability Management** | Microsoft Defender for Cloud (enhanced), Qualys/Trivy image scanning | Continuous scanning, gated deployments |
| **Data Masking** | Dynamic data masking for non-prod, tokenization for cardholder data | PAN never stored in cleartext |

> [!WARNING]
> PCI-DSS Level 1 requires a Qualified Security Assessor (QSA) for annual audit. Architecture decisions must be validated with QSA before implementation.

### Authentication & Authorization

| Layer | Method | Notes |
| --- | --- | --- |
| **External API** | OAuth 2.0 + API keys (Azure API Management) | Rate limiting per merchant |
| **Service-to-Service** | Managed Identity (workload identity for AKS) | Zero-trust between microservices |
| **Admin Access** | Entra ID + PIM (Privileged Identity Management) | Just-in-time, time-bound elevation |
| **Database** | Entra ID authentication only | `azureADOnlyAuthentication: true` |

---

## Budget

### Estimated Monthly Cost

| Category | Service | SKU / Tier | Est. Monthly Cost | Notes |
| --- | --- | --- | --- | --- |
| 💻 **Compute** | Azure Kubernetes Service | Standard tier, D8s_v5 nodes (3-20) | $2,500 – $8,000 | Zone-redundant, system + user node pools |
| 💾 **Database (Primary)** | Azure Database for PostgreSQL Flexible Server | Memory-optimized, 16 vCores, zone-redundant HA | $1,500 – $2,500 | Read replicas add ~$800/ea |
| 💾 **Database (Cache)** | Azure Cosmos DB | Autoscale, 10,000 – 50,000 RU/s | $800 – $3,000 | Session state, caching |
| 🔐 **Security** | Azure Key Vault Premium | HSM-backed keys | $200 – $500 | PCI-DSS HSM requirement |
| 🌐 **Networking** | Azure Front Door Premium + WAF | Premium tier with DDoS | $500 – $1,200 | PCI WAF requirement |
| 🌐 **Networking** | Azure Firewall Premium | Premium for IDPS | $1,800 – $2,500 | CDE network segmentation |
| 📊 **Monitoring** | Azure Monitor + Log Analytics | Per-GB ingestion, 1-year retention | $500 – $1,500 | PCI log retention |
| 📦 **Container Registry** | Azure Container Registry | Premium (geo-replicated) | $170 | Production image registry |
| 📨 **Messaging** | Azure Service Bus | Premium (1 MU) | $700 | Dedicated capacity for transaction queues |
| 👤 **Identity** | Entra ID P2 + PIM | Per-user licensing | $200 – $500 | PIM for admin access |
| 🛡️ **DDoS** | Azure DDoS Network Protection | Standard (per VNet) | $2,944 | Full VNet coverage for CDE |
| 🔀 **API Gateway** | Azure API Management | Premium (1 unit, VNet-integrated) | $2,800 | VNet integration for CDE, rate limiting, OAuth |
| | **Total Estimate** | | **$14,814 – $26,514/mo** | |

> [!NOTE]
> 💰 Budget range reflects Dev ($14,814) vs Production with full HA ($26,514). Reserved instances (1-year) can reduce compute costs by 30-40%. DDoS Network Protection ($2,944/mo) and API Management Premium ($2,800/mo) are significant fixed costs. Exact costs depend on actual TPS sustained load and data volumes. Validate with Azure Pricing Calculator.

### Cost Optimization Opportunities

- **Reserved Instances**: 1-year RI for AKS nodes and PostgreSQL — estimated 35% savings
- **Cosmos DB Autoscale**: Scale down during off-peak; avoid provisioned throughput over-allocation
- **Spot Nodes**: Use for non-CDE workloads (dev/test, batch processing) — up to 80% savings
- **Log Analytics Commitment Tier**: 100 GB/day commitment tier for predictable log volumes

---

## Operational Requirements

### Environments

| Environment | Purpose | SLA Tier | Notes |
| --- | --- | --- | --- |
| **dev** | Development & testing | Best-effort | Single-zone, reduced SKUs |
| **staging** | Pre-production, PCI compliance testing | 99.9% | Mirror prod config, synthetic data |
| **prod** | Live payment processing | 99.99% | Full HA, zone-redundant, PCI CDE |

### Deployment

| Attribute | Value |
| --- | --- |
| **IaC Tool** | Bicep (Azure Verified Modules) |
| **CI/CD** | GitHub Actions |
| **Container Strategy** | Multi-stage Docker builds, image scanning pre-push |
| **Deployment Strategy** | Blue-green for AKS, canary for critical services |
| **Rollback** | Automated rollback on health check failure (< 2 min) |

### Monitoring & Alerting

| Component | Tool | Retention | Notes |
| --- | --- | --- | --- |
| **Application Metrics** | Azure Monitor + Prometheus | 90 days | TPS, latency, error rates |
| **Application Logs** | Log Analytics workspace | 1 year | PCI-DSS § 10.7 requirement |
| **Distributed Tracing** | Application Insights (connection string) | 90 days | End-to-end transaction tracing |
| **Infrastructure Metrics** | Azure Monitor for Containers | 90 days | Node, pod, container metrics |
| **Security Alerts** | Microsoft Defender for Cloud | Continuous | Threat detection, anomaly alerting |
| **Uptime Monitoring** | Azure Monitor Availability Tests | Continuous | External synthetic probes |

### Alert Thresholds *(assumptions — validate with SRE team)*

| Alert | Condition | Severity | Action |
| --- | --- | --- | --- |
| Error Rate > 1% | 5xx responses / total requests | Sev 1 | Page on-call, auto-scale |
| P99 Latency > 1s | 99th percentile response time | Sev 2 | Investigate, alert team |
| TPS < 5,000 | Sustained 5-min drop from baseline | Sev 1 | Investigate capacity |
| Database CPU > 80% | PostgreSQL CPU sustained 10 min | Sev 2 | Scale up / add read replica |
| Pod Restart > 3 | Container restart loop detection | Sev 2 | Investigate crash, rollback |
| Certificate Expiry < 30d | TLS certificate approaching expiry | Sev 3 | Rotate certificate |

### Required Tags

| Tag | Value | Enforced By |
| --- | --- | --- |
| `Environment` | `dev` / `staging` / `prod` | Azure Policy |
| `ManagedBy` | `Bicep` | Azure Policy |
| `Project` | `pci-dss-gw` | Azure Policy |
| `Owner` | *(To be confirmed)* | Azure Policy |

### Backup & Recovery

| Resource | Backup Method | Frequency | Retention | Notes |
| --- | --- | --- | --- | --- |
| PostgreSQL | Azure-native automated backup | Continuous (WAL) | 35 days | Geo-redundant backup storage |
| Cosmos DB | Continuous backup (PITR) | Continuous | 30 days | Point-in-time restore |
| Key Vault | Soft delete + purge protection | Continuous | 90 days | Immutable by design |
| AKS Config | GitOps (Flux/ArgoCD) | Every commit | Git history | Infrastructure as Code |

---

## Regional Preferences

| Attribute | Value | Notes |
| --- | --- | --- |
| **Primary Region** | `swedencentral` | EU GDPR-compliant, full service availability |
| **Failover Region** | `germanywestcentral` | EU paired alternative |
| **Data Residency** | EU only | GDPR + financial data sovereignty |
| **Multi-Region Strategy** | Active-Passive | Primary handles all traffic; failover on regional outage |

### Region Service Availability *(validate before implementation)*

| Service | swedencentral | germanywestcentral | Notes |
| --- | --- | --- | --- |
| AKS | ✅ | ✅ | Availability zones supported |
| PostgreSQL Flexible Server | ✅ | ✅ | Zone-redundant HA available |
| Cosmos DB | ✅ | ✅ | Multi-region writes if needed |
| Key Vault | ✅ | ✅ | Premium with HSM |
| Azure Front Door | Global | Global | Anycast — no region dependency |
| Azure Firewall | ✅ | ✅ | Premium tier for IDPS |
| Container Registry | ✅ | ✅ | Geo-replication to failover |

---

## Summary for Architecture Assessment

### Recommended Architecture

| Component | Recommendation | Justification |
| --- | --- | --- |
| **Compute** | **Azure Kubernetes Service (AKS)** over Azure Container Apps | AKS provides: dedicated node pools for CDE isolation, Kubernetes network policies for micro-segmentation, KEDA for event-driven autoscaling, mature PCI-DSS compliance tooling (Falco, OPA Gatekeeper), and fine-grained control needed at 10k TPS. ACA lacks dedicated node isolation and granular network policy required by PCI-DSS. |
| **Database (Primary)** | Azure Database for PostgreSQL Flexible Server | ACID transactions for payment records, zone-redundant HA, read replicas for reporting |
| **Database (Cache/State)** | Azure Cosmos DB (NoSQL API) | Sub-10ms latency for session state, distributed caching, autoscale RU/s |
| **API Gateway** | Azure Front Door Premium + Azure API Management (Premium, VNet-integrated) | WAF, DDoS, global load balancing, API rate limiting, OAuth, VNet integration for CDE |
| **Networking** | Hub-spoke VNet with Azure Firewall Premium | CDE isolation, IDPS, east-west traffic inspection |
| **Messaging** | Azure Service Bus Premium | Dedicated capacity for transaction queues, dead-letter handling |
| **Secrets** | Azure Key Vault Premium (HSM) | PCI-DSS cryptographic key management |
| **Monitoring** | Azure Monitor + Log Analytics + Defender for Cloud | Full observability stack with 1-year PCI log retention |
| **DDoS Protection** | Azure DDoS Network Protection (Standard) | Full VNet coverage for CDE network |
| **Container Registry** | Azure Container Registry Premium | Geo-replicated, vulnerability scanning, content trust |
| **Identity** | Entra ID + Workload Identity + PIM | Zero-trust, managed identity everywhere, JIT admin access |

### Key Architecture Decisions for Architect Agent

1. **AKS over ACA**: PCI-DSS CDE isolation requires dedicated node pools and Kubernetes network policies not available in ACA
2. **Dual Database**: PostgreSQL for ACID transactions + Cosmos DB for low-latency cache/session — reduces load on primary DB
3. **Hub-Spoke Network**: Azure Firewall Premium provides IDPS and east-west inspection required by PCI-DSS Req 1
4. **Azure Front Door Premium**: WAF + DDoS + global anycast required for internet-facing payment endpoint
5. **Key Vault Premium (HSM)**: PCI-DSS requires hardware security modules for cryptographic key storage

### Assumptions Requiring Validation

| # | Assumption | Impact if Wrong | Validate With |
| --- | --- | --- | --- |
| 1 | Company size is Enterprise (500+) | Budget tier, security posture | Product Owner |
| 2 | ~~Peak TPS is 1.5× sustained (15,000 TPS)~~ | ~~Node count, cost estimate~~ | **Confirmed** ✅ |
| 3 | Transaction retention is 7 years | Storage costs, archival strategy | Compliance / Legal |
| 4 | P99 latency target is 500 ms | Service tier, architecture complexity | Product Owner |
| 5 | Blue-green deployment strategy | CI/CD pipeline design | DevOps team |
| 6 | Active-passive multi-region (not active-active) | Cosmos DB config, cost, complexity | Architecture team |
| 7 | OAuth 2.0 for external API auth | APIM configuration | Security team |
| 8 | Service Bus for async messaging (not Event Hubs) | Messaging architecture | Architecture team |
| 9 | AKS node range 3-20 nodes (D8s_v5) | Compute cost, scaling headroom | Performance team |
| 10 | KEDA for event-driven autoscaling | AKS add-on configuration | Platform team |
| 11 | PgBouncer for connection pooling | Database connectivity pattern | Database team |
| 12 | Alert thresholds (error rate, latency, TPS) | Alert fatigue vs. missed incidents | SRE team |
| 13 | Staging mirrors prod configuration | Staging environment cost | Finance / Product Owner |
| 14 | Owner tag value not yet confirmed | Azure Policy enforcement | Project lead |

### Handoff to Architect Agent

The Architect agent should:

1. Validate the AKS vs. ACA decision with WAF pillar assessment
2. Confirm SKU recommendations with Azure Pricing MCP
3. Assess hub-spoke network topology for PCI-DSS compliance
4. Evaluate Cosmos DB consistency model (Strong vs. Session for payment state)
5. Produce cost estimate with reserved instance pricing
6. Score all 5 WAF pillars for the proposed architecture

---

## References

> [!NOTE]
> 📚 The following Microsoft Learn resources provide additional guidance.

| Topic | Link |
| --- | --- |
| PCI-DSS on Azure | [Payment processing blueprint](https://learn.microsoft.com/azure/compliance/offerings/offering-pci-dss) |
| AKS Security Best Practices | [AKS security concepts](https://learn.microsoft.com/azure/aks/concepts-security) |
| AKS PCI-DSS Guidance | [AKS regulated workloads](https://learn.microsoft.com/azure/aks/operator-best-practices-cluster-security) |
| PostgreSQL Flexible Server HA | [High availability concepts](https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-high-availability) |
| Cosmos DB Consistency Levels | [Consistency levels](https://learn.microsoft.com/azure/cosmos-db/consistency-levels) |
| Azure Key Vault HSM | [Managed HSM overview](https://learn.microsoft.com/azure/key-vault/managed-hsm/overview) |
| Azure Front Door WAF | [WAF on Front Door](https://learn.microsoft.com/azure/web-application-firewall/afds/afds-overview) |
| Azure Well-Architected Framework | [WAF overview](https://learn.microsoft.com/azure/well-architected/) |
| Managed Identities | [Managed identities overview](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) |
| Azure Pricing Calculator | [Pricing calculator](https://azure.microsoft.com/pricing/calculator/) |