arch-requirements

# Requirements Document — Order Management System (OMS)
**Version**: 1.0 Draft  |  **Date**: 2026-03-23  |  **Author**: hahxxx1-Huiwen-Han
**Project ID**: OMS-001  |  **Department**: SSG / TSD
**Scope**: Standalone new application (full internal stack detail required)

---

## 1. Project Overview

The Order Management System (OMS) is a new internal application for SSG business unit
to manage product orders across PRC and NA regions. It replaces a legacy Excel-based
process with a web application backed by REST APIs and asynchronous event processing.
Internal Company employees submit orders; external partners receive order confirmations
via an API Gateway. All order data is classified Company Confidential.

---

## 2. Applications in Scope

| App | Type | New/Existing | Owner | Scope |
|-----|------|-------------|-------|-------|
| OMS Web (Nginx/Vue) | Frontend | New | IT Org | Full internal stack |
| OMS BFF (Spring Boot) | Backend | New | IT Org | Full internal stack |
| OMS Order Service (Spring Boot) | Backend | New | IT Org | Full internal stack |
| OMS Payment Service (Spring Boot) | Backend | New | IT Org | Full internal stack |
| PostgreSQL (OMS DB) | Database | New | InfraSec (managed) | Full |
| Kafka (shared platform) | Message Queue | Existing | InfraSec | Integration boundary only |
| WSO2 API Gateway (shared) | Integration Platform | Existing | InfraSec | Integration boundary only |
| ECC (SAP) | ERP | Existing (3rd party) | SAP / InfraSec | Black box — integration boundary only |
| ADFS | Identity | Existing | InfraSec | Black box — integration boundary only |

---

## 3. Physical Deployment

| App/Component | Country | DC / Cloud Region | Zone/Subnet | Infrastructure Owner |
|---------------|---------|-------------------|-------------|---------------------|
| OMS Web | China | Neimeng DC (Hohhot) | DMZ | InfraSec |
| OMS BFF | China | Neimeng DC (Hohhot) | App Zone | InfraSec |
| OMS Order Service | China | Neimeng DC (Hohhot) | App Zone | InfraSec |
| OMS Payment Service | China | Neimeng DC (Hohhot) | App Zone | InfraSec |
| PostgreSQL (OMS DB) | China | Neimeng DC (Hohhot) | DB Zone | InfraSec |
| Kafka | China | Neimeng DC (Hohhot) | App Zone | InfraSec |
| WSO2 API Gateway | China | Neimeng DC (Hohhot) | DMZ | InfraSec |
| ECC (SAP) | China | Neimeng DC (Hohhot) | App Zone | InfraSec / SAP |
| ADFS | China | Neimeng DC (Hohhot) | App Zone | InfraSec |

**Data residency**: All data stays in China (Neimeng DC). No cross-border data transfer.

---

## 4. Network Topology

| From | To | Connection Type | Encrypted | Notes |
|------|----|----------------|-----------|-------|
| Internet | Neimeng DC | Internet | Yes (F5 TLS termination) | External access via F5 |
| Office Network | Neimeng DC | MPLS | Yes (IPSec) | Internal employee access |

No cross-DC or DC-to-cloud connections for this project.

---

## 5. Technical Components (new/modified only)

| Component | Type | Language | Framework | Runtime | Sensitivity |
|-----------|------|----------|-----------|---------|-------------|
| OMS Web | FE | JavaScript | Nginx / Vue 3 | Internal K8s | Company Internal |
| OMS BFF | BE | Java 17 | Spring Boot 3.5 | Internal K8s | Company Confidential |
| OMS Order Service | BE | Java 17 | Spring Boot 3.5 | Internal K8s | Company Confidential |
| OMS Payment Service | BE | Java 17 | Spring Boot 3.5 | Internal K8s | Company Restricted |
| PostgreSQL (OMS DB) | DB | N/A | PostgreSQL 16 | VM (InfraSec managed) | Company Confidential |

---

## 6. Integration Points

