TSYSDevStack/SupportStack/demo/PRD.md

TSYS Developer Support Stack - Product Requirements Document (Demo Version)

📋 Document Overview

Document ID: PRD-SUPPORT-DEMO-001
Version: 1.0
Date: 2025-11-13
Author: TSYS Development Team
Status: Draft

---

🎯 Product Vision

To create a comprehensive, demo-ready developer support services stack that enhances developer productivity and quality of life for the TSYS engineering team. This stack is designed to run locally on every developer workstation, providing essential services for inner loop development workflows while maintaining security, simplicity, and adherence to free/libre/open source principles.

---

🏗️ Architecture Overview

Design Principles

1. Demo-First: All services configured for easy demonstration with no persistent data, hardcoded credentials, and minimal setup complexity
2. Service Discovery: Automatic service discovery via Homepage dashboard with Docker labels
3. FOSS Only: Exclusively use free/libre/open source software
4. Inner Loop Focus: Support daily development workflows, not project-specific dependencies
5. Workstation Local: Run locally on developer machines, not centralized infrastructure
6. Security Conscious: Demo-hardened configurations with clear separation from production

Service Categories

• Infrastructure Services: Core platform services (Pi-hole, Portainer)
• Monitoring & Observability: Metrics and visualization (InfluxDB, Grafana)
• Documentation & Diagramming: Knowledge management tools (Draw.io, Kroki)
• Developer Tools: Productivity and workflow enhancers

---

📊 Functional Requirements

FR-001: Infrastructure Services

FR-001.1: Pi-hole DNS Management

• Description: DNS-based ad blocking and network monitoring
• Requirements:
  • Web-based administration interface
  • DNS filtering capabilities
  • Network traffic monitoring
  • Demo configuration with default settings
  • Port assignment: 4006
  • Health check endpoint: HTTP GET /
  • Homepage integration with Infrastructure group

FR-001.2: Portainer Container Management

• Description: Web-based Docker container management interface
• Requirements:
  • Container lifecycle management (start/stop/restart)
  • Image management and registry integration
  • Volume and network management
  • User authentication (demo credentials)
  • Port assignment: 4007
  • Health check endpoint: HTTP GET /
  • Homepage integration with Infrastructure group

FR-002: Monitoring & Observability

FR-002.1: InfluxDB Time Series Database

• Description: High-performance time series database for metrics storage
• Requirements:
  • HTTP API for data ingestion and querying
  • Web-based administration interface
  • Demo database with sample data
  • Port assignment: 4008
  • Health check endpoint: HTTP GET /ping
  • Homepage integration with Monitoring group

FR-002.2: Grafana Visualization Platform

• Description: Analytics and visualization platform for time series data
• Requirements:
  • Pre-configured data source connection to InfluxDB
  • Demo dashboards for system metrics
  • Web-based dashboard creation and editing
  • Admin credentials: admin/demo_password
  • Port assignment: 4009
  • Health check endpoint: HTTP GET /api/health
  • Homepage integration with Monitoring group

FR-003: Documentation & Diagramming

FR-003.1: Draw.io Diagramming Server

• Description: Web-based diagramming and flowchart application
• Requirements:
  • Browser-based diagram creation and editing
  • Export to multiple formats (PNG, SVG, PDF)
  • Integration with cloud storage (optional)
  • No authentication required (demo mode)
  • Port assignment: 4010
  • Health check endpoint: HTTP GET /
  • Homepage integration with Documentation group

FR-003.2: Kroki Diagrams as a Service

• Description: Service for converting text diagrams to images
• Requirements:
  • Support for multiple diagram types (PlantUML, Mermaid, GraphViz)
  • HTTP API for diagram generation
  • Simple web interface for testing
  • No authentication required (demo mode)
  • Port assignment: 4011
  • Health check endpoint: HTTP GET /health
  • Homepage integration with Documentation group

---

🔧 Technical Requirements

TR-001: Docker Integration

• All services must be containerized using official Docker images
• Services must use consistent naming convention: tsysdevstack-supportstack-{service}
• All services must include comprehensive health checks
• Services must include proper Homepage labels for auto-discovery
• Restart policy: unless-stopped

TR-002: Network Configuration

• All services must use the tsysdevstack_supportstack network
• Port assignments must follow the 4000+ range pattern
• Services must be accessible via 192.168.3.6:{port}
• Inter-service communication via container names

TR-003: Data Management

• No persistent data storage (demo mode)
• Use Docker volumes for temporary data only
• All data must be reset on container restart
• Hardcoded demo credentials only
• No encryption or security hardening

TR-004: Service Discovery

• All services must include Homepage labels:
  • homepage.group: Service category
  • homepage.name: Display name
  • homepage.icon: Appropriate icon
  • homepage.href: Full URL
  • homepage.description: Brief service description

---

🎨 User Experience Requirements

UX-001: Homepage Dashboard

