================================================================================
DBIS Core Lite - Deployment Requirements
Hardware and Software Dependencies
================================================================================

PROJECT: DBIS Core Lite - IBM 800 Terminal to Core Banking Payment System
VERSION: 1.0.0
LICENSE: PROPRIETARY - Organisation Mondiale Du Numérique, L.P.B.C.A.

================================================================================
HARDWARE REQUIREMENTS
================================================================================

MINIMUM REQUIREMENTS (Development/Testing):
- CPU: 2 cores (x86_64 or ARM64)
- RAM: 4 GB
- Storage: 20 GB (SSD recommended)
- Network: 100 Mbps connection with outbound TLS/HTTPS access (port 443)
- Network Ports: 
  * 3000 (Application HTTP)
  * 5432 (PostgreSQL - if local)
  * 6379 (Redis - if local)

RECOMMENDED REQUIREMENTS (Production):
- CPU: 4+ cores (x86_64 or ARM64)
- RAM: 8 GB minimum, 16 GB recommended
- Storage: 100+ GB SSD (for database, logs, audit trail)
- Network: 1 Gbps connection with outbound TLS/HTTPS access (port 443)
- Network Ports:
  * 3000 (Application HTTP)
  * 5432 (PostgreSQL - if local)
  * 6379 (Redis - if local)
- High Availability: Multiple instances behind load balancer recommended
- Backup Storage: Separate storage for database backups and audit logs

PRODUCTION CONSIDERATIONS:
- Redundant network paths for TLS S2S connections
- Sufficient storage for audit log retention (7+ years recommended)
- Monitoring infrastructure (Prometheus, DataDog, or equivalent)
- Centralized logging infrastructure (ELK stack or equivalent)

================================================================================
SOFTWARE REQUIREMENTS - RUNTIME
================================================================================

OPERATING SYSTEM:
- Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+, or Alpine Linux 3.16+)
- Windows Server 2019+ (with WSL2 or native Node.js)
- macOS 12+ (for development only)
- Container: Any Docker-compatible OS (Docker 20.10+)

NODE.JS RUNTIME:
- Node.js 18.0.0 or higher (LTS recommended: 18.x or 20.x)
- npm 9.0.0 or higher (bundled with Node.js)
- TypeScript 5.3.3+ (for development builds)

DATABASE:
- PostgreSQL 14.0 or higher (14.x or 15.x recommended)
- PostgreSQL client tools (psql) for database setup
- Database extensions: None required (standard PostgreSQL)

CACHE/SESSION STORE (Optional but Recommended):
- Redis 6.0 or higher (6.x or 7.x recommended)
- Redis client tools (redis-cli) for management

================================================================================
SOFTWARE REQUIREMENTS - BUILD TOOLS (For Native Dependencies)
================================================================================

REQUIRED FOR BUILDING NATIVE MODULES (libxmljs2):
- Python 3.8+ (for node-gyp)
- Build tools:
  * GCC/G++ compiler (gcc, g++)
  * make
  * pkg-config
- System libraries:
  * libxml2-dev (or libxml2-devel on RHEL/CentOS)
  * libxml2 (runtime library)

INSTALLATION BY OS:

Ubuntu/Debian:
  sudo apt-get update
  sudo apt-get install -y build-essential python3 libxml2-dev

RHEL/CentOS/Fedora:
  sudo yum install -y gcc gcc-c++ make python3 libxml2-devel
  # OR for newer versions:
  sudo dnf install -y gcc gcc-c++ make python3 libxml2-devel

Alpine Linux:
  apk add --no-cache python3 make g++ libxml2-dev

macOS:
  xcode-select --install
  brew install libxml2

Windows:
  Install Visual Studio Build Tools or Visual Studio Community
  Install Python 3.8+ from python.org

================================================================================
SOFTWARE REQUIREMENTS - CONTAINERIZATION (Optional)
================================================================================

DOCKER DEPLOYMENT:
- Docker Engine 20.10.0 or higher
- Docker Compose 2.0.0 or higher (v2 format)
- Container runtime: containerd, runc, or compatible

KUBERNETES DEPLOYMENT (If applicable):
- Kubernetes 1.24+ (if using K8s)
- kubectl 1.24+
- Helm 3.0+ (if using Helm charts)

