Skip to content

Requirements Traceability Matrix

Document Type: Requirements Architecture
Status: Draft
Version: 1.0
Last Updated: 2024-12-30
Owner: Product Management, Architecture Team


Purpose

This document provides comprehensive traceability between the Product Requirements Document (PRD) and the architecture, ensuring all requirements are addressed in the design and implementation. It maps functional requirements to components, non-functional requirements to design decisions, and stakeholder needs to capabilities.


Functional Requirements Mapping

FR-1: Application Deployment

Req ID Requirement Component(s) Implementation Status Version
FR-1.1.1 Git integration (GitHub, GitLab) Next.js API, simple-git, BullMQ /api/webhooks/*, Git client service ✅ Implemented v1.0
FR-1.1.2 Docker image deployment Next.js API, dockerode Docker client service ✅ Implemented v1.0
FR-1.1.3 Docker Compose support Next.js API, dockerode Compose parser, Service orchestration ✅ Implemented v1.0
FR-1.2.1 Build process with Nixpacks Build Worker, Nixpacks integration Background job worker ✅ Implemented v1.0
FR-1.2.2 Custom Dockerfile support Build Worker, Docker BuildKit Multi-stage build handler ✅ Implemented v1.0
FR-1.2.3 Build cache optimization Docker BuildKit, Redis Layer caching, Cache management ✅ Implemented v1.0
FR-1.3.1 Zero-downtime deployments Docker Swarm, Traefik Rolling update strategy ✅ Implemented v1.0
FR-1.3.2 Health checks Docker Swarm, dockerode Health check configuration ✅ Implemented v1.0
FR-1.3.3 Automatic rollback Deployment Engine Failure detection, Rollback logic ✅ Implemented v1.0
FR-1.4.1 Manual rollback Next.js API, Deployment Engine /api/deployments/:id/rollback ✅ Implemented v1.0
FR-1.4.2 Deployment history PostgreSQL, Prisma deployments table ✅ Implemented v1.0

Architecture References: - Component: Application Component Diagram (Deployment Engine) - Data: Data Model (deployments, deployment_logs, git_sources) - API: API Specification (/api/applications/:id/deploy)


FR-2: Application Management

Req ID Requirement Component(s) Implementation Status Version
FR-2.1.1 List applications Next.js API, PostgreSQL /api/applications endpoint ✅ Implemented v1.0
FR-2.1.2 Application details view Next.js API, React UI Application detail page ✅ Implemented v1.0
FR-2.1.3 Search and filter PostgreSQL, Prisma Full-text search, indexed queries ✅ Implemented v1.0
FR-2.2.1 Environment variables PostgreSQL (encrypted), Prisma env_vars table with encryption ✅ Implemented v1.0
FR-2.2.2 Resource limits (CPU, RAM) Docker Swarm, dockerode Service resource constraints ✅ Implemented v1.0
FR-2.2.3 Replica configuration Docker Swarm Service replication ✅ Implemented v1.0
FR-2.3.1 Start/stop applications Next.js API, Docker Swarm Service lifecycle management ✅ Implemented v1.0
FR-2.3.2 Restart applications Next.js API, Docker Swarm /api/applications/:id/restart ✅ Implemented v1.0
FR-2.3.3 Scale applications Next.js API, Docker Swarm /api/applications/:id/scale ✅ Implemented v1.0
FR-2.4.1 Application logs Docker Engine, dockerode Real-time log streaming ✅ Implemented v1.0
FR-2.4.2 Log search PostgreSQL full-text Indexed log storage ✅ Implemented v1.0
FR-2.4.3 Log export Next.js API Download logs endpoint ✅ Implemented v1.0

Architecture References: - Component: Application Component Diagram (Docker Client, API Routes) - Security: Security View (Environment variable encryption) - API: API Specification (/api/applications/*)


FR-3: Database Management

Req ID Requirement Component(s) Implementation Status Version
FR-3.1.1 PostgreSQL provisioning Next.js API, Docker Swarm Database service creation ✅ Implemented v1.5
FR-3.1.2 MySQL provisioning Next.js API, Docker Swarm Database service creation ✅ Implemented v1.5
FR-3.1.3 MongoDB provisioning Next.js API, Docker Swarm Database service creation ✅ Implemented v1.5
FR-3.1.4 Redis provisioning Next.js API, Docker Swarm Database service creation ✅ Implemented v1.5
FR-3.2.1 Connection string management PostgreSQL (encrypted) databases table with secrets ✅ Implemented v1.5
FR-3.2.2 Database credentials rotation Next.js API, Docker Secrets Credential update workflow 📋 Planned v2.0
FR-3.3.1 Database backups Backup script, S3 Automated pg_dump/mysqldump ✅ Implemented v1.5
FR-3.3.2 Backup scheduling Cron, BullMQ Scheduled job queue ✅ Implemented v1.5
FR-3.3.3 Backup restore Next.js API, Backup script Restore workflow ✅ Implemented v1.5
FR-3.4.1 Database metrics Prometheus, Grafana Database exporter integration ✅ Implemented v1.5

Architecture References: - Component: Application Component Diagram (Database Client) - Data: Data Model (databases, backups) - Flow: Data Flow Diagram (Database Backup Flow)


FR-4: Domain & SSL Management

Req ID Requirement Component(s) Implementation Status Version
FR-4.1.1 Custom domain assignment PostgreSQL, Traefik domains table, Traefik labels ✅ Implemented v1.0
FR-4.1.2 Wildcard domain support Traefik Traefik routing rules ✅ Implemented v1.0
FR-4.1.3 Multiple domains per app PostgreSQL, Traefik One-to-many relationship ✅ Implemented v1.0
FR-4.2.1 Let's Encrypt integration Traefik ACME protocol implementation ✅ Implemented v1.0
FR-4.2.2 Automatic certificate renewal Traefik Traefik certificate resolver ✅ Implemented v1.0
FR-4.2.3 Certificate storage Docker Volume, PostgreSQL Volume + DB backup ✅ Implemented v1.0
FR-4.3.1 HTTP to HTTPS redirect Traefik Middleware configuration ✅ Implemented v1.0
FR-4.3.2 HSTS headers Traefik Security headers middleware ✅ Implemented v1.0

Architecture References: - Component: Traefik Reverse Proxy - Flow: Data Flow Diagram (TLS Certificate Flow) - Data: Data Model (domains, certificates) - Decision: ADR-004 (Traefik selection)


FR-5: Monitoring & Observability

Req ID Requirement Component(s) Implementation Status Version
FR-5.1.1 Resource usage metrics Prometheus, cAdvisor Container metrics collection ✅ Implemented v1.5
FR-5.1.2 Application metrics Prometheus Application endpoint scraping ✅ Implemented v1.5
FR-5.1.3 Custom metrics Prometheus User-defined exporters ✅ Implemented v1.5
FR-5.2.1 Pre-built dashboards Grafana Dashboard templates ✅ Implemented v1.5
FR-5.2.2 Custom dashboards Grafana Dashboard builder UI ✅ Implemented v1.5
FR-5.2.3 Real-time charts Next.js UI, WebSocket Live metric streaming ✅ Implemented v1.5
FR-5.3.1 Alert configuration Prometheus Alertmanager Alert rules configuration ✅ Implemented v1.5
FR-5.3.2 Alert notifications Email, Slack, Discord Notification webhook system ✅ Implemented v1.5
FR-5.3.3 Alert history PostgreSQL alerts table ✅ Implemented v1.5

Architecture References: - Component: Monitoring Service - Flow: Data Flow Diagram (Monitoring Data Flow) - Technology: Technology Stack (Prometheus, Grafana)


FR-6: User & Team Management

Req ID Requirement Component(s) Implementation Status Version
FR-6.1.1 User registration Next.js API, bcrypt /api/auth/register ✅ Implemented v1.0
FR-6.1.2 Local authentication NextAuth.js, bcrypt Credentials provider ✅ Implemented v1.0
FR-6.1.3 OIDC authentication NextAuth.js OIDC provider integration ✅ Implemented v1.5
FR-6.1.4 Session management Redis, JWT Token-based sessions ✅ Implemented v1.0
FR-6.2.1 Team creation PostgreSQL, Prisma teams table ✅ Implemented v1.0
FR-6.2.2 Team member management PostgreSQL team_members table ✅ Implemented v1.0
FR-6.2.3 Role-based access control PostgreSQL, Middleware RBAC engine implementation ✅ Implemented v1.0
FR-6.3.1 Project organization PostgreSQL projects table hierarchy ✅ Implemented v1.0
FR-6.3.2 Project permissions RBAC Engine Resource-level permissions ✅ Implemented v1.0

Architecture References: - Component: Authentication Module - Security: Security View (Authentication & Authorization) - Data: Data Model (users, teams, projects) - Decision: ADR-002 (NextAuth.js)


FR-7: Server Management

Req ID Requirement Component(s) Implementation Status Version
FR-7.1.1 Single-server deployment Docker Swarm (single-node) Swarm initialization ✅ Implemented v1.0
FR-7.1.2 Multi-server cluster Docker Swarm (multi-node) Manager/worker topology ✅ Implemented v1.0
FR-7.2.1 SSH server connection Next.js API, node-ssh Remote server management ✅ Implemented v1.0
FR-7.2.2 Server health monitoring Prometheus, Node Exporter System metrics collection ✅ Implemented v1.5
FR-7.2.3 Server removal Next.js API, Docker Swarm Node drain and removal ✅ Implemented v1.0
FR-7.3.1 Load balancing Traefik, Docker Swarm Service distribution ✅ Implemented v1.0
FR-7.3.2 Automatic failover Docker Swarm Service rescheduling ✅ Implemented v1.0

Architecture References: - Deployment: Deployment Diagram (Multi-server topology) - Decision: ADR-001 (Docker Swarm selection) - Component: Docker Client


Non-Functional Requirements Mapping

NFR-1: Performance

NFR ID Requirement Architecture Decision Validation Method Status
NFR-1.1 <5 min deployment time Build cache, Docker BuildKit, BullMQ Performance testing ✅ Met
NFR-1.2 Support 100+ apps per instance Resource limits, efficient orchestration Load testing ✅ Met
NFR-1.3 <200ms API response time (p95) Redis caching, indexed queries Prometheus monitoring ✅ Met
NFR-1.4 <1s real-time log latency WebSocket streaming Real-time monitoring ✅ Met
NFR-1.5 <500ms page load time Next.js SSR, code splitting Lighthouse audits ✅ Met

Architecture References: - Flow: Data Flow Diagram (Caching Strategy) - Component: Cache Client (Redis) - Technology: Technology Stack (Performance Benchmarks)


NFR-2: Scalability

NFR ID Requirement Architecture Decision Validation Method Status
NFR-2.1 Horizontal scaling of apps Docker Swarm replication Load testing ✅ Met
NFR-2.2 Multi-server deployment Docker Swarm clustering Multi-node testing ✅ Met
NFR-2.3 Auto-scaling support Metrics-based scaling engine Feature implementation 📋 Planned v2.0
NFR-2.4 Database connection pooling Prisma connection pool (10 connections) Connection monitoring ✅ Met
NFR-2.5 Concurrent deployment handling BullMQ job queue (3 concurrent) Queue monitoring ✅ Met

Architecture References: - Deployment: Deployment Diagram (HA Pattern) - Roadmap: Implementation Roadmap (Auto-scaling Phase 3)


NFR-3: Reliability

NFR ID Requirement Architecture Decision Validation Method Status
NFR-3.1 99.9% uptime SLA HA deployment, health checks, monitoring Uptime monitoring ✅ Met
NFR-3.2 Zero-downtime deployments Rolling updates, health checks Deployment testing ✅ Met
NFR-3.3 Automatic rollback on failure Health check monitoring, rollback logic Failure testing ✅ Met
NFR-3.4 Data backup & recovery Automated backups (daily), S3 storage Restore testing ✅ Met
NFR-3.5 Service redundancy Multi-replica services, manager quorum Failure testing ✅ Met

Architecture References: - Security: Security View (High Availability) - Flow: Data Flow Diagram (Database Backup Flow) - Deployment: Deployment Diagram (HA Configuration)


NFR-4: Security

NFR ID Requirement Architecture Decision Validation Method Status
NFR-4.1 Encrypted secrets storage AES-256-GCM encryption, Docker Secrets Security audit ✅ Met
NFR-4.2 TLS/HTTPS enforcement Let's Encrypt, Traefik, HSTS SSL Labs testing ✅ Met
NFR-4.3 Password security bcrypt (cost 12) Security audit ✅ Met
NFR-4.4 JWT token security HS256/RS256 signing, 7-day expiry Token validation testing ✅ Met
NFR-4.5 RBAC enforcement Permission middleware, row-level security Authorization testing ✅ Met
NFR-4.6 Audit logging Immutable audit trail in PostgreSQL Compliance audit ✅ Met
NFR-4.7 Network isolation Security zones, Docker networks Network testing ✅ Met
NFR-4.8 Input validation Zod schema validation Penetration testing ✅ Met

Architecture References: - Security: Security View (all sections) - Component: Authentication Module - Data: Data Model (audit_logs, encryption) - Decision: ADR-003 (PostgreSQL RLS)


NFR-5: Usability

NFR ID Requirement Architecture Decision Validation Method Status
NFR-5.1 Intuitive UI Material UI, consistent design system User testing ✅ Met
NFR-5.2 <5 click deployment Streamlined workflow UX testing ✅ Met
NFR-5.3 Real-time feedback WebSocket updates, progress indicators User observation ✅ Met
NFR-5.4 Error messages clarity Structured error responses, helpful messages User feedback ✅ Met
NFR-5.5 Mobile responsive Responsive Material UI components Device testing ✅ Met
NFR-5.6 Dark mode support Theme system, user preferences Visual testing ✅ Met

Architecture References: - Component: Web Layer (React, Material UI) - API: API Specification (Error Handling) - Technology: Technology Stack (Frontend Stack)


NFR-6: Maintainability

NFR ID Requirement Architecture Decision Validation Method Status
NFR-6.1 Type-safe codebase TypeScript 5.3+ (strict mode) Build verification ✅ Met
NFR-6.2 API documentation OpenAPI 3.1, Swagger UI Documentation review ✅ Met
NFR-6.3 Code coverage >80% Jest unit tests, integration tests CI/CD checks ✅ Met
NFR-6.4 Automated testing Jest, Playwright, CI/CD pipeline Test execution ✅ Met
NFR-6.5 Logging & monitoring Structured logs, Prometheus metrics Log analysis ✅ Met
NFR-6.6 Database migrations Prisma migrations, version control Migration testing ✅ Met

Architecture References: - Component: Application Component Diagram (Testing Strategy) - Technology: Technology Stack (Development Tools) - API: API Specification (OpenAPI)


NFR-7: Compatibility

NFR ID Requirement Architecture Decision Validation Method Status
NFR-7.1 Docker 24.0+ Docker Engine compatibility Version testing ✅ Met
NFR-7.2 Node.js 20 LTS Node.js LTS support Runtime testing ✅ Met
NFR-7.3 PostgreSQL 16+ PostgreSQL compatibility Database testing ✅ Met
NFR-7.4 Multiple cloud providers Cloud-agnostic design Multi-cloud deployment ✅ Met
NFR-7.5 Bare metal support No cloud dependencies On-premise testing ✅ Met
NFR-7.6 ARM64 architecture Multi-arch Docker images ARM testing ✅ Met

Architecture References: - Technology: Technology Stack (Version Matrix, Cloud Compatibility) - Deployment: Deployment Diagram (Deployment Patterns)


Stakeholder Needs → Capabilities

Stakeholder Key Need Business Capability Components Status
Independent Developer Quick, cost-effective deployment Application Management Next.js UI, Docker Swarm, Deployment Engine ✅ Met
DevOps Engineer Full observability and control Monitoring & Operations Prometheus, Grafana, Monitoring Service ✅ Met
Small Team Collaboration and team management Team Collaboration Teams, RBAC, Projects ✅ Met
Enterprise Security and compliance Security & Access Control Authentication, Encryption, Audit Logs ✅ Met
Startup Scalability without complexity Infrastructure Management Docker Swarm, Multi-server support ✅ Met
Open Source Maintainer Self-hosted, no vendor lock-in Self-Hosting Capability All components (open source) ✅ Met
Educational Institution Cost-effective learning platform Application Management Complete PaaS functionality ✅ Met
System Administrator Easy maintenance Infrastructure Management Automated updates, Monitoring ✅ Met

Architecture References: - Business: Business Capability Model - Vision: Stakeholder Analysis - Business: Value Stream Mapping


Gap Analysis

Requirements Not Yet Addressed

1. FR-8.1: Multi-factor Authentication

  • Status: Planned for v3.0
  • Impact: High (enterprise security requirement)
  • Mitigation: OIDC providers support MFA
  • Timeline: Phase 4 - Sprint 23-24
  • Components: Authentication Module extension

2. FR-8.2: SAML/LDAP Authentication

  • Status: Planned for v3.0
  • Impact: High (enterprise requirement)
  • Dependencies: Advanced security infrastructure
  • Timeline: Phase 4 - Sprint 23-24
  • Components: Authentication Module, SAML/LDAP connectors

3. NFR-2.3: Automatic Scaling

  • Status: Planned for v2.0
  • Impact: Medium (performance optimization)
  • Dependencies: Metrics collection, decision engine
  • Timeline: Phase 3 - Sprint 15-16
  • Components: Auto-scaling Engine, Metrics Collector

4. FR-9.1: Multi-region Deployment

  • Status: Planned for v3.0
  • Impact: High (enterprise feature)
  • Dependencies: Cross-region networking, data replication
  • Timeline: Phase 4 - Sprint 21-22
  • Components: Multi-cluster orchestrator

5. FR-10.1: Advanced Deployment Strategies

  • Status: Planned for v2.0
  • Impact: Medium (deployment flexibility)
  • Features: Blue-green, canary deployments
  • Timeline: Phase 3 - Sprint 17-18
  • Components: Deployment Engine extension, Traffic splitting

Over-Delivered Features

1. Real-time WebSocket Updates

  • Original Requirement: Polling-based updates
  • Delivered: Real-time WebSocket streaming
  • Impact: Better user experience, lower latency
  • Components: WebSocket API, Real-time event bus

2. Comprehensive API Documentation

  • Original Requirement: Basic API docs
  • Delivered: OpenAPI 3.1 spec, Swagger UI, SDK examples
  • Impact: Better developer experience
  • Components: API Specification, Interactive documentation

3. Material UI Component Library

  • Original Requirement: Functional UI
  • Delivered: Enterprise-grade Material UI with theming
  • Impact: Professional appearance, better UX
  • Components: Web Layer with comprehensive component library

Compliance Matrix

Standards Compliance

Standard Applicable Requirements Architecture Components Compliance Status
OWASP Top 10 NFR-4.1 - NFR-4.8 Security View, Authentication ✅ Compliant
CIS Docker Benchmark NFR-4.7 Docker Security, Network Isolation ✅ Compliant
SOC 2 Type II NFR-4.6, NFR-3.4 Audit Logs, Backups 📋 In Progress
GDPR NFR-4.1, FR-6.4.1 Data Encryption, Data Deletion ✅ Compliant
ISO 27001 NFR-4.* Security View (all sections) 📋 Planned v3.0

Architecture References: - Security: Security View (Compliance Section) - Vision: Architecture Principles (Security by Design)


Test Coverage Matrix

Unit Test Coverage

Component Coverage Critical Paths Status
Authentication Module 95% Login, OIDC, session management ✅ Met
Deployment Engine 88% Deploy, rollback, health checks ✅ Met
Docker Client 92% Service create/update, logs ✅ Met
API Routes 85% All endpoints, error handling ✅ Met
Database Client 90% Queries, migrations, transactions ✅ Met

Integration Test Coverage

Integration Coverage Critical Scenarios Status
Git → Build → Deploy 90% Full deployment pipeline ✅ Met
Authentication → Authorization 95% RBAC enforcement ✅ Met
Database Backup → Restore 85% Backup lifecycle ✅ Met
Monitoring → Alerting 80% Alert workflows ✅ Met

E2E Test Coverage

User Journey Coverage Test Scenarios Status
New user onboarding 90% Register → Deploy first app ✅ Met
Application lifecycle 85% Create → Deploy → Monitor → Delete ✅ Met
Team collaboration 80% Create team → Add member → Deploy ✅ Met
Database provisioning 85% Create → Backup → Restore ✅ Met

Architecture References: - Component: Application Component Diagram (Testing Strategy) - Technology: Technology Stack (Testing Tools)


Change Impact Analysis

Architecture Changes Required for Planned Features

Auto-scaling (v2.0)

Impacted Components: - Monitoring Service (enhanced metrics collection) - Deployment Engine (scaling decision logic) - Docker Client (dynamic scaling API)

New Components: - Scaling Decision Engine - Metrics Aggregator

Estimated Effort: 4 weeks (2 developers)


Multi-region (v3.0)

Impacted Components: - Docker Client (multi-cluster management) - Database Client (replication support) - Traefik configuration (geo-routing)

New Components: - Multi-cluster Orchestrator - Cross-region Network Manager - Region Selector UI

Estimated Effort: 8 weeks (3 developers + 1 DevOps)


Document Revision History

Version Date Changes Author
1.0 2024-12-30 Initial traceability matrix Architecture Team

  • Product Requirements Document: Source requirements
  • Business Capability Model: Capability definitions
  • Value Stream Mapping: Value delivery flows
  • Stakeholder Analysis: Stakeholder needs
  • Data Model: Data architecture
  • Component Diagram: Component architecture
  • API Specification: API requirements
  • Technology Stack: Technical implementation
  • Implementation Roadmap: Delivery timeline
  • Security View: Security requirements

Document Version: 1.0
Last Updated: 2024-12-30
Next Review: 2025-03-30
Approved By: Product Management, Architecture Team, Quality Assurance