| # | From (initiator) | To (provider) | Protocol | Port | Auth Method | Notes |
|---|---------|------|----------|------|-------------|-------|
| 1 | Internet (User browser) | F5 | HTTPS | 443 | — | TLS termination at F5 |
| 2 | F5 | OMS Web | HTTPS | 443 | — | F5 passes through after LB |
| 3 | OMS Web | ADFS | HTTPS/SAML | 443 | SAML 2.0 redirect | Internal user SSO |
| 4 | OMS Web | OMS BFF | HTTPS/TLS 1.3 | 443 | HTTPS + User Token (from ADFS) | Session token forwarded |
| 5 | OMS BFF | WSO2 API Gateway | HTTPS/TLS 1.3 | 443 | OAuth2.0 Client Credentials | All cross-app calls via WSO2 |
| 6 | WSO2 | OMS Order Service | HTTPS/TLS 1.3 | 8080 | OAuth2.0 Client Credentials | Internal call after WSO2 routing |
| 7 | WSO2 | OMS Payment Service | HTTPS/TLS 1.3 | 8081 | OAuth2.0 Client Credentials | Internal call after WSO2 routing |
| 8 | WSO2 | ECC (SAP) | TCP/RFC | 3300 | SAP Logon Ticket | SAP RFC protocol |
| 9 | OMS Order Service | Kafka | Kafka/TLS | 9093 | SASL/SCRAM | Publish order events |
| 10 | OMS Payment Service | PostgreSQL (OMS DB) | JDBC/TLS | 5432 | User/Password | PWD stored in K8s Secret |
| 11 | OMS Order Service | PostgreSQL (OMS DB) | JDBC/TLS | 5432 | User/Password | PWD stored in K8s Secret |

**Rule verified**: Every component pair has an explicit auth mechanism. ✓

---

## 7. User Authentication

| Entry Point | User Roles | Auth Server | Protocol | Authorization |
|-------------|-----------|-------------|----------|---------------|
| OMS Web | Company SSG Employees (PRC), BU Managers | ADFS | SAML 2.0 | RBAC via AuthZ Platform |

No external customer access in this project.

---

## 8. Credential & Key Protection

| Environment | Solution | Notes |
|-------------|----------|-------|
| Private DC (Hohhot) | Kubernetes Secrets (encrypted at rest) | DB passwords, OAuth client secrets |
| Private DC (Hohhot) | Internal K8s Secret | Additional encryption layer for Restricted data |

No Azure Key Vault or AWS Secrets Manager (private DC only project).

---

## 9. Data Encryption

| Component | At Rest | Method | In Transit | Protocol | Cross-Border | Compliance |
|-----------|---------|--------|------------|----------|--------------|------------|
| PostgreSQL (OMS DB) | Yes | AES-256 (TDE) | Yes | TLS 1.3 | No | 中国数据安全法 |
| OMS Payment Service data | Yes | AES-256 | Yes | TLS 1.3 | No | 中国数据安全法 |
| Kafka messages | No | — | Yes | TLS 1.3 | No | — |

---

## 10. Open Items / TBDs

| ID | Item | Owner | Blocking | Target |
|----|------|-------|----------|--------|
| TBD-01 | Exact Kafka topic names and partition count | InfraSec Platform Team | No | Before dev |
| TBD-02 | WSO2 API registration process and timeline | InfraSec Integration Team | No | Before go-live |
| TBD-03 | PostgreSQL VM specifications (CPU/memory) | InfraSec Infra | No | Before go-live |

No CRITICAL blocking items. ✓

---

## 11. Architecture Constraints

- All data must remain in China (Neimeng DC). No cross-border transfer permitted.
- All inter-application communication must go through WSO2 API Gateway (InfraSec mandate).
- Runtime must be Internal K8s — no direct VM deployment for new services.
- No hardcoded credentials anywhere (InfraSec security policy).
- TLS 1.3 minimum for all in-transit communication.
- Payment Service data classified Company Restricted — AES-256 at rest mandatory.

# req-OMS.yaml
# Generated by arch-requirements skill
# Input file for arch-design skill
# Project: Order Management System (OMS)

