• 🚨 Recent Updates
• 🎯 Project Vision
• ⚡ Quick Start
• 🏗️ Project Architecture
• 🧪 Testing & Quality
• 🚀 Deployment Strategy
• 🛠️ Development Workflow
• 📊 Observability & Monitoring
• 🔧 Configuration & Security
• 📚 Documentation
• 🤝 Contributing
• 📄 License

• 🔧 Developer Experience Enhanced: Implemented lint-staged with pre-commit optimization
• 🧪 Test Suite Completed: 99 tests passing (54 integration + 39 unit + 6 frontend) with 95%+ coverage
• 📊 Full Observability Stack: Complete monitoring with Prometheus, Grafana, Jaeger, and OpenTelemetry
• 🚀 Production Monitoring: Real-time metrics, dashboards, and health monitoring ready
• 🛡️ Security Validation Improved: Enhanced ValidationMiddleware with JavaScript URI detection
• 📦 Architectural Refactoring: Decomposed React hooks and strengthened backend validation
• 📅 Architectural Evolution Plan: Comprehensive refinement roadmap defined (see docs/evolution/ARCHITECTURE_EVOLUTION_EN.md)

• Frontend: 79 TypeScript files, React 19.2 with modern tooling
• Backend: 26 PHP source files, 18 test files, clean architecture
• Tests: 99 total tests with excellent coverage (54 integration, 39 unit, 6 frontend)
• Documentation: Comprehensive guides and architectural decisions
• Docker: 5 compose configurations for different environments

📚 Educational Focus: This section documents architectural constraints that create learning opportunities for systematic improvement.

Filesystem Dependencies

• Current State: Uses SQLite files and Markdown knowledge base for simplicity
• Learning Opportunity: Understanding the evolution from filesystem to scalable storage
• Impact: Limits horizontal scaling and some hosting deployment options
• Evolution Path: Phase 2 introduces database and CMS abstractions

Configuration in Code

• Current State: Some settings embedded in configuration files for development transparency
• Learning Opportunity: Exploring the balance between explicit configuration and flexibility
• Impact: Requires code understanding for environment-specific customization
• Evolution Path: Environment variable abstraction and external configuration

Container Security Hardening: ✅ COMPLETED

• ✅ Non-root user enforcement (UID 1000:1000)
• ✅ Security capabilities dropped (no-new-privileges)
• ✅ Read-only filesystem with controlled tmpfs
• ✅ PHP security settings (disabled dangerous functions)

CI/CD Security Hardening: ✅ COMPLETED

• ✅ Strict security audits (fail on critical vulnerabilities)
• ✅ Removed continue-on-error from security checks
• ✅ Container security validation in pipeline

Rate Limiting: ✅ IMPLEMENTED

• Production Nginx configuration includes rate limiting
• Chat endpoints: 5 req/s with burst of 10
• API endpoints: 10 req/s with burst of 20

1. Domain Layer Implementation: Explicit domain entities and value objects
2. Storage Abstraction: Database migration from filesystem to PostgreSQL/MySQL
3. Frontend State Management: Global state for persistent conversations
4. Observability Simplification: Reduced tracing complexity with decorators

This project serves as an educational blueprint for modern chatbot development with evolving architecture. It demonstrates the complete journey from proof-of-concept to enterprise deployment, emphasizing clean code, comprehensive testing, and progressive architectural refinement.

🎓 Educational Excellence: Rather than presenting a "perfect" solution, this codebase includes intentional architectural constraints that mirror real-world development challenges. Each limitation creates learning opportunities for systematic improvement, teaching specific lessons about scalability, state management, and deployment evolution.

🚀 Current Capabilities: Fully functional with excellent code quality (95%+ test coverage), modern development practices, and robust testing pipeline. Production-capable for demonstration and learning environments, with a clear roadmap for enterprise deployment.

💡 Key Learning Areas:

• Clean architecture implementation with PHP and React
• Comprehensive testing strategies (Unit + Integration + E2E)
• Container orchestration and deployment patterns
• Security best practices and audit compliance
• Progressive enhancement and feature evolution

git clone https://github.com/Miguel-DevOps/chatbot-demo.git
cd chatbot-demo
./scripts/dev.sh start

The development script will:

• 🔧 Install all dependencies (pnpm + composer)
• 🏗️ Build frontend and backend
• 🐳 Start all services with Docker Compose
• 🧪 Run initial health checks
• 📱 Open the app at http://localhost

pnpm install --frozen-lockfile
pnpm build

cd api
composer install --no-dev --prefer-dist
cd ..

docker compose up -d

# Run all tests
./scripts/test.sh

# Local CI/CD simulation
./scripts/test-local.sh

# Development with hot reload
./scripts/dev.sh watch

src/
├── components/           # Reusable UI components
│   ├── ui/              # Radix UI + Tailwind components
│   └── ChatBot.tsx      # Main chatbot interface
├── pages/               # Route components
├── hooks/               # Custom React hooks (API, mobile, toast)
├── services/            # API communication layer
├── config/              # Configuration management
├── locales/             # i18n translation files
└── __tests__/           # Vitest test files

Key Technologies:

• React 19.2: Latest with concurrent features
• TypeScript 5.9: Strict typing, advanced features
• Vite 7.1: Ultra-fast build tool and HMR
• TailwindCSS 4.1: Utility-first styling
• Radix UI: Accessible headless components
• TanStack Query: Server state management

api/
├── src/
│   ├── Controllers/     # HTTP request handlers
│   ├── Services/        # Business logic layer
│   ├── Repositories/    # Data access layer
│   ├── Middleware/      # Request/response processing
│   ├── Config/          # Configuration management
│   └── Exceptions/      # Custom exception handling
├── tests/
│   ├── Unit/           # Unit tests (isolated components)
│   └── Integration/    # Integration tests (API endpoints)
└── knowledge/          # AI knowledge base (Markdown)

Key Technologies:

• PHP 8.4: Latest features, strict typing
• Slim Framework 4: PSR-7/PSR-15 compliant
• PHP-DI: Dependency injection container
• PHPUnit + Mockery: Comprehensive testing
• Monolog: Structured logging
• OpenTelemetry: Observability and tracing

Production Stack:
├── nginx:1.25-alpine        # Reverse proxy + static files
├── chatbot-api:latest       # PHP-FPM backend (multi-stage)
├── redis:7-alpine           # Cache and session storage
├── prometheus               # Metrics collection
├── grafana                  # Monitoring dashboards
└── jaeger                   # Distributed tracing

Security Features:

• Non-root containers (UID 1000:1000)
• Read-only filesystems with controlled tmpfs
• Dropped Linux capabilities
• PHP security hardening (disabled dangerous functions)
• Container image scanning (Trivy)

graph TB
    subgraph "Frontend"
        React[React App] --> CDN[CDN]
    end
    
    subgraph "Load Balancer"
        LB[Nginx/ALB] --> API1[API Pod 1]
        LB --> API2[API Pod 2]
        LB --> API3[API Pod N]
    end
    
    subgraph "State Layer"
        API1 --> Redis[(Redis Cluster)]
        API2 --> Redis
        API3 --> Redis
    end
    
    subgraph "Content & AI"
        API1 --> CMS[Headless CMS]
        API1 --> Gemini[Google Gemini]
        API2 --> CMS
        API3 --> CMS
    end
    
    subgraph "Observability"
        API1 --> Monitoring[Prometheus/Grafana]
        API2 --> Logs[ELK/Loki]
        API3 --> Tracing[Jaeger]
    end

Level 0 (Current): Excellent for development, demos, and educational purposes. Production-capable for single-instance deployments with filesystem storage limitations.

