🌍 Cloudvelous Showcase System

Master Documentation Hub for the Cloudvelous multi-repo microservices architecture

🎯 Purpose

The Cloudvelous Showcase System demonstrates a complete cloud-native microservices architecture built with modern technologies across multiple programming languages. This system showcases:

• Event-driven architecture with SQS message queues
• Multi-language microservices (PHP, C#, Python, React)
• AWS-native infrastructure with CDK
• AI-powered analytics and sentiment analysis
• Real-time dashboard with comprehensive monitoring
• End-to-end testing and CI/CD pipelines

🗺️ System Map

graph TB
    subgraph "Frontend Layer"
        RD[React Dashboard]
    end
    
    subgraph "API Gateway Layer"
        PCG[PHP CRM Gateway]
        CAA[C# Analytics API]
    end
    
    subgraph "Processing Layer"
        CLP[C# Lead Processor]
        PAI[Python AI Agent]
        PMS[PHP Marketing Service]
        CLG[C# Log Processor]
    end
    
    subgraph "Infrastructure Layer"
        SQS[AWS SQS]
        RDS[AWS RDS]
        OS[AWS OpenSearch]
        SEC[AWS Secrets Manager]
    end
    
    subgraph "Shared Components"
        SDK[Cloudvelous AWS SDK]
        SC[Shared Contracts]
    end
    
    PCG --> SQS
    SQS --> CLP
    CLP --> RDS
    CAA --> RDS
    CAA --> OS
    PAI --> OS
    PMS --> RDS
    CLG --> OS
    RD --> CAA
    RD --> PAI
    
    CLP -.-> SDK
    CAA -.-> SDK
    CLG -.-> SDK
    PCG -.-> SC
    CLP -.-> SC

Loading

📋 Repository Dependency Order

Order	Repository	Language	Purpose	Dependencies
0️⃣	cloudvelous-showcase	Markdown	🧭 Master documentation hub	None
1️⃣	php-crm-gateway	PHP (Laravel)	REST API sending leads to SQS	shared-contracts
2️⃣	cloudvelous-aws-sdk	C# (.NET 8)	Modular AWS SDK for all C# services	None
3️⃣	aws-cdk-infra	Python (CDK)	Infrastructure: VPC, SQS, RDS, OpenSearch	None
4️⃣	csharp-lead-processor	C# (.NET 8 Lambda)	Consumes SQS → RDS	cloudvelous-aws-sdk, shared-contracts
5️⃣	csharp-analytics-api	C# (.NET 8 Web API)	Exposes analytics data	cloudvelous-aws-sdk, shared-contracts
6️⃣	python-ai-agent	Python (FastAPI + Haystack)	Sentiment / AI Classification	shared-contracts
7️⃣	react-dashboard	React (Vite + TS)	Displays analytics and AI results	csharp-analytics-api, python-ai-agent
8️⃣	shared-contracts	JSON Schema	Defines common data contracts	None
9️⃣	php-marketing-service	PHP (Symfony)	Generates marketing summaries	shared-contracts
🔟	local-dev-stack	Docker	Local environment setup	All services
1️⃣1️⃣	integration-tests	C# / Python	End-to-end testing	All services
1️⃣2️⃣	example-data-seeder	Python / PHP	Seed fake CRM data	php-crm-gateway

🚀 Quick Start

Prerequisites

• Docker & Docker Compose (for local development)
• AWS CLI configured with appropriate permissions
• Node.js 18+ (for React dashboard)
• PHP 8.2+ (for PHP services)
• .NET 8 SDK (for C# services)
• Python 3.11+ (for Python services)

1. Clone All Repositories

# Clone the master documentation hub
git clone https://github.com/sl-cloud/cloudvelous-showcase.git
cd cloudvelous-showcase

# Run the setup script to clone all repositories
./scripts/setup-repos.sh

2. Infrastructure Setup

# Deploy AWS infrastructure
cd aws-cdk-infra
npm install
cdk bootstrap
cdk deploy --all

3. Local Development

# Start all services locally
cd local-dev-stack
docker-compose up -d

# Verify all services are running
./scripts/health-check.sh

4. Access the System

• React Dashboard: http://localhost:3000
• PHP CRM Gateway: http://localhost:8000
• C# Analytics API: http://localhost:5000
• Python AI Agent: http://localhost:8001

📊 Repository Status

Repository	Build Status	Coverage	Last Updated
php-crm-gateway
cloudvelous-aws-sdk
aws-cdk-infra
csharp-lead-processor
csharp-analytics-api
python-ai-agent
react-dashboard
shared-contracts
php-marketing-service
csharp-log-processor
local-dev-stack
integration-tests
example-data-seeder

📚 Documentation

• Architecture Overview - System design, data flow, and technical decisions
• Runbook - Local development and AWS deployment procedures
• Troubleshooting - Common issues and solutions
• API Documentation - Service endpoints and contracts
• Contributing Guide - Development standards and conventions

🔧 Development Workflow

1. Start with Infrastructure: Deploy AWS resources using CDK
2. Setup Shared Components: Build and publish shared contracts and SDK
3. Develop Services: Build services in dependency order
4. Integration Testing: Run end-to-end tests
5. Frontend Development: Connect React dashboard to APIs
6. Deployment: Deploy to AWS using CI/CD pipelines

🏗️ Architecture Principles

• Event-Driven: Asynchronous communication via SQS
• Microservices: Independent, deployable services
• Cloud-Native: AWS-managed services and serverless functions
• API-First: RESTful APIs with OpenAPI specifications
• Observability: Comprehensive logging and monitoring
• Security: IAM roles, secrets management, and input validation

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

• Code style conventions
• Testing requirements
• Pull request process
• Issue reporting guidelines

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Check the docs directory
• Issues: Report bugs via GitHub Issues
• Discussions: Join our GitHub Discussions for questions
• Security: Report security issues privately via email

---

Built with ❤️ by the Cloudvelous Team

Last updated: $(date)