================================================================================
SOFTWARE REQUIREMENTS - SECURITY & CERTIFICATES
================================================================================

TLS/SSL CERTIFICATES (For mTLS if required by receiver):
- Client Certificate (.crt or .pem format)
- Client Private Key (.key or .pem format)
- CA Certificate (.crt or .pem format) - if custom CA
- Certificate storage: Secure file system location with appropriate permissions

CERTIFICATE MANAGEMENT:
- OpenSSL 1.1.1+ (for certificate validation and management)
- Certificate renewal mechanism (if certificates expire)

NETWORK SECURITY:
- Firewall configuration (iptables, firewalld, or cloud firewall)
- Network access control for database and Redis ports
- TLS 1.2+ support in system libraries

================================================================================
SOFTWARE REQUIREMENTS - MONITORING & OBSERVABILITY (Production)
================================================================================

MONITORING (Recommended):
- Prometheus 2.30+ (metrics collection)
- Grafana 8.0+ (visualization) - Optional
- DataDog, New Relic, or equivalent APM tool - Optional

LOGGING (Recommended):
- Centralized logging solution (ELK Stack, Splunk, or equivalent)
- Log rotation utilities (logrotate)
- Winston daily rotate file support (included in application)

ALERTING:
- Alert manager (Prometheus Alertmanager or equivalent)
- Notification channels (email, Slack, PagerDuty, etc.)

================================================================================
SOFTWARE REQUIREMENTS - DATABASE MANAGEMENT
================================================================================

DATABASE TOOLS:
- PostgreSQL client (psql) - for schema setup and maintenance
- Database backup tools (pg_dump, pg_restore)
- Database migration tools (included in application: npm run migrate)

BACKUP SOFTWARE:
- Automated backup solution for PostgreSQL
- Backup storage system (local or cloud)
- Restore testing capability

================================================================================
SOFTWARE REQUIREMENTS - DEVELOPMENT/CI-CD (If applicable)
================================================================================

VERSION CONTROL:
- Git 2.30+ (for source code management)

CI/CD TOOLS (If applicable):
- GitHub Actions, GitLab CI, Jenkins, or equivalent
- Docker registry access (if using containerized deployment)

TESTING:
- Jest 29.7.0+ (included in devDependencies)
- Supertest 6.3.3+ (included in devDependencies)

================================================================================
NODE.JS DEPENDENCIES (Runtime)
================================================================================

PRODUCTION DEPENDENCIES (Installed via npm install):
- express ^4.18.2
- cors ^2.8.5
- helmet ^7.1.0
- dotenv ^16.3.1
- bcryptjs ^2.4.3
- jsonwebtoken ^9.0.2
- pg ^8.11.3
- redis ^4.6.12
- uuid ^9.0.1
- xml2js ^0.6.2
- libxmljs2 ^0.26.2 (requires native build tools)
- joi ^17.11.0
- winston ^3.11.0
- winston-daily-rotate-file ^4.7.1
- zod ^3.22.4
- prom-client ^15.1.0
- express-prometheus-middleware ^1.2.0
- swagger-jsdoc ^6.2.8
- swagger-ui-express ^5.0.0

================================================================================
NODE.JS DEPENDENCIES (Development)
================================================================================