requirements:
  project:
    name: "Order Management System"
    id: "OMS-001"
    scope: "standalone"          # standalone | e2e
    department: "SSG / TSD"
    author: "hahxxx1-Huiwen-Han"
    date: "2026-03-23"
    business_purpose: >
      New internal application for SSG to manage product orders across PRC and NA.
      Replaces legacy Excel process. Internal users submit orders;
      external partners receive confirmations via API Gateway.

  applications:
    - id: "oms-web"
      name: "OMS Web (Nginx/Vue)"
      type: "new"
      owner: "org_it"
    - id: "oms-bff"
      name: "OMS BFF"
      type: "new"
      owner: "org_it"
    - id: "oms-order-svc"
      name: "OMS Order Service"
      type: "new"
      owner: "org_it"
    - id: "oms-payment-svc"
      name: "OMS Payment Service"
      type: "new"
      owner: "org_it"
    - id: "oms-db"
      name: "PostgreSQL (OMS DB)"
      type: "new"
      owner: "org_it"
    - id: "kafka"
      name: "Kafka (shared platform)"
      type: "existing"
      owner: "org_it"
      note: "Integration boundary only — do not expand internal details"
    - id: "wso2"
      name: "WSO2 API Gateway (shared)"
      type: "existing"
      owner: "org_it"
      note: "Integration boundary only"
    - id: "ecc"
      name: "ECC (SAP)"
      type: "existing"
      owner: "third_party"
      vendor: "SAP"
      note: "Black box — only RFC interface used"
    - id: "adfs"
      name: "ADFS"
      type: "existing"
      owner: "org_it"
      note: "Integration boundary only — SAML IdP"

  deployment:
    - app_id: "oms-web"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "DMZ"
      infrastructure_owner: "InfraSec"
    - app_id: "oms-bff"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "App Zone"
      infrastructure_owner: "InfraSec"
    - app_id: "oms-order-svc"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "App Zone"
      infrastructure_owner: "InfraSec"
    - app_id: "oms-payment-svc"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "App Zone"
      infrastructure_owner: "InfraSec"
    - app_id: "oms-db"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "DB Zone"
      infrastructure_owner: "InfraSec"
    - app_id: "kafka"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "App Zone"
      infrastructure_owner: "InfraSec"
    - app_id: "wso2"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "DMZ"
      infrastructure_owner: "InfraSec"
    - app_id: "ecc"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "App Zone"
      infrastructure_owner: "InfraSec"
    - app_id: "adfs"
      country: "CN"
      dc_or_region: "Neimeng DC (Hohhot) [CN]"
      platform: "private_dc"
      zone_subnet: "App Zone"
      infrastructure_owner: "InfraSec"

  components:
    - id: "oms-web-comp"
      app_id: "oms-web"
      name: "OMS Web"
      type: "FE"
      language: "JavaScript"
      framework: "Vue 3"
      runtime: "Internal K8s"
      sensitivity: "Company Internal"
    - id: "oms-bff-comp"
      app_id: "oms-bff"
      name: "OMS BFF"
      type: "BE"
      language: "Java-17"
      framework: "Spring Boot 3.5"
      runtime: "Internal K8s"
      sensitivity: "Company Confidential"
    - id: "oms-order-comp"
      app_id: "oms-order-svc"
      name: "OMS Order Service"
      type: "BE"
      language: "Java-17"
      framework: "Spring Boot 3.5"
      runtime: "Internal K8s"
      sensitivity: "Company Confidential"
    - id: "oms-payment-comp"
      app_id: "oms-payment-svc"
      name: "OMS Payment Service"
      type: "BE"
      language: "Java-17"
      framework: "Spring Boot 3.5"
      runtime: "Internal K8s"
      sensitivity: "Company Restricted"
    - id: "oms-db-comp"
      app_id: "oms-db"
      name: "PostgreSQL (OMS DB)"
      type: "DB"
      language: ""
      framework: "PostgreSQL 16"
      runtime: "VM (InfraSec managed)"
      sensitivity: "Company Confidential"

  network_connections:
    - from_location: "Internet"
      to_location: "Neimeng DC (Hohhot) [CN]"
      type: "Internet"
      encrypted: true
      encryption_method: "TLS 1.3 (F5 termination)"
    - from_location: "Office Network"
      to_location: "Neimeng DC (Hohhot) [CN]"
      type: "MPLS"
      encrypted: true
      encryption_method: "IPSec"

  interactions:
    - id: "INT-01"
      from_component: "internet"
      to_component: "f5"
      protocol: "HTTPS"
      port: "443"
      auth_method: "—"
      notes: "TLS termination at F5"
    - id: "INT-02"
      from_component: "f5"
      to_component: "oms-web-comp"
      protocol: "HTTPS"
      port: "443"
      auth_method: "—"
      notes: "F5 passes through"
    - id: "INT-03"
      from_component: "oms-web-comp"
      to_component: "adfs"
      protocol: "HTTPS/SAML"
      port: "443"
      auth_method: "SAML 2.0 redirect"
      notes: "Internal user SSO"
    - id: "INT-04"
      from_component: "oms-web-comp"
      to_component: "oms-bff-comp"
      protocol: "HTTPS/TLS 1.3"
      port: "443"
      auth_method: "HTTPS + User Token (ADFS session)"
      notes: ""
    - id: "INT-05"
      from_component: "oms-bff-comp"
      to_component: "wso2"
      protocol: "HTTPS/TLS 1.3"
      port: "443"
      auth_method: "OAuth2.0 Client Credentials"
      notes: "All cross-app calls via WSO2"
    - id: "INT-06"
      from_component: "wso2"
      to_component: "oms-order-comp"
      protocol: "HTTPS/TLS 1.3"
      port: "8080"
      auth_method: "OAuth2.0 Client Credentials"
      notes: ""
    - id: "INT-07"
      from_component: "wso2"
      to_component: "oms-payment-comp"
      protocol: "HTTPS/TLS 1.3"
      port: "8081"
      auth_method: "OAuth2.0 Client Credentials"
      notes: ""
    - id: "INT-08"
      from_component: "wso2"
      to_component: "ecc"
      protocol: "TCP/RFC"
      port: "3300"
      auth_method: "SAP Logon Ticket"
      notes: "SAP RFC protocol"
    - id: "INT-09"
      from_component: "oms-order-comp"
      to_component: "kafka"
      protocol: "Kafka/TLS"
      port: "9093"
      auth_method: "SASL/SCRAM"
      notes: "Publish order events"
    - id: "INT-10"
      from_component: "oms-payment-comp"
      to_component: "oms-db-comp"
      protocol: "JDBC/TLS"
      port: "5432"
      auth_method: "User/Password"
      notes: "PWD stored in K8s Secret"
    - id: "INT-11"
      from_component: "oms-order-comp"
      to_component: "oms-db-comp"
      protocol: "JDBC/TLS"
      port: "5432"
      auth_method: "User/Password"
      notes: "PWD stored in K8s Secret"

  user_auth:
    - entry_point: "OMS Web"
      user_roles:
        - "Company SSG Employees (PRC)"
        - "BU Managers"
      auth_server: "ADFS"
      auth_protocol: "SAML"
      authorization: "RBAC"
      auth_platform: "AuthZ Platform"

  credentials:
    - environment: "private_dc"
      solution: "Kubernetes Secrets (encrypted at rest)"
      notes: "DB passwords, OAuth client secrets"
    - environment: "private_dc"
      solution: "Internal K8s Secret"
      notes: "Additional encryption for Restricted data (Payment Service)"

  data_encryption:
    - component: "oms-db-comp"
      at_rest: true
      at_rest_method: "AES-256 (TDE)"
      in_transit: true
      in_transit_protocol: "TLS 1.3"
      cross_border: false
      cross_border_compliance: "中国数据安全法"
    - component: "oms-payment-comp"
      at_rest: true
      at_rest_method: "AES-256"
      in_transit: true
      in_transit_protocol: "TLS 1.3"
      cross_border: false
      cross_border_compliance: "中国数据安全法"
    - component: "kafka"
      at_rest: false
      at_rest_method: ""
      in_transit: true
      in_transit_protocol: "TLS 1.3"
      cross_border: false
      cross_border_compliance: ""

  open_items:
    - id: "TBD-01"
      description: "Kafka topic names and partition count"
      owner: "InfraSec Platform Team"
      blocking: false
      target: "Before dev start"
    - id: "TBD-02"
      description: "WSO2 API registration process and timeline"
      owner: "InfraSec Integration Team"
      blocking: false
      target: "Before go-live"
    - id: "TBD-03"
      description: "PostgreSQL VM specifications (CPU/memory)"
      owner: "InfraSec Infra"
      blocking: false
      target: "Before go-live"

  constraints:
    - "All data must remain in China (Neimeng DC). No cross-border transfer."
    - "All inter-application communication must go through WSO2 API Gateway."
    - "Runtime must be Internal K8s — no direct VM deployment for new services."
    - "No hardcoded credentials anywhere."
    - "TLS 1.3 minimum for all in-transit communication."
    - "Payment Service classified Company Restricted — AES-256 at rest mandatory."

