proxmox/docs/02-architecture/PHOENIX_SYSTEM_BOUNDARY_STATEMENT.md

# Phoenix System Boundary Statement

**System Name:** Phoenix Core  
**System Version:** 1.0.0  
**Classification:** Unclassified  
**Document Version:** 1.0.0  
**Last Updated:** 2026-01-09  
**Status:** Active Documentation
**Author:** Infrastructure Team

---

## 1. System Identification

### 1.1 System Name and Acronym

**System Name:** Phoenix Core  
**System Acronym:** PHX-CORE  
**System Aliases:** Phoenix, Phoenix v1.0

### 1.2 System Purpose

Phoenix Core provides a secure, scalable application platform supporting:
- Authentication and authorization services (Keycloak)
- Application programming interface (GraphQL API)
- Web-based user interface (Portal)
- Data persistence layer (PostgreSQL)

Phoenix Core serves as the foundation for future service migrations and expansion within the Sankofa infrastructure ecosystem.

### 1.3 System Owner and Point of Contact

**System Owner:** Infrastructure Team  
**Technical Contact:** Infrastructure Team  
**Security Contact:** Infrastructure Team

---

## 2. System Boundary Definition

### 2.1 Components Included in System Boundary

The Phoenix Core system boundary includes the following components:

#### 2.1.1 Computing Resources

**VMID Range:** 8600-8699 (Phoenix Core allocation)

| Component | VMID | IP Address | Function |
|-----------|------|------------|----------|
| Phoenix API | 8600 | 10.160.0.10 | Application API server (GraphQL) |
| Phoenix Portal | 8601 | 10.160.0.11 | Web-based user interface |
| Phoenix Keycloak | 8602 | 10.160.0.12 | Identity and access management |
| Phoenix PostgreSQL | 8603 | 10.160.0.13 | Database server |

**Physical Host:** r630-01 (192.168.11.11) - Proxmox VE hypervisor

#### 2.1.2 Network Infrastructure

**VLAN:** 160 (SANKOFA-SVC)  
**Subnet:** 10.160.0.0/22  
**Gateway:** 10.160.0.1  
**Network Type:** Private (RFC 1918)

