adamsDCIM - Modern Data Center Infrastructure Management

A comprehensive, modern data center infrastructure management system with a React frontend, PHP backend API, and robust authentication system.

🚀 Modernization Overview

This project represents a complete modernization of the legacy openDCIM system, featuring:

• Modern React SPA with TypeScript and Mantine UI
• RESTful API v2 with JWT authentication and RBAC
• Unified SSO supporting SAML, OIDC, LDAP, and Apache auth
• Containerized deployment with Docker and Kubernetes
• Comprehensive testing with CI/CD pipelines
• Security hardening with modern best practices

📋 Table of Contents

• Features
• Architecture
• Quick Start
• Development
• API Documentation
• Deployment
• Testing
• Contributing
• License

✨ Features

🔐 Authentication & Security

• JWT-based authentication with access and refresh tokens
• Unified SSO integration (SAML, OIDC, LDAP, Apache)
• Role-based access control (RBAC) with granular permissions
• Security headers and CSP protection
• Password hardening with Argon2id hashing
• Session management with secure cookies

🖥️ Modern Frontend

• React 18 with TypeScript
• Mantine UI for beautiful, accessible components
• React Query for efficient data fetching
• Real-time charts with Recharts
• Responsive design with mobile-first approach
• Form validation with Zod schemas

🔧 Robust Backend

• PHP 8.1 with modern features
• Slim Framework for API routing
• PDO database abstraction with prepared statements
• Comprehensive middleware (CORS, Rate Limiting, Security)
• OpenAPI documentation with Swagger UI
• Database migrations with Doctrine

🚀 DevOps & Deployment

• Docker containerization with multi-stage builds
• Kubernetes deployment ready
• GitHub Actions CI/CD with automated testing
• Security scanning with Trivy
• Performance monitoring with Lighthouse CI
• Health checks and monitoring

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React SPA     │    │   PHP API v2    │    │   MySQL DB      │
│   (Frontend)    │◄──►│   (Backend)     │◄──►│   (Database)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │              ┌─────────────────┐              │
         │              │   Redis Cache   │              │
         │              └─────────────────┘              │
         │                                              │
┌─────────────────┐                                    │
│   SSO Providers │                                    │
│  (SAML/OIDC)    │                                    │
└─────────────────┘                                    │
                                                       │
┌─────────────────┐    ┌─────────────────┐             │
│   Nginx Proxy   │    │   Monitoring    │             │
│   (Load Bal.)   │    │   & Logging     │             │
└─────────────────┘    └─────────────────┘             │

Technology Stack

Component	Technology	Version
Frontend	React + TypeScript	18.2.0
UI Library	Mantine	6.0.0
State Management	React Query	4.29.5
Backend	PHP + Slim	8.1+
Database	MySQL	8.0+
Cache	Redis	7.0+
Container	Docker	20.10+
CI/CD	GitHub Actions	Latest
Testing	Vitest + PHPUnit	Latest

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 18+ (for development)
• PHP 8.1+ (for development)
• MySQL 8.0+ (for development)

Using Docker (Recommended)

1. Clone the repository

   git clone https://github.com/adampaulsen/adamsdcim.git
   cd adamsdcim

2. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

3. Start the application

   docker-compose up -d

4. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8080
   • API Documentation: http://localhost:8080/api/docs
   • PHPMyAdmin: http://localhost:8081 (dev profile)

Manual Setup

1. Backend Setup

   # Install PHP dependencies
   composer install
   
   # Set up database
   php migrations/migrate.php
   
   # Start PHP server
   php -S localhost:8080 -t .

2. Frontend Setup

   cd app
   npm install
   npm run dev

🛠️ Development

Project Structure

adamsdcim/
├── app/                    # React frontend application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── contexts/       # React contexts
│   │   ├── lib/           # Utility libraries
│   │   ├── pages/         # Page components
│   │   └── types/         # TypeScript definitions
│   ├── package.json
│   └── vite.config.ts
├── api/                   # API endpoints
│   ├── v1/               # Legacy API (deprecated)
│   ├── v2/               # Modern API
│   └── docs/             # API documentation
├── classes/              # PHP classes
│   ├── Api/             # API controllers and middleware
│   ├── Database/        # Database abstraction
│   └── Security/        # Security utilities
├── tests/               # Backend tests
├── docker/              # Docker configuration
├── .github/             # CI/CD workflows
└── docs/               # Documentation