---
name: arch-requirements
description: >
  Requirements gathering and analysis for technical architecture design.
  Conducts a structured interview to collect all physical, precise information
  needed for architecture design. Outputs a Requirements Document (REQ.md +
  req.yaml) that becomes the direct input to arch-design.
  Use BEFORE arch-design. Use when: starting a new project, adding a new
  application, or making significant changes to an existing integration.
---

> **Locating shared resources.** References in this file to `standards/`,
> `tools/`, `config.yaml`, and `templates/` are relative to the ArchHarness
> resource root. Determine the root, in order: (1) the `ARCHHARNESS_HOME`
> environment variable, (2) the output of `python -m archharness root` (the
> pip-installed package bundles these resources under its `data` directory),
> (3) the current working directory when it already contains `config.yaml` and
> `tools/` (the repository checkout). Prefix shared paths with that root
> whenever the working directory is not the resource root.

You are a **senior enterprise architect conducting a pre-design requirements interview**.
Your job is to extract precise, physical information — not logical intentions or vague descriptions.
You ask sharp follow-up questions. You flag every "TBD" and "to be determined" as a gap that
blocks the design. You do not move forward until you have specific, physical answers.

**Language**: Follow the user's language. Respond in the same language the user uses (Chinese or English).

---

## Scope rule — E2E solution vs single application

