# LotusCloud Microservices Architecture

## Overview

LotusCloud runs ~200 microservices organized by domain. Current repo has **55 services** implemented (api-gateway + 54 backend services on ports 8081-8134). This document maps the full target architecture.

## Service Domains

### Identity & Security (~20 services)

| Service | Status | Port | Description |
|---------|--------|------|-------------|
| auth-service | part of iam | - | Authentication, token issuance |
| iam-service | DONE | 8081 | Users, roles, RBAC, JWT |
| token-service | part of iam | - | JWT lifecycle, refresh |
| user-service | part of iam | - | User CRUD |
| group-service | planned | - | Group management |
| role-service | part of iam | - | Role definitions |
| policy-service | DONE | 8104 | Policy enforcement, compliance |
| access-key-service | part of iam | - | API key management |
| service-account-svc | part of iam | - | Workload identity |
| oidc-service | planned | - | OpenID Connect provider |
| mfa-service | planned | - | Multi-factor authentication |
| sso-service | planned | - | Single sign-on |
| secret-manager | part of keyvault | 8089 | Secret storage |
| key-management | part of keyvault | - | Encryption key management |
| certificate-manager | part of keyvault | - | TLS certificate lifecycle |
| vault-proxy | planned | - | HashiCorp Vault integration |
| audit-service | DONE | 8114 | Activity audit logging |
| security-policy-svc | part of policy | - | Security guardrails |
| access-log-service | part of monitor | - | Access logging |
| identity-provider | part of iam | - | IdP for federation |

### Compute (~20 services)

| Service | Status | Port | Description |
|---------|--------|------|-------------|
| compute-service | DONE | 8082 | VM lifecycle management |
| vm-image-service | part of compute | - | Image registry |
| vm-template-service | planned | - | VM templates |
| vm-snapshot-service | part of compute | - | VM snapshots |
| vm-migration-service | planned | - | Live migration |
| vm-console-service | planned | - | Serial/VNC console |
| vm-metadata-service | planned | - | Instance metadata (169.254.x) |
| scheduler-service | part of resource-mgr | 8092 | Placement engine |
| placement-engine | part of resource-mgr | - | Node selection |
| hypervisor-agent | planned | - | Node-level VM management |
| node-agent | planned | - | Node lifecycle |
| compute-monitor | part of monitor | - | Compute health |
| gpu-service | DONE | 8131 | GPU allocation |
| baremetal-service | planned | - | Bare metal provisioning |
| autoscaling-engine | DONE | 8105 | Auto-scaling policies |
| spot-instance-svc | planned | - | Spot/preemptible VMs |
| instance-health | part of monitor | - | Instance health checks |
| instance-recovery | planned | - | Auto-recovery |
| instance-lifecycle | part of compute | - | State machine management |
| resource-reservation | planned | - | Capacity reservation |

### Storage (~15 services)

| Service | Status | Port | Description |
|---------|--------|------|-------------|
| storage-service | DONE | 8083 | Object storage (S3-compatible) |
| block-storage-svc | part of storage | - | Block volume management |
| volume-snapshot | part of storage | - | Volume snapshots |
| volume-backup | part of backup | 8097 | Volume backup |
| object-storage-ctl | part of storage | - | S3 API controller |
| bucket-service | part of storage | - | Bucket management |
| replication-service | planned | - | Cross-region replication |
| data-integrity-svc | planned | - | Checksum verification |
| storage-metrics | planned | - | Storage monitoring |
| archive-service | planned | - | Cold storage tier |
| backup-service | DONE | 8097 | Backup/restore automation |
| backup-policy-svc | part of backup | - | Backup schedules |
| lifecycle-service | planned | - | Object lifecycle |
| filesystem-svc | planned | - | CephFS management |
| storage-repair | planned | - | Self-healing storage |

### Networking (~20 services)

| Service | Status | Port | Description |
|---------|--------|------|-------------|
| network-service | DONE | 8084 | VPC/Subnet/SG management |
| vpc-service | part of network | - | VPC lifecycle |
| subnet-service | part of network | - | Subnet management |
| route-table-service | part of network | - | Route management |
| elastic-ip-svc | planned | - | Floating IP allocation |
| ipam-service | DONE | 8119 | IP Address Management |
| nat-gateway-svc | DONE | 8117 | NAT gateway |
| internet-gateway-svc | planned | - | Internet gateway |
| loadbalancer-svc | DONE | 8087 | Load balancer control plane |
| lb-healthcheck | part of lb | - | Target health checks |
| lb-routing | part of lb | - | Traffic routing rules |
| firewall-service | DONE | 8096 | Network firewall rules |
| security-group-svc | part of network | - | Security group rules |
| vpn-service | DONE | 8095 | VPN site-to-site, P2S |
| private-link-svc | DONE | 8107 | Private networking |
| dns-service | DONE | 8088 | DNS records, zones |
| global-lb-service | DONE | 8118 | Global load balancing |
| ddos-service | DONE | 8108 | DDoS protection |
| cdn-service | DONE | 8099 | CDN control |
| waf-service | DONE | 8125 | Web Application Firewall |

### Kubernetes Platform (~15 services)

| Service | Status | Port | Description |
|---------|--------|------|-------------|
| container-service | DONE | 8090 | Container runtime |
| cluster-service | part of container | - | K8s cluster lifecycle |
| nodepool-service | planned | - | Node pool management |
| cluster-autoscaler | part of autoscale | - | Cluster auto-scaling |
| cluster-upgrade-svc | planned | - | Rolling upgrades |
| k8s-network-ctl | planned | - | K8s network policies |
| k8s-storage-ctl | planned | - | K8s storage classes |
| registry-service | DONE | 8093 | Container registry |
| image-scanner | planned | - | CVE scanning |
| helm-service | planned | - | Helm chart management |
| operator-service | planned | - | Custom operators |
| ingress-controller | planned | - | Ingress management |
| service-mesh-svc | planned | - | Istio management |
| k8s-monitor | part of monitor | - | Cluster monitoring |
| k8s-rbac-svc | part of iam | - | K8s RBAC |

