AI-Driven Microservices Platform

Overview

This repository contains the AI-Driven Microservices Platform for pickleball facility management. The platform is designed to enable domain-driven development with a focus on three complete environments:

1. Local Dapr-only Development Environment
2. Local Kubernetes (Kind) Development Environment
3. GCP Development Environment with GKE cluster

The platform is currently in Phase 0: Foundation Setup, which establishes the core infrastructure and development environments.

Platform Architecture

The platform is built on a microservices architecture using Dapr (Distributed Application Runtime) as the primary runtime for building distributed applications. This approach provides several benefits:

• Language Agnostic: Services can be written in any language
• Building Blocks: Dapr provides ready-to-use building blocks for common distributed application capabilities
• Portability: Applications run consistently across all environments
• Scalability: Services can be scaled independently
• Resilience: Failures are isolated to individual services

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│                      Client Applications                        │
│                                                                 │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│                         API Gateway                             │
│                                                                 │
└───────────┬─────────────────────┬────────────────┬──────────────┘
            │                     │                │
            ▼                     ▼                ▼
┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
│                   │  │                   │  │                   │
│  Microservice A   │  │  Microservice B   │  │  Microservice C   │
│                   │  │                   │  │                   │
└─────────┬─────────┘  └─────────┬─────────┘  └─────────┬─────────┘
          │                      │                      │
          ▼                      ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│                       Dapr Building Blocks                      │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────┐│
│  │ Service     │  │ State       │  │ Pub/Sub     │  │ Bindings ││
│  │ Invocation  │  │ Management  │  │ Messaging   │  │          ││
│  └─────────────┘  └─────────────┘  └─────────────┘  └──────────┘│
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Environments

Local Dapr-only Development Environment

The Local Dapr-only Development Environment uses Docker Compose with Dapr sidecars for fast development.

Purpose: Provides the fastest development experience with minimal resource requirements.

Benefits:

• Quick iteration cycles
• Simple setup and configuration
• No Kubernetes knowledge required
• Minimal resource usage on development machines
• Direct access to logs and debugging

Local Kubernetes (Kind) Development Environment

The Local Kubernetes (Kind) Development Environment uses Kind (Kubernetes in Docker) with Dapr for testing in a Kubernetes environment.

Purpose: Allows testing Kubernetes-specific features without cloud costs.

Benefits:

• Kubernetes experience without cloud costs
• Closer to production environment
• Tests Kubernetes-specific features
• Validates Kubernetes manifests
• Simulates multi-node deployments

GCP Development Environment

The GCP Development Environment uses Google Kubernetes Engine (GKE) for a production-like deployment.

Purpose: Provides a production-like deployment for thorough testing.

Benefits:

• Access to cloud services
• Realistic performance testing
• Scalability testing
• Integration with GCP services
• Validates cloud-specific configurations

Prerequisites

Common Requirements

• Docker (≥ 24.0)
• Dapr CLI (≥ 1.11)
• Node.js (≥ 20.x LTS)
• curl (for verification tests)
• jq (for verification tests)

Environment-Specific Requirements

Local Dapr-only Environment

• Docker Compose

Local Kubernetes (Kind) Environment

• Kind (≥ 0.20)
• kubectl (≥ 1.28)

GCP Environment

• Google Cloud SDK
• Terraform (≥ 1.6.0)
• kubectl (≥ 1.28)
• GCP account with appropriate permissions

Quick Start

Local Dapr-only Environment

1. Navigate to the local-dapr environment directory:

   cd environments/local-dapr

2. Run the setup script:

   ./scripts/setup.sh

3. Verify the environment:

   ./tests/verify.sh

4. When done, tear down the environment:

   ./scripts/teardown.sh

Local Kubernetes (Kind) Environment

1. Navigate to the local-kind environment directory:

   cd environments/local-kind

2. Run the setup script:

   ./scripts/setup.sh

3. Verify the environment:

   ./tests/verify.sh

4. When done, tear down the environment:

   ./scripts/teardown.sh

GCP Environment

1. Navigate to the GCP environment directory:

   cd environments/gcp

2. Run the setup script:

   ./scripts/setup.sh

3. Verify the environment:

   ./tests/verify.sh

4. When done, tear down the environment:

   ./scripts/teardown.sh

Hello World Service

The platform includes a sample Hello World service that validates all three environments. This service demonstrates:

• State management using Dapr state store
• Publishing events using Dapr pub/sub
• Service invocation using Dapr

To test the Hello World service:

1. Deploy the service to your chosen environment (it's included in the setup scripts)
2. Run the Hello World verification script:

   ./tests/verify-hello-world.sh

Port Management Strategy

The platform implements a standardized port management strategy to ensure consistency across all environments and prevent port conflicts. Key features include:

• Standardized port ranges for different service types:

  • Application Ports: 3001-3999
  • Dapr HTTP Ports: 3500-3599
  • Dapr gRPC Ports: 50001-50100
  • Monitoring Ports: 6000-6999
  • Testing/Debug Ports: 7000-7999
  • Reserved (External): 8000-8999
  • Future Expansion: 9000-9999
  • Fallback Ranges: 10000-12999

• Port validation and conflict detection tools

• Automated port migration scripts

• Dapr-specific port coordination

For more details, see the port management documentation:

• Port Management Strategy
• Port Registry
• Port Validation Guide
• Port Migration Plan

Documentation

For more detailed information, please refer to the following documentation:

• Detailed Documentation Guide
• Verification Process Documentation
• Development Guide

License

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