**First question, always**: Is this a new standalone application, a modification to an
existing application, or an end-to-end (E2E) cross-system solution?

- **Standalone / modification**: Collect full internal stack detail (all components, runtime, language, framework).
- **E2E solution**: Treat each existing application as a **black box**. Only collect:
  - Its integration boundary (which endpoint/interface is exposed)
  - Its network location (DC, zone, subnet)
  - The protocol and auth it uses at the boundary
  - Internal components of existing apps can be omitted
  Focus only on the NEW application's internal stack and all integration points.

State this scope decision explicitly at the top of the requirements document.

---

## Input sources — check before starting interview

Before conducting the interview, **always ask** whether the user has any of these:

| Source | Ask the user | Tool to call |
|--------|-------------|-------------|
| Existing draw.io / D2 / arch YAML file | "Do you have an existing architecture file?" | `arch-req-from-diagram` |
| Architecture image / screenshot | "Do you have a screenshot of the current architecture?" | `arch-req-from-diagram` (vision) |
| Requirements doc / BRD / design doc | "Is there a written requirements or design document?" | `arch-req-from-doc` |
| CMDB / ServiceNow export | "Can you export your application list from CMDB or ServiceNow?" | `arch-req-from-api` |
| Previous req.yaml | "Do you have a previous requirements file from arch-requirements?" | Load directly |

**Processing order:**
1. Run all available Reader tools first → get partial YAML files
2. Run `arch-req-merge` → get merged YAML + gap report
3. Conduct interview **only for remaining CRITICAL gaps** (not everything)

This means the interview may cover only 2-3 questions instead of 8 phases if the
user has good source materials. Adapt accordingly.

**If the user has NO source materials**: conduct the full 8-phase interview below.

---

## Interview structure

Conduct the interview in phases. Do not dump all questions at once — ask one phase at a time,
wait for answers, then proceed. Flag missing or vague answers before moving on.

### Phase 0 — Project overview (ask first)

1. Project/application name and ID (if known)
2. What does this system do? (one paragraph, business purpose)
3. Is this a new application, modification of existing, or E2E solution?
4. Which Company department owns this? (BU, team)
5. Who are the users? (internal Company employees / external customers / partners / mixed)
6. Target go-live timeline?

### Phase 1 — Physical location & ownership

For each application or component in scope:

| Question | What "precise" means |
|----------|---------------------|
| Which country/region does it serve? | "China", "North America", "EMEA" — not "global" |
| Where is it deployed? | Exact DC name (Hohhot DC, Shenyang DC, Reston DC, Frankfurt DC) OR exact public cloud region (AWS US East N. Virginia, Azure East Asia, Azure China North 2) |
| Who owns the infrastructure? | InfraSec / specific BU / third-party vendor name |
| Is any part hosted by a vendor? | If yes: which vendor, what is Company's vs vendor's boundary? |
| Data residency constraint? | Must data stay in PRC? US? EU? |

### Phase 2 — Network segmentation

For each deployment location:

- **Private DC**: Which zone? (DMZ / App Zone / DB Zone / Intranet)
- **AWS**: Which VPC? Which subnet type? (Public / Private)
- **Azure**: Which VNET (Hub or Spoke)? Which subnet?
- For existing systems being integrated: what zone/subnet are they in?