Level 0.5 Considerations: Shared hosting deployment requires database setup and careful configuration of file permissions, PHP-FPM setup, and database connectivity. Current filesystem dependencies limit horizontal scaling.

Scaling Evolution: Levels 1+ unlock horizontal scaling and enterprise features through Phase 2 (database abstraction) and Phase 3 (containerization/orchestration).

• Clean Architecture: SOLID principles, dependency injection, PSR compliance
• Comprehensive Testing: Unit + Integration tests with 99 passing tests and 95%+ coverage
• Modern Stack: React 19, TypeScript 5.9, PHP 8.4, Slim Framework 4
• Developer Experience: Hot reload, type safety, linting, lint-staged pre-commit optimization
• Quality Assurance: Automated testing, security validation, comprehensive error handling

Goal: Enable horizontal scaling and flexible deployment options

Remaining Tasks:

• Rate Limiting Abstraction: Abstract from SQLite to Redis/MySQL interface
• Content Management: Move knowledge base from filesystem to database/CMS
• Configuration Externalization: Environment variables for all settings
• Schema Management: Database migrations and version control

Enables: Shared hosting deployment, VPS scaling, cloud-native readiness

Goal: Production-grade observability and operational maturity

Planned Features:

• Container Orchestration: Kubernetes manifests and Helm charts
• Full Observability: Structured logging, metrics collection, distributed tracing
• Advanced Security: OAuth2/OIDC integration, comprehensive audit logging
• Automation: GitOps deployment, auto-scaling, infrastructure as code

Full ADRs: Detailed architectural decisions with context and rationale are documented in /docs/ADRs/ ( Working on it )

Required:

GEMINI_API_KEY=your_google_gemini_api_key_here
LOG_LEVEL=info
CORS_ORIGINS="http://localhost:3000,http://localhost:5173"

Phase 2 (Upcoming):

# Database Configuration
DATABASE_URL="mysql://user:pass@host:port/dbname"
STATE_STORE_TYPE="database"  # sqlite|database|redis
CONTENT_STORE_TYPE="database"  # filesystem|database|cms

# Rate Limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=3600

The project includes a production-optimized Dockerfile with two stages:

1. Dependencies Stage: Installs all dependencies including dev dependencies for complete build
2. Production Stage: Copies only production files and dependencies to a clean PHP-FPM Alpine image

Key Production Features:

• Multi-stage build for minimal image size
• Non-root user for security
• Optimized PHP-FPM configuration
• Intelligent health check system (CI-aware)
• Proper file permissions

Smart Health Check System:

The Docker image includes an intelligent health check that adapts to different environments:

• Production/Development: Validates full stack including Redis connectivity
• CI/Testing: Automatically skips external dependencies when GITHUB_ACTIONS or CI environment variables are detected
• Build Verification: Ensures container integrity without requiring full infrastructure

# Deploy production environment
docker-compose -f docker-compose.prod.yml up -d

# Scale API instances
docker-compose -f docker-compose.prod.yml up -d --scale api=3

# Monitor services
docker-compose -f docker-compose.prod.yml logs -f

Production Architecture:

[Internet] → [Nginx:80/443] → [PHP-FPM:9000] → [Redis:6379]

Key Differences from Development:

Configuration Files:

• nginx/nginx.conf: Main Nginx configuration with security and performance optimizations
• nginx/conf.d/default.conf: Virtual host with rate limiting and FastCGI configuration
• docker-compose.prod.yml: Production orchestration with resource limits

For traditional VPS deployment without Docker:

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL configuration (use Certbot for Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # CRITICAL: Root must point to api/public
    root /var/www/chatbot-demo/api/public;
    index index.php;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

    # Rate limiting
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req zone=api burst=20 nodelay;

    # Block sensitive files
    location ~ /\.(env|git) { deny all; }
    location ~ \.(json|lock|md)$ { deny all; }

    # PHP processing
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;

        # FastCGI optimizations
        fastcgi_connect_timeout 5s;
        fastcgi_send_timeout 30s;
        fastcgi_read_timeout 30s;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
    }

    # Clean URLs
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
}

