MIZOKI Microservices Architecture

This directory contains the implementation for deploying MIZOKI as a microservices architecture on Google Cloud Run, where each of the 25 cells runs as an independent service.

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────┐
│                   API Gateway                        │
│              (Routes requests to cells)              │
└──────────────────────┬──────────────────────────────┘
                       │
        ┌──────────────┴──────────────┐
        │                             │
┌───────▼────────┐          ┌────────▼────────┐
│    Cell 1      │          │     Cell 2      │
│  (Bootstrap)   │◄─────────►  (Extractor)    │
└────────────────┘   A2A    └─────────────────┘
        │                             │
        │         ┌──────────┐        │
        └────────►│ Service  │◄───────┘
                  │Discovery │
                  └──────────┘
                       ...
                  (Cells 3-25)

📁 Directory Structure

microservices/
├── README.md                     # This file
├── configs/
│   └── api-gateway-config.yaml   # API Gateway routing configuration
├── dockerfiles/
│   └── Dockerfile.cell*          # Generated Dockerfiles for each cell
├── scripts/
│   ├── deploy-cell.sh           # Deploy individual cell
│   ├── deploy-all-cells.sh      # Orchestrate deployment of all cells
│   ├── verify-health.sh         # Health check verification
│   ├── service-discovery.py     # Service registry and discovery
│   └── a2a-communication.py     # Inter-service communication library
└── logs/                        # Deployment and health check logs

🚀 Quick Start

Prerequisites

  1. Google Cloud SDK installed and configured
  2. Docker installed and running
  3. Appropriate GCP permissions for Cloud Run, Pub/Sub, and API Gateway
  4. Environment variables set: bash export GOOGLE_CLOUD_PROJECT="your-project-id" export GOOGLE_CLOUD_REGION="us-central1"

Deploy All Services

# Deploy all 25 cells to staging environment
cd microservices/scripts
./deploy-all-cells.sh staging

# Deploy with parallel execution (faster)
./deploy-all-cells.sh staging true

# Deploy to production
./deploy-all-cells.sh production

Deploy Individual Cell

# Deploy a specific cell
./deploy-cell.sh <cell_number> [environment]

# Example: Deploy Cell 5 to production
./deploy-cell.sh 5 production

Verify Deployment

# Check health status of all deployed services
./verify-health.sh staging

# View deployment logs
ls logs/

🔧 Configuration

Environment Variables

Each cell service receives these environment variables:

Service Accounts

Each cell runs with its own service account with minimal required permissions:

Resource Allocation

Staging: - CPU: 1 - Memory: 2Gi - Min Instances: 0 - Max Instances: 10

Production: - CPU: 2 - Memory: 4Gi - Min Instances: 1 - Max Instances: 100

🔄 Inter-Service Communication (A2A)

Services communicate using the A2A (Agent-to-Agent) protocol:

HTTP Communication

from a2a_communication import create_a2a_communicator

# Initialize communicator
comm = await create_a2a_communicator("my-service", cell_number=1)

# Send message to another cell
response = await comm.send_message(
    target_cell="cell2",
    message_type="data_request",
    payload={"query": "SELECT * FROM events"}
)

Pub/Sub Communication (Async)

# Send async message via Pub/Sub
await comm.send_message(
    target_cell="cell3",
    message_type="process_data",
    payload={"data": processed_data},
    use_pubsub=True
)

🏥 Health Monitoring

Service Discovery

The service discovery component automatically: - Discovers all deployed MIZOKI services - Monitors health status - Provides service registry API

Access service discovery:

# Get all services
curl https://[DISCOVERY_URL]/services

# Get specific cell info
curl https://[DISCOVERY_URL]/services/5

# Get only healthy services
curl https://[DISCOVERY_URL]/services/healthy

Health Checks

All services expose a /health endpoint that returns:

{
  "status": "healthy",
  "service": "cell-1-bootstrap",
  "version": "1.0.0",
  "dependencies": {
    "database": "connected",
    "pubsub": "connected"
  }
}

🌐 API Gateway

The API Gateway provides a unified entry point:

https://[GATEWAY_URL]/api/v1/cell1/[endpoint]
https://[GATEWAY_URL]/api/v1/cell2/[endpoint]
...
https://[GATEWAY_URL]/api/v1/cell25/[endpoint]

📊 Monitoring and Logs

View Logs

# View logs for a specific cell
gcloud run services logs read mizoki-cell1-staging --region=us-central1

# Stream logs
gcloud run services logs tail mizoki-cell1-staging --region=us-central1

Metrics

Access metrics in Cloud Console: - Request count - Latency - Error rate - CPU/Memory usage

🔄 Rollback

To rollback a cell to a previous version:

# List revisions
gcloud run revisions list --service=mizoki-cell1-staging --region=us-central1

# Rollback to specific revision
gcloud run services update-traffic mizoki-cell1-staging \
  --to-revisions=mizoki-cell1-staging-00002-abc=100 \
  --region=us-central1

🐛 Troubleshooting

Common Issues

  1. Cell fails to deploy - Check logs: cat logs/cell<number>_<timestamp>.log - Verify Docker build: Check if Cell file exists - Check permissions: Ensure service account has required roles

  2. Health check failing - Check service logs for errors - Verify the /health endpoint is implemented - Check if dependencies (DB, APIs) are accessible

  3. Inter-service communication fails - Verify service discovery is running - Check if target service is healthy - Review circuit breaker status in logs

Debug Commands

# Get service details
gcloud run services describe mizoki-cell1-staging --region=us-central1

# Check service account permissions
gcloud iam service-accounts get-iam-policy mizoki-cell1-sa@PROJECT_ID.iam.gserviceaccount.com

# Test service directly
curl https://[SERVICE_URL]/health

📚 Additional Resources

🤝 Contributing

When adding new cells or modifying the architecture:

  1. Update the deployment scripts if new permissions are needed
  2. Ensure the cell implements the standard health check endpoint
  3. Register new message types in the A2A communication library
  4. Update the API Gateway configuration for new endpoints
  5. Document any new environment variables or configuration

For questions or issues, please refer to the main project documentation or contact the DevOps team.

← All docsView source on GitHub →