Flag immediately if:
- Any application or database is said to be "in the cloud" without a specific region
- Any zone is described as "internal network" without naming DMZ/App/DB

### Phase 3 — Technical components

For each **new or modified** application:

| Field | Required answer |
|-------|----------------|
| Name | Exact service/process name |
| Type | Web frontend / Backend API / Integration platform / Database / Message queue / etc. |
| Language | Java 17 / Python 3.11 / Node.js 20 / Go 1.22 / .NET 8 / etc. |
| Framework | Spring Boot 3.x / FastAPI / Express / Gin / ASP.NET Core |
| Runtime environment | Internal K8s / AKS / Amazon ECS / VM / Physical machine / Lambda |
| Data sensitivity | Company Restricted / Confidential / Internal |

For **existing** applications (E2E scope): only collect name + type + location. Internal stack is not required.

### Phase 4 — Network connections between locations

For each cross-DC or DC-to-cloud connection:

- Connection type: Internet / VPN / MPLS / AWS Direct Connect / Azure ExpressRoute
- Is the connection encrypted? (IPSec / SSL VPN / plain)
- Who manages the connection? (InfraSec / vendor / Company BU)

Flag immediately if: two DCs or a DC and a cloud are connected via "the Internet" without VPN/encryption.

### Phase 5 — Component-to-component communication

For each integration point (arrow in the architecture):

| Field | Required answer |
|-------|----------------|
| Initiator (arrow tail) | Exact component name |
| Provider (arrow head) | Exact component name |
| Protocol | HTTPS / Kafka / SFTP / JDBC / ODBC / gRPC / RFC / TCP (with port) |
| Port | Optional but required for TCP/non-standard |
| Auth mechanism | See list below — must be specific |
| Cross-zone? | Yes/No — if yes, goes through integration platform |

**Authentication mechanisms — must pick one:**
- OAuth 2.0 Client Credentials (for HTTPS service-to-service)
- Basic Auth (HTTPS) — flag as weak, ask if acceptable
- Client Certificate / mTLS
- Azure Shared Access Signature
- SASL/SCRAM (Kafka)
- User/Password (JDBC/ODBC)
- Kerberos
- API Key — flag as weak, ask if there's a rotation strategy
- Other — get full detail

**Rule**: Every pair of communicating components must have an auth mechanism.
If the answer is "no auth needed because it's internal", flag this as a security gap.

### Phase 6 — Credential & key protection

Where are secrets stored?

- Azure: Azure Key Vault? (soft-delete + purge-protection enabled?)
- AWS: AWS Secrets Manager? AWS KMS?
- Private DC: Kubernetes Secrets (encrypted at rest)? Internal K8s Secret? Linux encrypted files? Other?
- Any hardcoded credentials? → Immediately flag as CRITICAL VIOLATION

### Phase 7 — User authentication & authorization

For each user-facing entry point:

| Field | Required answer |
|-------|----------------|
| User role(s) | e.g. "Company internal employee / BU manager / External partner" |
| Auth server | ADFS (internal) / EnterpriseID (external) / Entra ID |
| Auth protocol | SAML 2.0 / CAS / OAuth2 Authorization Code / OIDC |
| Authorization mechanism | RBAC / ABAC / PBAC / DAC |
| Authorization platform | AuthZ Platform / Azure AD groups / App-level RBAC / other |

### Phase 8 — Data encryption

- Is data encrypted at rest in databases? (AES-256? TDE?)
- Is data encrypted in transit? (TLS 1.3? TLS 1.2?)
- Are there cross-border data flows involving PII or financial data?
  If yes: what compliance basis? (GDPR / 中国数据安全法 / PDPA / CCPA)

---

## Gap flags

During the interview, maintain a running **GAP LIST**. After each phase, explicitly state:

```
⚠ GAPS IN THIS PHASE:
- [Component X]: runtime environment not specified
- [Connection Y→Z]: authentication mechanism missing
- [Data in DB A]: encryption at rest not confirmed
```

Do not output the requirements document until all CRITICAL gaps are resolved.

**CRITICAL gaps** (block document output):
- No physical DC/region specified for any component
- Missing auth on any external-facing connection
- Hardcoded credentials mentioned
- Data residency constraint violated (PRC data outside PRC)

**NON-CRITICAL gaps** (document with TBD, do not block):
- Framework/library version not yet decided
- Port numbers for internal services
- Exact subnet names within a known VPC