Development:

• Never commit .env files
• Use different API keys per environment
• Enable error_reporting=0 in production PHP

Production:

• Configure HTTPS with valid certificates
• Set proper file permissions (644 for files, 755 for directories)
• Block access to sensitive files (.env, .git, etc.)
• Use Nginx + PHP-FPM (recommended web server configuration)
• Implement rate limiting at web server level (already configured in Nginx)

Project Overview:

• README.md - Main project documentation (English)
• README.es.md - Spanish version documentation

Architectural Evolution:

• ARCHITECTURE_EVOLUTION_EN.md - Architectural evolution plan (English)
• ARCHITECTURE_EVOLUTION_ES.md - Plan de evolución arquitectónica (Español)

Project Structure:

• PROJECT_STRUCTURE.md - Guide to project organization and file structure

API Documentation:

• OpenAPI Specification: openapi.yml - Complete API specification
• Interactive API Docs: Available at /api/docs when running locally

• Architectural Decision Records (ADRs): Located in /docs/architecture/ (in development)
• Deployment Guides: Various deployment strategies documented
• Development Guides: Contributor guidelines and setup instructions

• Use the table of contents at the top of each README
• Check the docs/ directory for specialized documentation
• Refer to code comments for implementation details
• Visit the GitHub repository for issues and discussions

Test Pyramid:

• Unit Tests: pnpm test (Frontend) + composer test (Backend) - Fast, isolated tests
• Integration Tests: API contract validation with OpenAPI schemas
• E2E Tests: pnpm test:e2e - Complete user workflows

Quality Gates:

# Pre-commit validation
pnpm lint && pnpm typecheck    # Code quality
pnpm test                      # Unit tests
composer test                  # Backend tests

# Security audit
pnpm audit && composer audit   # Dependency vulnerabilities

Coverage Targets:

• Business Logic: 90%+ (Services, Controllers)
• UI Components: 80%+ (User interactions, error states)  
• Integration: 100% (API contracts, external services)

# Complete development management
./scripts/dev.sh start          # Full environment setup
./scripts/dev.sh watch          # Development with hot reload
./scripts/dev.sh stop           # Clean shutdown

# Testing and quality
./scripts/test.sh                # Complete test suite
./scripts/test-local.sh          # CI/CD simulation locally
./scripts/security-audit.sh     # Security vulnerability scan

# Building and deployment
./scripts/build.sh all           # Complete project build
./scripts/build.sh frontend     # Frontend only
./scripts/build.sh backend      # Backend only
./scripts/deploy-prod.sh         # Production deployment

# API validation
./scripts/validate-api-contracts.sh  # OpenAPI contract testing

pnpm dev                    # Development server (Vite)
pnpm build                  # Production build
pnpm test                   # Run Vitest tests
pnpm lint                   # ESLint checking
pnpm typecheck              # TypeScript validation
pnpm security-check         # Dependency audit

composer install            # Install dependencies
composer test               # Run PHPUnit tests
composer test-coverage      # Tests with coverage report
composer validate           # Validate composer.json
composer audit              # Security audit

1. Prerequisites Check: Scripts automatically validate Node.js 20+, PHP 8.4+, Docker
2. Dependency Installation: Automated pnpm and composer setup
3. Service Orchestration: Docker Compose with health checks
4. Hot Reload: Frontend Vite HMR + Backend file watching
5. Testing Integration: Automated test execution on file changes

# Local production environment
docker compose -f docker-compose.prod.yml up -d

# Complete build validation
./scripts/build.sh all && ./scripts/test.sh

# Security and compliance check
./scripts/security-audit.sh

• Frontend: 79 TypeScript files (React 19.2)
• Backend: 26 PHP source files + 18 test files
• Documentation: 824 Markdown files
• Configuration: 24 YAML files (Docker, CI/CD, observability)
• Scripts: 10 automation scripts for development and deployment