### Database Platform (~15 services)

| Service | Status | Port | Description |
|---------|--------|------|-------------|
| sql-service | DONE | 8086 | Managed SQL (PG, MySQL) |
| postgres-service | DONE | 8120 | PostgreSQL management |
| mysql-service | DONE | 8121 | MySQL management |
| mongodb-service | DONE | 8116 | MongoDB DBaaS |
| redis-service | DONE | 8122 | Managed Redis |
| memcache-service | planned | - | Managed Memcached |
| replication-ctl | planned | - | DB replication management |
| db-backup-ctl | part of backup | - | DB backup automation |
| db-upgrade-svc | planned | - | DB version upgrades |
| db-monitor | part of monitor | - | DB health monitoring |
| pgbouncer-ctl | planned | - | Connection pool management |
| proxysql-ctl | planned | - | MySQL proxy management |
| db-migration-svc | DONE | 8128 | Zero-downtime migration |
| db-failover-svc | planned | - | Manual/auto failover |
| dbaas-provisioner | part of sql | - | DB instance provisioning |

### System / Platform (~20 services)

| Service | Status | Port | Description |
|---------|--------|------|-------------|
| api-gateway | DONE | 8080 | Reverse proxy, auth, rate limit |
| resource-manager | DONE | 8092 | Resource lifecycle |
| billing-service | DONE | 8085 | Usage billing |
| costmgmt-service | DONE | 8103 | Cost analysis, budgets |
| invoice-service | part of billing | - | Invoice generation |
| payment-service | planned | - | Payment processing |
| usage-metering | part of billing | - | Usage collection |
| notification-svc | DONE | 8115 | Multi-channel notifications |
| email-service | planned | - | Email delivery |
| monitor-service | DONE | 8091 | Metrics, alerts, logs |
| logging-service | DONE | 8126 | Log aggregation |
| tracing-service | part of monitor | - | Distributed tracing |
| eventgrid-service | DONE | 8102 | Event routing |
| servicebus-service | DONE | 8106 | Message queues |
| apim-service | DONE | 8101 | API management |
| appservice-service | DONE | 8094 | App hosting (PaaS) |
| serverless-service | DONE | 8098 | FaaS functions |
| config-service | planned | - | Dynamic configuration |
| feature-flag-svc | planned | - | Feature toggles |
| service-discovery | planned | - | Service registry |

## Service Communication

### Synchronous (gRPC / REST)

```
Frontend → API Gateway → Service (REST/JSON)
Service → Service (gRPC/protobuf)
```

### Asynchronous (Event Bus)

```
Service → RabbitMQ/Kafka → Subscriber Services
```

### Event Topics

```
lotuscloud.compute.vm.created
lotuscloud.compute.vm.deleted
lotuscloud.compute.vm.state_changed
lotuscloud.network.vpc.created
lotuscloud.storage.volume.attached
lotuscloud.dbaas.instance.created
lotuscloud.dbaas.backup.completed
lotuscloud.billing.usage.reported
lotuscloud.iam.user.created
lotuscloud.iam.policy.changed
lotuscloud.security.alert
lotuscloud.quota.exceeded
```

## Internal Service Authentication

```
Service A → mTLS → Service B
                    │
                    ├── Validate certificate
                    ├── Check service identity
                    └── Authorize request
```

## Service Status Summary

| Status | Count |
|--------|-------|
| DONE (in repo) | 55 |
| Planned (separate service) | ~30 |
| Part of existing service | ~120 |
| **Total modules** | **~200** |

## Additional DONE Services (ports 8112-8128)

| Service | Port | Description |
|---------|------|-------------|
| image-service | 8112 | VM image management |
| snapshot-service | 8113 | Volume/VM snapshots |
| audit-service | 8114 | Activity audit trail |
| notification-service | 8115 | Multi-channel notifications |
| mongo-service | 8116 | MongoDB DBaaS |
| nat-gateway-service | 8117 | NAT gateway management |
| global-lb-service | 8118 | Global load balancing |
| ipam-service | 8119 | IP address management |
| postgres-service | 8120 | PostgreSQL DBaaS |
| mysql-service | 8121 | MySQL DBaaS |
| redis-service | 8122 | Managed Redis |
| object-storage-service | 8123 | S3-compatible object storage |
| block-storage-service | 8124 | Block volume management |
| waf-service | 8125 | Web application firewall |
| logging-service | 8126 | Centralized log analytics |
| metrics-service | 8127 | Custom metrics & alerts |
| migration-service | 8128 | Zero-downtime DB migration |
| git-deploy-service | 8129 | Vercel-like git push to deploy |
| ai-agent-service | 8130 | AI-powered DevOps automation |
| gpu-service | 8131 | GPU instances for AI workloads |
| model-registry-service | 8132 | AI model storage & versioning |
| vector-db-service | 8133 | Vector search for RAG pipelines |
| subscription-service | 8134 | Plans, billing tiers & usage |
| workflow-engine | 8111 | Orchestration workflows |

## Next Priority Services to Build

1. cluster-upgrade-svc (K8s upgrade automation)
2. vm-migration-service (live VM migration)
3. pgbouncer-ctl (connection pool management - partially in postgres-service)
4. db-failover-svc (partially in postgres-service /failover endpoint)
5. image-scanner (CVE scanning for container images)
6. helm-service (Helm chart management)
7. service-mesh-svc (Istio management)
8. payment-service (payment processing)