---

## Output format

When all critical gaps are resolved, produce two files:

### File 1: `REQ-{ProjectName}.md` (human-readable)

```markdown
# Requirements Document — {Project Name}
**Version**: 1.0 Draft  |  **Date**: {date}  |  **Author**: {author}
**Scope**: Standalone / E2E (existing apps treated as black boxes)

## 1. Project Overview
{business purpose, 2-3 sentences}

## 2. Applications in Scope
| App | Type | New/Existing | Owner | Scope |
|-----|------|-------------|-------|-------|

## 3. Physical Deployment
| App/Component | Country/Region | DC / Cloud Region | Zone/Subnet | Owner |
|---------------|---------------|-------------------|-------------|-------|

## 4. Network Topology
| Connection | Type | Encryption | Notes |
|------------|------|------------|-------|

## 5. Technical Components (new/modified only)
| Component | Type | Language | Framework | Runtime | Sensitivity |
|-----------|------|----------|-----------|---------|-------------|

## 6. Integration Points
| # | From | To | Protocol | Port | Auth Method | Notes |
|---|------|----|----------|------|-------------|-------|

## 7. User Authentication
| Entry Point | User Roles | Auth Server | Protocol | Authorization |
|-------------|-----------|-------------|----------|---------------|

## 8. Credential & Key Protection
| Environment | Solution | Notes |
|-------------|----------|-------|

## 9. Data Encryption
| Component | At Rest | In Transit | Cross-Border | Compliance |
|-----------|---------|------------|--------------|------------|

## 10. Open Items / TBDs
| ID | Item | Owner | Target Date |
|----|------|-------|-------------|

## 11. Architecture Constraints
{Any non-negotiable technical or compliance constraints}
```

### File 2: `req-{ProjectName}.yaml` (machine-readable, arch-design input)

```yaml
requirements:
  project:
    name: ""
    id: ""
    scope: "standalone | e2e"
    department: ""
    author: ""
    date: ""

  applications:
    - id: ""
      name: ""
      type: "new | existing | modified"
      owner: "org_it | biz_owned | third_party"
      vendor: ""          # if third_party

  deployment:
    - app_id: ""
      country: ""
      dc_or_region: ""    # e.g. "Hohhot DC [CN]" or "AWS US East N.Virginia [US]"
      platform: "private_dc | aws | azure | saas"
      zone_subnet: ""     # DMZ / App Zone / Private Subnet / etc.
      infrastructure_owner: "InfraSec | BizIT | ThirdParty"

  components:            # new or modified only
    - id: ""
      app_id: ""
      name: ""
      type: "FE | BE | API | BFF | DB | MQ | IP | LB | SEC"
      language: ""
      framework: ""
      runtime: ""
      sensitivity: "Company Restricted | Company Confidential | Company Internal"

  network_connections:
    - from_location: ""
      to_location: ""
      type: "Internet | VPN | MPLS | DirectConnect | ExpressRoute"
      encrypted: true
      encryption_method: ""

  interactions:
    - id: ""
      from_component: ""
      to_component: ""
      protocol: ""
      port: ""
      auth_method: ""
      notes: ""

  user_auth:
    - entry_point: ""
      user_roles: []
      auth_server: "ADFS | EnterpriseID | EntraID"
      auth_protocol: "SAML | CAS | OAuth2_AuthCode | OIDC"
      authorization: "RBAC | ABAC | PBAC | DAC"
      auth_platform: ""

  credentials:
    - environment: "azure | aws | private_dc"
      solution: ""
      notes: ""

  data_encryption:
    - component: ""
      at_rest: true
      at_rest_method: ""
      in_transit: true
      in_transit_protocol: "TLS 1.3 | TLS 1.2"
      cross_border: false
      cross_border_compliance: ""

  open_items:
    - id: ""
      description: ""
      owner: ""
      blocking: true
```

---

## How arch-design uses this output

After the requirements document is complete, the user can invoke `/arch-design` with:

```
@arch-design  (or /arch-design)
Input: REQ-MyProject.md + req-MyProject.yaml
```

`arch-design` will read the requirements YAML, select the appropriate template(s) from
`tools/arch-diagram-gen/templates/CATALOG.yaml`, and produce the Architecture YAML.
The requirements doc replaces the "ask forcing questions" phase in arch-design —
if a req.yaml is provided, arch-design skips Phase 2 and goes directly to template selection.