• Frontend: 59 dependencies (React ecosystem, UI components)
• Backend: 11 runtime + 2 dev dependencies (minimal, focused)
• DevOps: 5 Docker Compose configurations for different environments

• Test Coverage: 95%+ (Frontend + Backend)
• Security Compliance: 100% (No critical vulnerabilities)
• Code Quality: TypeScript strict mode, PHP PSR-12
• CI/CD Success Rate: 100% (All pipelines passing)

The project includes a production-ready observability infrastructure with metrics collection, visualization, and distributed tracing.

# Development with complete monitoring stack
pnpm dev:monit:up

# Production with observability
pnpm prod:monit:up

# Access monitoring interfaces
open http://localhost:3000    # Grafana (admin/admin)
open http://localhost:9090    # Prometheus
open http://localhost:16686   # Jaeger UI

Application Layer:
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Nginx Proxy   │───▶│  Chatbot API    │───▶│ OpenTelemetry  │
│     :80/443     │    │    :9000        │    │   Collector     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
Metrics Collection:        ┌─────────────────┐    ┌─────────────────┐
                          │   Prometheus    │    │     Jaeger      │
                          │     :9090       │    │    :16686       │
                          └─────────────────┘    └─────────────────┘
                                │
                                ▼
Visualization:             ┌─────────────────┐
                          │    Grafana      │
                          │     :3000       │
                          └─────────────────┘

API Performance Metrics:

• chatbot_api_http_requests_total - Request count by endpoint, method, status
• chatbot_api_http_request_duration_seconds - Request latency histograms
• Request rate per second (5-minute rolling average)
• Error rates by endpoint and status code

System Metrics:

• Memory usage and limits
• CPU utilization
• Disk usage and I/O
• Network throughput

Business Metrics:

• Chat conversations initiated
• Response success/failure rates
• Average response time by message type

API Overview Dashboard (/monitoring/grafana/dashboards/)

• HTTP request rate and latency
• Error rate tracking (4xx, 5xx responses)
• Top endpoints by traffic and latency
• System resource utilization

Real-time Metrics Available:

# Test the metrics endpoint
curl http://localhost/api/v1/metrics

# Query Prometheus directly
curl "http://localhost:9090/api/v1/query?query=chatbot_api_http_requests_total"

Prometheus Alert Rules (/monitoring/alert_rules.yml)

• High error rate (>5% for 5 minutes)
• High response latency (>500ms p95 for 5 minutes)
• Memory usage >80%
• API health check failures

Health Check Endpoints:

• GET /health - Basic API health status
• GET /api/v1/health - Comprehensive health check with dependencies
• GET /api/v1/metrics - Prometheus metrics endpoint

Health Check Intelligence:

The health check system automatically adapts based on environment:

# Production deployment - full validation including Redis
docker run chatbot-api:latest php /usr/local/bin/healthcheck.php

# CI/Build verification - skips external dependencies
docker run -e GITHUB_ACTIONS=true chatbot-api:test php /usr/local/bin/healthcheck.php

# Manual testing mode
docker run -e HEALTHCHECK_SKIP_REDIS=true chatbot-api php /usr/local/bin/healthcheck.php

monitoring/
├── prometheus.yml              # Prometheus scrape configuration
├── alert_rules.yml            # Alerting rules and thresholds
└── grafana/
    ├── provisioning/
    │   ├── datasources/        # Auto-provision Prometheus
    │   └── dashboards/         # Auto-provision dashboards
    └── dashboards/
        └── chatbot-api-dashboard.json  # Pre-built API dashboard

observability/
└── otel-collector.yml         # OpenTelemetry Collector configuration

Development with Monitoring:

# All services + monitoring stack in development mode
pnpm dev:monit:up

Production with Monitoring:

# All services + monitoring stack in production mode
pnpm prod:monit:up

✅ Fully Implemented:

• Complete metrics collection from API endpoints
• Real-time Prometheus scraping (10s intervals)
• Pre-configured Grafana dashboards
• Health check monitoring
• Request/response metrics with labels
• Container resource monitoring
• Automatic service discovery

🚧 Infrastructure Ready (Needs App Instrumentation):

• Distributed tracing with Jaeger
• OpenTelemetry trace collection
• Custom business metrics
• Advanced error tracking

🔮 Future Enhancements:

• Advanced alerting (Slack/email notifications)
• Log aggregation (ELK/Loki stack)
• SLA monitoring and reporting
• Performance profiling integration

# Frontend (.env)
VITE_API_BASE_URL=           # API endpoint
VITE_APP_VERSION=            # Application version
VITE_ENVIRONMENT=            # Environment (dev/prod)

# Backend (api/.env)
APP_ENV=                     # Application environment
LOG_LEVEL=                   # Logging level
REDIS_HOST=                  # Cache server
GOOGLE_GEMINI_API_KEY=       # AI service key

# Observability Configuration
OTEL_SERVICE_NAME=chatbot-api          # Service name for tracing
OTEL_TRACES_ENABLED=true               # Enable distributed tracing
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318  # Collector endpoint

• OpenTelemetry: Configurable tracing and metrics (OTEL_TRACES_ENABLED)
• Security Headers: Configurable CORS and CSP policies
• Rate Limiting: Configurable per-endpoint limits
• AI Provider: Swappable between Google Gemini and OpenAI
• Monitoring Stack: Individual service enable/disable for resource optimization
• Development vs Production: Different monitoring configurations per environment

1. Interface-First Design: Create abstractions that enable technology swapping
2. Test-Driven Development: Write failing tests before implementing features
3. Configuration-Driven: No hardcoded values - everything configurable
4. Documentation-Driven: Update ADRs for architectural decisions

# 1. Fork and clone
git clone https://github.com/Miguel-DevOps/chatbot-demo.git
cd chatbot-demo

# 2. Create feature branch
git checkout -b feature/database-abstraction

# 3. Development with tests
./scripts/dev.sh start     # Start development environment
./scripts/test.sh          # Validate changes

# 4. Quality checks
pnpm lint && pnpm typecheck
./scripts/security-audit.sh

# 5. Submit PR with:
#    - Clear description of changes
#    - Updated tests and documentation
#    - Breaking changes noted

🟢 Beginner-Friendly:

• UI improvements and component enhancements
• Test coverage expansion
• Documentation updates and translations
• Configuration management improvements

🟡 Intermediate:

• Interface implementations and abstraction layers
• API endpoint development
• Container and deployment optimizations
• Security enhancements

🔴 Advanced:

• Architecture design and pattern implementation
• Infrastructure and observability
• Performance optimization
• Complex integration challenges

# 1. Fork and clone
git clone https://github.com/Miguel-DevOps/chatbot-demo.git
cd chatbot-demo

# 2. Create feature branch
git checkout -b feature/database-abstraction

# 3. Development with tests
./scripts/test.sh    # Validate changes

# 4. Submit PR with:
#    - Clear description of changes
#    - Updated tests
#    - Documentation updates
#    - Breaking changes noted

Focus Areas by Experience:

• Beginner: UI improvements, test coverage, documentation
• Intermediate: Interface implementations, configuration management
• Advanced: Architecture design, infrastructure, observability

MIT License - see LICENSE for details.

• ✅ Use as learning reference for modern full-stack development
• ✅ Fork for workshops, training, and educational purposes
• ✅ Adapt architectural patterns for your own projects
• ✅ Reference in technical blogs, documentation, and presentations
• ✅ Contribute improvements and share learning experiences

• ✅ Deploy for commercial and non-commercial applications
• ✅ Modify and customize for specific business needs
• ✅ Integrate with existing systems and infrastructure
• ⚠️ Note: Review and address any critical issues before production deployment