DEVELOPMENT DEPENDENCIES (Installed via npm install):
- TypeScript ^5.3.3
- ts-node ^10.9.2
- ts-node-dev ^2.0.0
- @types/* (various type definitions)
- eslint ^8.56.0
- @typescript-eslint/* ^6.17.0
- jest ^29.7.0
- ts-jest ^29.1.1
- supertest ^6.3.3

================================================================================
NETWORK REQUIREMENTS
================================================================================

INBOUND CONNECTIONS:
- Port 3000: HTTP application server (or custom port via PORT env var)
- Port 5432: PostgreSQL (if running locally, should be firewalled)
- Port 6379: Redis (if running locally, should be firewalled)

OUTBOUND CONNECTIONS:
- Port 443: TLS/HTTPS to receiver gateway (RECEIVER_IP:RECEIVER_PORT)
- Port 443: HTTPS for compliance screening services (if external)
- Port 443: HTTPS for package registry (npm) during installation

NETWORK CONFIGURATION:
- DNS resolution for receiver hostname (RECEIVER_SNI)
- SNI (Server Name Indication) support for TLS connections
- TLS 1.2+ protocol support
- Firewall rules to allow outbound TLS connections

================================================================================
STORAGE REQUIREMENTS
================================================================================

APPLICATION STORAGE:
- Source code: ~50 MB
- node_modules: ~200-300 MB (production), ~400-500 MB (development)
- Compiled dist/: ~10-20 MB
- Logs directory: Variable (depends on log retention policy)
- Audit logs: 7+ years retention recommended (configurable)

DATABASE STORAGE:
- Initial database: ~100 MB
- Growth rate: Depends on transaction volume
- Indexes: Additional 20-30% overhead
- Backup storage: 2-3x database size recommended

REDIS STORAGE (If used):
- Session storage: ~10-50 MB (depends on session count and TTL)
- Cache storage: Variable (depends on cache policy)

TOTAL STORAGE ESTIMATE:
- Minimum: 20 GB
- Recommended: 100+ GB (with growth and backup space)

================================================================================
ENVIRONMENT VARIABLES (Configuration)
================================================================================

REQUIRED ENVIRONMENT VARIABLES:
- NODE_ENV (development|production|test)
- PORT (application port, default: 3000)
- DATABASE_URL (PostgreSQL connection string)
- JWT_SECRET (secure random secret for JWT signing)
- RECEIVER_IP (receiver gateway IP address)
- RECEIVER_PORT (receiver gateway port, typically 443)
- RECEIVER_SNI (Server Name Indication for TLS)

OPTIONAL ENVIRONMENT VARIABLES:
- REDIS_URL (Redis connection string, optional)
- JWT_EXPIRES_IN (JWT expiration, default: 8h)
- RECEIVER_TLS_VERSION (TLS version, default: TLSv1.3)
- CLIENT_CERT_PATH (mTLS client certificate path)
- CLIENT_KEY_PATH (mTLS client private key path)
- CA_CERT_PATH (mTLS CA certificate path)
- COMPLIANCE_TIMEOUT (compliance screening timeout, default: 5000ms)
- AUDIT_RETENTION_YEARS (audit log retention, default: 7)
- LOG_LEVEL (logging level: error|warn|info|debug)

================================================================================
DEPLOYMENT OPTIONS
================================================================================

OPTION 1: NATIVE DEPLOYMENT
- Install Node.js, PostgreSQL, Redis directly on host
- Run: npm install, npm run build, npm start
- Requires: All build tools and system libraries

OPTION 2: DOCKER DEPLOYMENT (Recommended)
- Use Docker Compose for full stack
- Includes: Application, PostgreSQL, Redis
- Requires: Docker Engine and Docker Compose
- Run: docker-compose up -d

OPTION 3: KUBERNETES DEPLOYMENT
- Deploy as Kubernetes pods/services
- Requires: Kubernetes cluster, container registry
- Custom Helm charts or manifests needed

================================================================================
POST-DEPLOYMENT REQUIREMENTS
================================================================================

INITIAL SETUP:
- Database schema initialization (src/database/schema.sql)
- Initial operator creation (Maker, Checker, Admin roles)
- JWT secret generation (secure random string)
- Certificate installation (if mTLS required)
- Environment configuration (.env file)

ONGOING MAINTENANCE:
- Regular database backups
- Log rotation and archival
- Security updates (OS, Node.js, dependencies)
- Certificate renewal (if applicable)
- Compliance list updates
- Monitoring and alerting configuration

================================================================================
NOTES
================================================================================

1. libxmljs2 is a native module requiring compilation. Ensure build tools
   are installed before running npm install.

2. For production deployments, use npm ci instead of npm install for
   deterministic builds.

3. PostgreSQL and Redis can be hosted externally (cloud services) or
   locally. Adjust DATABASE_URL and REDIS_URL accordingly.

4. TLS certificates for mTLS are optional and only required if the receiver
   gateway requires mutual TLS authentication.

5. The application supports horizontal scaling. Run multiple instances
   behind a load balancer for high availability.

6. Audit logs must be retained per regulatory requirements (default: 7 years).

7. All network connections should use TLS 1.2+ for security compliance.

================================================================================
END OF DEPLOYMENT REQUIREMENTS
================================================================================