**Network Segments:**
- Internal service-to-service communication (10.160.0.0/22)
- Management network connectivity (192.168.11.0/24 via ER605)
- Egress NAT connectivity (via Block #5 when assigned)

#### 2.1.3 Storage Infrastructure

**Storage Type:** Proxmox thin-provisioned LVM (thin1)  
**Allocation:**
- VMID 8600: 50GB
- VMID 8601: 50GB
- VMID 8602: 30GB
- VMID 8603: 50GB

**Total Allocated:** 180GB

#### 2.1.4 Software Components

**Operating System:** Ubuntu 22.04 LTS (container base)  
**Application Stack:**
- Node.js 18 (API and Portal)
- PostgreSQL 16 (Database)
- Keycloak 24.0.0 (Identity Provider)
- Next.js (Portal framework)

### 2.2 Components Excluded from System Boundary

The following components are **explicitly excluded** from the Phoenix Core system boundary:

#### 2.2.1 Legacy Services

- **VMIDs 7800-7803 (Legacy Sankofa Services):**
  - sankofa-api-1 (7800, 192.168.11.13)
  - sankofa-portal-1 (7801, 192.168.11.16)
  - sankofa-keycloak-1 (7802, 192.168.11.17)
  - Legacy PostgreSQL (if exists)

**Rationale:** Legacy services operate on a separate network (192.168.11.x) and are not part of the Phoenix Core system.

#### 2.2.2 DBIS Core Services

- **VMIDs 10100-10151:** DBIS Core services (PostgreSQL, Redis, API, Frontend)
- **Location:** ml110 (192.168.11.10)
- **Network:** 192.168.11.x

**Rationale:** DBIS Core services are separate systems with distinct purposes and will be migrated to Phoenix in future phases.

#### 2.2.3 Blockchain Services

- **VMIDs 1000-1004:** Besu Validators
- **VMIDs 1500-1503:** Besu Sentries
- **VMIDs 2500-2502:** Besu RPC Nodes
- **VMIDs 2400-2402:** RPC Translator Services

**Rationale:** Blockchain services are separate systems with distinct purposes and security requirements.

#### 2.2.4 Infrastructure Services

- **VMID 102:** Cloudflare Tunnel
- **VMID 105:** Nginx Proxy Manager
- **VMID 130:** Monitoring Stack

**Rationale:** Infrastructure services are shared resources used by multiple systems, not part of Phoenix Core.

#### 2.2.5 Network Equipment

- **ER605 Router:** Network gateway and firewall
- **Network Switches:** Layer 2/3 network infrastructure
- **Proxmox Host:** Hypervisor infrastructure

**Rationale:** Network equipment is shared infrastructure, not part of the Phoenix Core application system.

---

## 3. System Architecture

### 3.1 Network Topology

```mermaid
graph TB
    subgraph MgmtVLAN["Management VLAN (11)<br/>192.168.11.0/24"]
        ProxmoxHost["Proxmox Host<br/>r630-01<br/>192.168.11.11"]
    end
    
    subgraph PhoenixVLAN["Phoenix VLAN (160)<br/>10.160.0.0/22"]
        API["Phoenix API<br/>VMID 8600<br/>10.160.0.10:4000"]
        Portal["Phoenix Portal<br/>VMID 8601<br/>10.160.0.11:3000"]
        Keycloak["Phoenix Keycloak<br/>VMID 8602<br/>10.160.0.12:8080"]
        PostgreSQL["Phoenix PostgreSQL<br/>VMID 8603<br/>10.160.0.13:5432"]
    end
    
    subgraph External["External Access"]
        DNS["DNS<br/>phoenix.sankofa.nexus"]
        Cloudflare["Cloudflare Tunnel<br/>(Future)"]
    end
    
    ProxmoxHost -->|Hosts| PhoenixVLAN
    Portal -->|HTTP/HTTPS| API
    Portal -->|OAuth/OIDC| Keycloak
    API -->|OAuth/OIDC| Keycloak
    API -->|SQL| PostgreSQL
    Keycloak -->|SQL| PostgreSQL
    External -->|Resolves to| PhoenixVLAN
```

### 3.2 Data Flow

#### 3.2.1 External Ingress (Future)

**Path:** External → DNS → NAT Gateway → Phoenix Services

1. External client resolves `api.phoenix.sankofa.nexus` via DNS
2. DNS returns private IP (10.160.0.10) or NAT gateway IP (when configured)
3. Traffic routes through ER605 NAT gateway
4. ER605 routes to Phoenix VLAN 160
5. Traffic reaches Phoenix API container

**Current State:** External ingress not yet configured. DNS records exist but NAT routing pending.

#### 3.2.2 Internal Communication

**Path:** Service-to-Service within VLAN 160

1. Portal (10.160.0.11) → API (10.160.0.10): GraphQL API calls
2. Portal (10.160.0.11) → Keycloak (10.160.0.12): Authentication requests
3. API (10.160.0.10) → Keycloak (10.160.0.12): Token validation
4. API (10.160.0.10) → PostgreSQL (10.160.0.13): Database queries
5. Keycloak (10.160.0.12) → PostgreSQL (10.160.0.13): Database queries

**Security:** All internal communication is unencrypted (HTTP) within the private VLAN. TLS encryption recommended for production.

#### 3.2.3 Management Access

**Path:** Management VLAN → Phoenix VLAN

1. Administrator on 192.168.11.x → ER605 Router
2. ER605 routes to VLAN 160 (via firewall rules)
3. Traffic reaches Phoenix services

**Purpose:** Administrative access, monitoring, logging, troubleshooting.

#### 3.2.4 Egress

**Path:** Phoenix Services → Internet

1. Phoenix services require outbound connectivity (updates, external APIs)
2. Traffic routes through ER605
3. ER605 performs NAT via Block #5 (when assigned)
4. Traffic egresses to Internet

**Purpose:** Software updates, external API calls, external service dependencies.

---

## 4. Trust Boundaries

### 4.1 Trust Zones

#### Zone 1: Phoenix Internal (Highest Trust)

**Components:** VMIDs 8600-8603 within VLAN 160  
**Trust Level:** High (same security domain)  
**Communication:** Service-to-service within VLAN 160  
**Security Controls:** Network segmentation, service authentication

#### Zone 2: Management Network (Administrative Trust)

**Components:** Management VLAN (192.168.11.0/24)  
**Trust Level:** Medium (administrative access)  
**Communication:** Management VLAN → Phoenix VLAN  
**Security Controls:** Firewall rules, source IP restrictions, SSH authentication

#### Zone 3: External Network (Untrusted)

**Components:** Internet, external clients  
**Trust Level:** Low (untrusted)  
**Communication:** External → Phoenix (via NAT/DNS)  
**Security Controls:** Firewall rules (deny by default), authentication, authorization, TLS encryption

### 4.2 Trust Boundary Crossings

**Crossings occur at:**

1. **ER605 Router (Management → Phoenix):**
   - Source: Management VLAN (192.168.11.0/24)
   - Destination: Phoenix VLAN (10.160.0.0/22)
   - Controls: Firewall rules, source IP filtering

2. **ER605 Router (External → Phoenix):**
   - Source: External/Internet
   - Destination: Phoenix VLAN (10.160.0.0/22)
   - Controls: Firewall rules (currently denied), future: NAT routing, TLS termination

3. **ER605 Router (Phoenix → External):**
   - Source: Phoenix VLAN (10.160.0.0/22)
   - Destination: Internet
   - Controls: Egress NAT, firewall rules

---

## 5. Security Controls

### 5.1 Network Security

**Control:** Network Segmentation  
**Implementation:** VLAN 160 isolation, firewall rules at ER605 router  
**Purpose:** Separate Phoenix services from other systems  
**Effectiveness:** High - VLAN isolation prevents unauthorized access

**Control:** Firewall Rules  
**Implementation:** ER605 router firewall rules (see firewall rules document)  
**Purpose:** Control access to Phoenix services  
**Effectiveness:** Medium - Depends on rule configuration accuracy

**Control:** Private IP Addressing  
**Implementation:** RFC 1918 private addresses (10.160.0.0/22)  
**Purpose:** Prevent direct Internet access, enable NAT  
**Effectiveness:** High - Private IPs are not routable on Internet

### 5.2 Access Control

**Control:** Keycloak Authentication  
**Implementation:** Keycloak identity provider (VMID 8602)  
**Purpose:** Centralized authentication and authorization  
**Effectiveness:** High - Industry-standard identity provider

**Control:** Service Authentication  
**Implementation:** OAuth 2.0 / OIDC tokens for API access  
**Purpose:** Authenticate service-to-service communication  
**Effectiveness:** Medium - Depends on proper token validation

**Control:** SSH Access Control  
**Implementation:** SSH key authentication, root password  
**Purpose:** Administrative access to containers  
**Effectiveness:** Medium - SSH keys provide strong authentication

### 5.3 Data Protection

**Control:** Database Access Control  
**Implementation:** PostgreSQL user authentication, role-based access  
**Purpose:** Control database access  
**Effectiveness:** Medium - Database users and passwords

**Control:** Data at Rest (Future)  
**Implementation:** Encryption at rest (not currently implemented)  
**Purpose:** Protect data if storage is compromised  
**Effectiveness:** N/A - Not implemented

**Control:** Data in Transit (Future)  
**Implementation:** TLS encryption for external access  
**Purpose:** Protect data during transmission  
**Effectiveness:** N/A - Not implemented (internal only currently)

### 5.4 Logging and Monitoring

**Control:** System Logs  
**Implementation:** systemd journal, application logs  
**Purpose:** Track system events and errors  
**Effectiveness:** Medium - Logs available but not centralized

**Control:** Access Logs (Future)  
**Implementation:** Application access logs, authentication logs  
**Purpose:** Track user access and authentication events  
**Effectiveness:** N/A - Not fully implemented

**Control:** Monitoring (Future)  
**Implementation:** Prometheus, Grafana (if integrated)  
**Purpose:** Monitor system health and performance  
**Effectiveness:** N/A - Not implemented

---

## 6. Operational Environment

### 6.1 Physical Environment

**Location:** On-premises datacenter  
**Hypervisor:** Proxmox VE (r630-01, 192.168.11.11)  
**Hardware:** Dell R630 server  
**Network Equipment:** ER605 router, managed switches

### 6.2 Virtual Environment

**Containerization:** LXC containers (unprivileged)  
**OS Template:** Ubuntu 22.04 LTS  
**Resource Allocation:**
- CPU: 12 cores total (2-4 cores per container)
- Memory: 12GB total (2-4GB per container)
- Storage: 180GB total (30-50GB per container)

### 6.3 Dependencies

**External Dependencies:**
- Internet connectivity (for software updates)
- DNS resolution (for external service calls)
- NTP servers (for time synchronization)

**Internal Dependencies:**
- ER605 router (for network routing and firewall)
- Proxmox host (for container execution)
- Storage infrastructure (thin1 LVM pool)

**Application Dependencies:**
- Node.js runtime (for API and Portal)
- PostgreSQL database (for data persistence)
- Keycloak identity provider (for authentication)

---

## 7. System Interfaces

### 7.1 External Interfaces

**Interface 1: HTTP/HTTPS API**  
**Protocol:** HTTP (internal), HTTPS (future external)  
**Port:** 4000 (API), 3000 (Portal), 8080 (Keycloak)  
**Authentication:** OAuth 2.0 / OIDC tokens  
**Status:** Internal only (external access pending)

**Interface 2: DNS**  
**Protocol:** DNS  
**Purpose:** Domain name resolution  
**Records:** api.phoenix.sankofa.nexus, auth.phoenix.sankofa.nexus, portal.phoenix.sankofa.nexus  
**Status:** Configured, pending NAT routing

### 7.2 Internal Interfaces

**Interface 3: Database**  
**Protocol:** PostgreSQL protocol (TCP)  
**Port:** 5432  
**Authentication:** Username/password (md5)  
**Access:** Service-to-service within VLAN 160

**Interface 4: Authentication**  
**Protocol:** OAuth 2.0 / OIDC (HTTP)  
**Port:** 8080  
**Authentication:** Client credentials, user credentials  
**Access:** Service-to-service and user-to-service

**Interface 5: Management**  
**Protocol:** SSH  
**Port:** 22  
**Authentication:** SSH keys, password  
**Access:** Management VLAN to Phoenix VLAN (admin only)

---

## 8. Compliance Considerations

### 8.1 Security Frameworks

**DoD RMF (Risk Management Framework):**  
- Phoenix Core is designed with DoD RMF principles in mind
- System boundary clearly defined
- Security controls documented
- Risk assessment recommended before production use

**NIST Cybersecurity Framework:**  
- Identify: System boundaries and assets defined
- Protect: Network segmentation, access controls implemented
- Detect: Logging available (monitoring recommended)
- Respond: Incident response procedures recommended
- Recover: Backup and recovery procedures recommended

### 8.2 Data Classification

**Data Types:**
- User authentication credentials (handled by Keycloak)
- Application data (stored in PostgreSQL)
- Session tokens (OAuth/OIDC)

**Classification:** Unclassified  
**Handling:** Standard security practices apply

### 8.3 Compliance Gaps (Future Work)

**Recommended Enhancements:**
- TLS encryption for all external interfaces
- Encryption at rest for database
- Centralized logging and monitoring
- Regular security audits
- Penetration testing
- Backup and recovery procedures
- Incident response procedures

---

## 9. Risk Assessment Summary

### 9.1 Identified Risks

**Risk 1: Unencrypted Internal Communication**  
**Likelihood:** High (current state)  
**Impact:** Medium (within private VLAN)  
**Mitigation:** Implement TLS for internal communication (recommended)

**Risk 2: No Encryption at Rest**  
**Likelihood:** Medium (storage compromise)  
**Impact:** High (data exposure)  
**Mitigation:** Implement database encryption at rest (recommended)

**Risk 3: Limited Logging and Monitoring**  
**Likelihood:** High (current state)  
**Impact:** Medium (difficulty detecting issues)  
**Mitigation:** Implement centralized logging and monitoring (recommended)

**Risk 4: Single Point of Failure (Database)**  
**Likelihood:** Low (hardware failure)  
**Impact:** High (complete system outage)  
**Mitigation:** Implement database replication (recommended for production)

**Risk 5: External Access Not Yet Configured**  
**Likelihood:** N/A (pending implementation)  
**Impact:** N/A  
**Mitigation:** Follow security best practices when implementing external access

### 9.2 Risk Acceptance

**Current State:** Phoenix Core is in initial deployment phase. Some security enhancements are deferred to future phases.

**Risk Acceptance:** Documented risks are accepted for initial deployment. Production deployment should address high-impact risks.

---

## 10. System Boundaries Diagram

```mermaid
graph TB
    subgraph Boundary["Phoenix Core System Boundary"]
        subgraph PhoenixVLAN["VLAN 160<br/>10.160.0.0/22"]
            API["API<br/>8600"]
            Portal["Portal<br/>8601"]
            Keycloak["Keycloak<br/>8602"]
            PostgreSQL["PostgreSQL<br/>8603"]
        end
    end
    
    subgraph Excluded["Excluded from Boundary"]
        Legacy["Legacy Services<br/>7800-7803<br/>192.168.11.x"]
        DBIS["DBIS Core<br/>10100-10151<br/>192.168.11.x"]
        Blockchain["Blockchain Services<br/>1000-2502<br/>192.168.11.x"]
        Infrastructure["Infrastructure<br/>102, 105, 130<br/>192.168.11.x"]
    end
    
    subgraph External["External Systems"]
        DNS["DNS<br/>Cloudflare"]
        Internet["Internet"]
        Mgmt["Management<br/>192.168.11.0/24"]
    end
    
    Boundary -->|Interfaces| External
    Boundary -.->|Not Included| Excluded
```

---

## 11. Document Control

### 11.1 Version History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0.0 | 2026-01-09 | Infrastructure Team | Initial system boundary statement |

### 11.2 Review Schedule

- **Initial Review:** After deployment validation
- **Quarterly Reviews:** Every 3 months
- **Change-Driven Reviews:** When system boundary changes

### 11.3 Approval

**Document Status:** Draft  
**Approval Status:** Pending  
**Reviewers:** Infrastructure Team, Security Team

---

## 12. References

- **Network Architecture:** `docs/02-architecture/NETWORK_ARCHITECTURE.md`
- **Phoenix Deployment Runbook:** `docs/03-deployment/PHOENIX_DEPLOYMENT_RUNBOOK.md`
- **Phoenix Firewall Rules:** `docs/04-configuration/PHOENIX_VLAN160_FIREWALL_RULES.md`
- **Phoenix DNS Template:** `docs/04-configuration/PHOENIX_DNS_ZONE_TEMPLATE.md`
- **VMID Allocation:** `docs/02-architecture/VMID_ALLOCATION_FINAL.md`

---

**Last Updated:** 2026-01-09  
**Document Status:** Draft  
**Classification:** Unclassified  
**Next Review:** After deployment validation