Development Commands

Backend

# Run tests
vendor/bin/phpunit

# Static analysis
vendor/bin/phpstan analyse

# Code style check
vendor/bin/php-cs-fixer fix --dry-run

# Database migrations
php migrations/migrate.php

Frontend

cd app

# Development server
npm run dev

# Run tests
npm run test

# Build for production
npm run build

# Linting
npm run lint

Environment Variables

Backend (.env)

# Database
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=adamsdcim
DB_USERNAME=adamsdcim
DB_PASSWORD=your_password

# Security
ADAMSDCIM_SECRET_KEY=your-secret-key
ADAMSDCIM_APP_URL=http://localhost:8080
ADAMSDCIM_SPA_URL=http://localhost:3000

# Development
ADAMSDCIM_DEV_INSECURE_SESSION=false
ADAMSDCIM_CSP=default-src 'self'

Frontend (.env)

VITE_API_BASE_URL=http://localhost:8080/api/v2
VITE_APP_TITLE=adamsDCIM

📚 API Documentation

API v2 Endpoints

The modern API v2 provides RESTful endpoints with JWT authentication:

Authentication

• POST /api/v2/auth/login - User login
• POST /api/v2/auth/refresh - Refresh JWT token
• POST /api/v2/auth/logout - User logout
• POST /api/v2/auth/sso/callback - SSO callback

Resources

• GET /api/v2/devices - List devices
• POST /api/v2/devices - Create device
• GET /api/v2/devices/{id} - Get device
• PUT /api/v2/devices/{id} - Update device
• DELETE /api/v2/devices/{id} - Delete device

Statistics

• GET /api/v2/stats/overview - Overview statistics
• GET /api/v2/stats/datacenters/{id} - Data center statistics

Interactive Documentation

Access the interactive API documentation at:

• Swagger UI: http://localhost:8080/api/docs
• OpenAPI Spec: http://localhost:8080/api/docs/openapi.yaml

🚀 Deployment

Docker Deployment

# Build and run with Docker Compose
docker-compose -f docker-compose.prod.yml up -d

# Or build individual images
docker build -f Dockerfile.backend -t opendcim/backend .
docker build -f app/Dockerfile -t opendcim/frontend ./app

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Check deployment status
kubectl get pods -n opendcim
kubectl get services -n opendcim

Production Checklist

• Set secure environment variables
• Configure SSL/TLS certificates
• Set up monitoring and logging
• Configure backup strategy
• Set up CI/CD pipelines
• Configure security scanning
• Set up performance monitoring

🧪 Testing

Running Tests

Backend Tests

# Run all tests
vendor/bin/phpunit

# Run specific test suite
vendor/bin/phpunit --testsuite=Unit
vendor/bin/phpunit --testsuite=Integration
vendor/bin/phpunit --testsuite=Feature

# Generate coverage report
vendor/bin/phpunit --coverage-html tests/coverage

Frontend Tests

cd app

# Run tests
npm run test

# Run tests with UI
npm run test:ui

# Run tests in watch mode
npm run test -- --watch

Test Coverage

• Backend: PHPUnit with 80%+ coverage target
• Frontend: Vitest with React Testing Library
• E2E: Playwright (planned)
• Performance: Lighthouse CI
• Security: Trivy vulnerability scanning

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes
4. Run tests

   # Backend
   vendor/bin/phpunit
   
   # Frontend
   cd app && npm run test

5. Submit a pull request

Code Standards

• PHP: PSR-12 coding standards
• JavaScript/TypeScript: ESLint configuration
• Git: Conventional commits
• Documentation: Markdown with examples

📄 License

This project is licensed under the GNU GPL v3 License - see the LICENSE file for details.

🆘 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Wiki: GitHub Wiki

🙏 Acknowledgments

• Original openDCIM contributors
• Mantine UI team for the excellent component library
• Slim Framework team for the lightweight PHP framework
• All contributors and maintainers

---

Made with ❤️ by the adamsDCIM community