• Single entry point for all services via Homepage at port 4000
• Automatic service discovery and organization
• Consistent visual design and navigation
• Real-time service status indicators

UX-002: Service Accessibility

• All services accessible via web browser
• No complex setup or configuration required
• Default credentials where authentication is needed
• Clear error messages and troubleshooting guidance

UX-003: Demo Experience

• One-command deployment: docker compose up -d
• Services ready within 60 seconds
• All features immediately accessible
• No data persistence between sessions

---

🔒 Security Requirements

SEC-001: Demo Security Model

• All services configured for demo/development use only
• Hardcoded credentials clearly marked as demo-only
• No external network access except for image pulls
• No encryption or security hardening

SEC-002: Network Isolation

• Services isolated within Docker network
• Only necessary ports exposed to host
• No inter-container privilege escalation
• Docker socket proxy for secure API access

---

📋 Non-Functional Requirements

NFR-001: Performance

• All services must start within 60 seconds
• Health checks must complete within 10 seconds
• Memory usage per service: < 512MB (where applicable)
• CPU usage: < 25% per service (idle)

NFR-002: Reliability

• All services must include health checks
• Automatic restart on failure
• Graceful shutdown handling
• Dependency management between services

NFR-003: Maintainability

• Clear, commented Docker Compose configuration
• Consistent service naming and organization
• Comprehensive documentation
• Easy service addition/removal

---

🧪 Testing Requirements

TST-001: Automated Testing

• Comprehensive test suite (test-stack.sh)
• Service health validation
• Port accessibility verification
• Service discovery functionality
• Resource usage monitoring

TST-002: Manual Testing

• All web interfaces accessible and functional
• Demo credentials work correctly
• Service integration testing
• User workflow validation

---

📚 Documentation Requirements

DOC-001: Technical Documentation

• Updated README.md with all services
• Service access information
• Configuration details
• Troubleshooting guide

DOC-002: User Documentation

• Quick start guide
• Service descriptions and use cases
• Demo credentials reference
• FAQ section

---

✅ Acceptance Criteria

AC-001: Deployment Success

• All services start successfully with docker compose up -d
• All services pass health checks within 60 seconds
• Homepage discovers and displays all services
• All web interfaces accessible via browser

AC-002: Functionality Verification

• Pi-hole web interface loads and functions
• Portainer manages containers correctly
• InfluxDB accepts data and responds to queries
• Grafana connects to InfluxDB and displays dashboards
• Draw.io creates and exports diagrams
• Kroki generates diagrams from text

AC-003: Integration Testing

• Service discovery works correctly
• Inter-service communication functions
• Health checks trigger appropriately
• Resource usage remains within limits

---

🚀 Success Metrics

Deployment Metrics

• Time to full stack readiness: < 2 minutes
• Service success rate: 100%
• Health check pass rate: 100%

User Experience Metrics

• Single-command deployment success
• All services accessible via Homepage
• No configuration required for basic use

---

📅 Implementation Timeline

Phase 1: Core Infrastructure (Week 1)

• Pi-hole implementation
• Portainer integration
• Basic service discovery validation

Phase 2: Monitoring Stack (Week 1)

• InfluxDB deployment
• Grafana configuration
• Dashboard creation

Phase 3: Documentation Tools (Week 2)

• Draw.io server setup
• Kroki service implementation
• Integration testing

Phase 4: Testing & Documentation (Week 2)

• Comprehensive test suite
• Documentation updates
• Final validation

---

🔄 Change Management

Version Control

• All changes tracked via Git
• Conventional commit messages
• Atomic commits with clear descriptions

Quality Assurance

• Automated testing on all changes
• Manual validation of new services
• Documentation updates with each change

---

📞 Support & Maintenance

Troubleshooting

• Service logs accessible via docker compose logs
• Health check status via docker compose ps
• Common issues documented in README

Updates

• Regular image updates via Docker Hub
• Configuration changes tracked in Git
• Backward compatibility maintained where possible

---

📋 Appendix

A. Port Assignments

Service	Port	Group
Homepage	4000	Developer Tools
Atuin	4001	Developer Tools
Wakapi	4002	Developer Tools
ArchiveBox	4003	Developer Tools
Tube Archivist	4004	Developer Tools
MailHog	4005	Developer Tools
Pi-hole	4006	Infrastructure
Portainer	4007	Infrastructure
InfluxDB	4008	Monitoring
Grafana	4009	Monitoring
Draw.io	4010	Documentation
Kroki	4011	Documentation

B. Demo Credentials

Service	Username	Password
Grafana	admin	demo_password
Portainer	admin	demo_password

C. Service Dependencies

• Pi-hole: No dependencies
• Portainer: Docker Socket Proxy
• InfluxDB: No dependencies
• Grafana: InfluxDB
• Draw.io: No dependencies
• Kroki: No dependencies

---

Document End

This PRD serves as the source of truth for the TSYS Developer Support Stack demo implementation and will be used for audit and quality assurance purposes.