photoncloud-monorepo/README.md

# PlasmaCloud

**A modern, multi-tenant cloud infrastructure platform built in Rust**

PlasmaCloud provides a complete cloud computing stack with strong tenant isolation, role-based access control (RBAC), and seamless integration between compute, networking, and storage services.

## MVP-Beta Status: COMPLETE ✅

The MVP-Beta milestone validates end-to-end tenant isolation and core infrastructure provisioning:

- ✅ **IAM**: User authentication, RBAC, multi-tenant isolation
- ✅ **NovaNET**: VPC overlay networking with tenant boundaries
- ✅ **PlasmaVMC**: VM provisioning with network attachment
- ✅ **Integration**: E2E tests validate complete tenant path

**Test Results**: 8/8 integration tests passing
- IAM: 6/6 tenant path tests
- Network+VM: 2/2 integration tests

## Quick Start

### Get Started in 3 Steps

1. **Deploy the Platform**
   ```bash
   # Start IAM service
   cd iam && cargo run --bin iam-server -- --port 50080

   # Start NovaNET service
   cd novanet && cargo run --bin novanet-server -- --port 50081

   # Start PlasmaVMC service
   cd plasmavmc && cargo run --bin plasmavmc-server -- --port 50082
   ```

2. **Onboard Your First Tenant**
   ```bash
   # Create user, provision network, deploy VM
   # See detailed guide below
   ```

3. **Verify End-to-End**
   ```bash
   # Run integration tests
   cd iam && cargo test --test tenant_path_integration
   cd plasmavmc && cargo test --test novanet_integration -- --ignored
   ```

**For detailed instructions**: [Tenant Onboarding Guide](docs/getting-started/tenant-onboarding.md)

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                     User / API Client                        │
└─────────────────────────────────────────────────────────────┘
                            │
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  IAM (Identity & Access Management)                         │
│  • User authentication & JWT tokens                         │
│  • RBAC with hierarchical scopes (Org → Project)            │
│  • Cross-tenant access denial                               │
└─────────────────────────────────────────────────────────────┘
                            │
              ┌─────────────┴─────────────┐
              ↓                           ↓
┌──────────────────────┐     ┌──────────────────────┐
│      NovaNET         │     │      PlasmaVMC       │
│  • VPC overlay       │────▶│  • VM provisioning   │
│  • Subnets + DHCP    │     │  • Hypervisor mgmt   │
│  • Ports (IP/MAC)    │     │  • Network attach    │
│  • Security Groups   │     │  • KVM, Firecracker  │
└──────────────────────┘     └──────────────────────┘
```

**Full Architecture**: [MVP-Beta Tenant Path Architecture](docs/architecture/mvp-beta-tenant-path.md)

## Core Components

### IAM (Identity & Access Management)

**Location**: `/iam`

Multi-tenant identity and access management with comprehensive RBAC.

**Features**:
- User and service account management
- Hierarchical scopes: System → Organization → Project
- Custom role creation with fine-grained permissions
- Policy evaluation with conditional logic
- JWT token issuance with tenant claims

**Services**:
- `IamAdminService`: User, role, and policy management
- `IamAuthzService`: Authorization and permission checks
- `IamTokenService`: Token issuance and validation

**Quick Start**:
```bash
cd iam
cargo build --release
cargo run --bin iam-server -- --port 50080
```

### NovaNET (Network Virtualization)

**Location**: `/novanet`

VPC-based overlay networking with tenant isolation.

**Features**:
- Virtual Private Cloud (VPC) provisioning
- Subnet management with CIDR allocation
- Port allocation with IP/MAC assignment
- DHCP server integration
- Security group enforcement
- OVN integration for production networking

**Services**:
- `VpcService`: VPC lifecycle management
- `SubnetService`: Subnet CRUD operations
- `PortService`: Port allocation and attachment
- `SecurityGroupService`: Firewall rule management

**Quick Start**:
```bash
cd novanet
export IAM_ENDPOINT=http://localhost:50080
cargo build --release
cargo run --bin novanet-server -- --port 50081
```

### PlasmaVMC (VM Provisioning & Management)

**Location**: `/plasmavmc`

Virtual machine lifecycle management with hypervisor abstraction.

**Features**:
- VM provisioning with tenant scoping
- Hypervisor abstraction (KVM, Firecracker)
- Network attachment via NovaNET ports
- CPU, memory, and disk configuration
- VM metadata persistence (ChainFire)
- Live migration support (planned)

**Services**:
- `VmService`: VM lifecycle (create, start, stop, delete)

**Quick Start**:
```bash
cd plasmavmc
export NOVANET_ENDPOINT=http://localhost:50081
export IAM_ENDPOINT=http://localhost:50080
cargo build --release
cargo run --bin plasmavmc-server -- --port 50082
```

## Future Components (Roadmap)

### FlashDNS (DNS Service)

**Status**: Planned for next milestone

DNS resolution within tenant VPCs with automatic record creation.

**Features** (Planned):
- Tenant-scoped DNS zones
- Automatic hostname assignment for VMs
- DNS record lifecycle tied to resources
- Integration with NovaNET for VPC resolution

### FiberLB (Load Balancing)

**Status**: Planned for next milestone

Layer 4/7 load balancing with tenant isolation.

**Features** (Planned):
- Load balancer provisioning within VPCs
- Backend pool management (VM targets)
- VIP allocation from tenant subnets
- Health checks and failover

### LightningStor (Block Storage)

**Status**: Planned for next milestone

Distributed block storage with snapshot support.

**Features** (Planned):
- Volume creation and attachment to VMs
- Snapshot lifecycle management
- Replication and high availability
- Integration with ChainFire for immutable logs

## Testing

### Integration Test Suite

PlasmaCloud includes comprehensive integration tests validating the complete E2E tenant path.

**IAM Tests** (6 tests, 778 LOC):
```bash
cd iam
cargo test --test tenant_path_integration

# Tests:
# ✅ test_tenant_setup_flow
# ✅ test_cross_tenant_denial
# ✅ test_rbac_project_scope
# ✅ test_hierarchical_scope_inheritance
# ✅ test_custom_role_fine_grained_permissions
# ✅ test_multiple_role_bindings
```

**Network + VM Tests** (2 tests, 570 LOC):
```bash
cd plasmavmc
cargo test --test novanet_integration -- --ignored

# Tests:
# ✅ novanet_port_attachment_lifecycle
# ✅ test_network_tenant_isolation
```

**Coverage**: 8/8 tests passing (100% success rate)

See [E2E Test Documentation](docs/por/T023-e2e-tenant-path/e2e_test.md) for detailed test descriptions.

## Documentation

### Getting Started

- **[Tenant Onboarding Guide](docs/getting-started/tenant-onboarding.md)**: Complete walkthrough of deploying your first tenant

### Architecture

- **[MVP-Beta Tenant Path](docs/architecture/mvp-beta-tenant-path.md)**: Complete system architecture with diagrams
- **[Component Integration](docs/architecture/mvp-beta-tenant-path.md#component-boundaries)**: How services communicate

### Testing & Validation

- **[E2E Test Documentation](docs/por/T023-e2e-tenant-path/e2e_test.md)**: Comprehensive test suite description
- **[T023 Summary](docs/por/T023-e2e-tenant-path/SUMMARY.md)**: MVP-Beta deliverables and test results

### Component Specifications

- [IAM Specification](specifications/iam.md)
- [NovaNET Specification](specifications/novanet.md)
- [PlasmaVMC Specification](specifications/plasmavmc.md)

## Tenant Isolation Model

PlasmaCloud enforces tenant isolation at three layers:

### Layer 1: IAM Policy Enforcement

Every API call is validated against the user's JWT token:
- Token includes `org_id` and `project_id` claims
- Resources are scoped as: `org/{org_id}/project/{project_id}/{resource_type}/{id}`
- RBAC policies enforce: `resource.org_id == token.org_id`
- Cross-tenant access results in 403 Forbidden

### Layer 2: Network VPC Isolation

Each VPC provides a logical network boundary:
- VPC scoped to an `org_id`
- OVN overlay ensures traffic isolation between VPCs
- Different tenants can use the same CIDR without collision
- Security groups provide intra-VPC firewall rules

### Layer 3: VM Scoping

Virtual machines are scoped to tenant organizations:
- VM metadata includes `org_id` and `project_id`
- VMs can only attach to ports in their tenant's VPC
- VM operations filter by token scope
- Hypervisor isolation ensures compute boundary

**Validation**: All three layers tested in [cross-tenant denial tests](docs/por/T023-e2e-tenant-path/e2e_test.md#test-scenario-2-cross-tenant-denial).

## Example Workflow

### Create a Tenant with Network and VM

```bash
# 1. Authenticate and get token
grpcurl -plaintext -d '{
  "principal_id": "alice",
  "org_id": "acme-corp",
  "project_id": "project-alpha"
}' localhost:50080 iam.v1.IamTokenService/IssueToken

export TOKEN="<your-token>"

# 2. Create VPC
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" -d '{
  "org_id": "acme-corp",
  "project_id": "project-alpha",
  "name": "main-vpc",
  "cidr": "10.0.0.0/16"
}' localhost:50081 novanet.v1.VpcService/CreateVpc

export VPC_ID="<vpc-id>"

# 3. Create Subnet
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" -d '{
  "org_id": "acme-corp",
  "project_id": "project-alpha",
  "vpc_id": "'$VPC_ID'",
  "name": "web-subnet",
  "cidr": "10.0.1.0/24",
  "gateway": "10.0.1.1",
  "dhcp_enabled": true
}' localhost:50081 novanet.v1.SubnetService/CreateSubnet

export SUBNET_ID="<subnet-id>"

# 4. Create Port
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" -d '{
  "org_id": "acme-corp",
  "project_id": "project-alpha",
  "subnet_id": "'$SUBNET_ID'",
  "name": "vm-port",
  "ip_address": "10.0.1.10"
}' localhost:50081 novanet.v1.PortService/CreatePort

export PORT_ID="<port-id>"

# 5. Create VM with Network
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" -d '{
  "name": "web-server-1",
  "org_id": "acme-corp",
  "project_id": "project-alpha",
  "spec": {
    "network": [{
      "id": "eth0",
      "port_id": "'$PORT_ID'"
    }]
  }
}' localhost:50082 plasmavmc.v1.VmService/CreateVm
```

**Full walkthrough**: See [Tenant Onboarding Guide](docs/getting-started/tenant-onboarding.md)

## Development

### Prerequisites

- Rust 1.70+ with Cargo
- Protocol Buffers compiler (protoc)
- Optional: KVM for real VM execution
- Optional: OVN for production networking

### Build from Source

```bash
# Clone repository
git clone https://github.com/your-org/plasmacloud.git
cd cloud

# Initialize submodules
git submodule update --init --recursive

# Build all components
cd iam && cargo build --release
cd ../novanet && cargo build --release
cd ../plasmavmc && cargo build --release
```

### Run Tests

```bash
# IAM tests
cd iam && cargo test --test tenant_path_integration

# Network + VM tests
cd plasmavmc && cargo test --test novanet_integration -- --ignored

# Unit tests (all components)
cargo test
```

### Project Structure

```
cloud/
├── iam/                    # Identity & Access Management
│   ├── crates/
│   │   ├── iam-api/       # gRPC services
│   │   ├── iam-authz/     # Authorization engine
│   │   ├── iam-store/     # Data persistence
│   │   └── iam-types/     # Core types
│   └── tests/
│       └── tenant_path_integration.rs  # E2E tests
│
├── novanet/               # Network Virtualization
│   ├── crates/
│   │   ├── novanet-server/    # gRPC services
│   │   ├── novanet-api/       # Protocol buffers
│   │   ├── novanet-metadata/  # Metadata store
│   │   └── novanet-ovn/       # OVN integration
│   └── proto/
│
├── plasmavmc/             # VM Provisioning
│   ├── crates/
│   │   ├── plasmavmc-server/      # VM service
│   │   ├── plasmavmc-api/         # Protocol buffers
│   │   ├── plasmavmc-hypervisor/  # Hypervisor abstraction
│   │   ├── plasmavmc-kvm/         # KVM backend
│   │   └── plasmavmc-firecracker/ # Firecracker backend
│   └── tests/
│       └── novanet_integration.rs  # E2E tests
│
├── flashdns/              # DNS Service (planned)
├── fiberlb/               # Load Balancing (planned)
├── lightningstor/         # Block Storage (planned)
│
├── chainfire/             # Immutable event log (submodule)
├── flaredb/               # Distributed metadata store (submodule)
│
├── docs/
│   ├── architecture/      # Architecture docs
│   ├── getting-started/   # Onboarding guides
│   └── por/               # Plan of Record (POR) docs
│       └── T023-e2e-tenant-path/  # MVP-Beta deliverables
│
├── specifications/        # Component specifications
└── README.md             # This file
```

## Contributing

We welcome contributions! Please follow these guidelines:

1. **Fork the repository** and create a feature branch
2. **Write tests** for new functionality
3. **Update documentation** as needed
4. **Run tests** before submitting PR: `cargo test`
5. **Follow Rust style**: Use `cargo fmt` and `cargo clippy`

### Code Review Process

1. All PRs require at least one approval
2. CI must pass (tests, formatting, lints)
3. Documentation must be updated for user-facing changes
4. Integration tests required for new features

## License

PlasmaCloud is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.

## Support & Community

- **GitHub Issues**: Report bugs or request features
- **Documentation**: See [docs/](docs/) for detailed guides
- **Architecture**: Review [architecture docs](docs/architecture/mvp-beta-tenant-path.md) for design decisions

## Roadmap

### Completed (MVP-Beta) ✅

- [x] IAM with RBAC and tenant scoping
- [x] NovaNET VPC overlay networking
- [x] PlasmaVMC VM provisioning
- [x] End-to-end integration tests
- [x] Comprehensive documentation

### In Progress

- [ ] FlashDNS integration (S3)
- [ ] FiberLB integration (S4)
- [ ] LightningStor integration (S5)

### Planned

- [ ] FlareDB persistence for production
- [ ] ChainFire integration for VM metadata
- [ ] OVN production deployment
- [ ] Kubernetes integration
- [ ] Terraform provider
- [ ] Web UI / Dashboard

## Acknowledgments

PlasmaCloud builds upon:
- **ChainFire**: Immutable event log for audit trails
- **FlareDB**: Distributed metadata store
- **OVN (Open Virtual Network)**: Production-grade overlay networking
- **gRPC**: High-performance RPC framework
- **Rust**: Safe, concurrent systems programming

---

**Status**: MVP-Beta Complete ✅
**Last Updated**: 2025-12-09
**Next Milestone**: FlashDNS, FiberLB, LightningStor integration

For detailed information, see:
- [Tenant Onboarding Guide](docs/getting-started/tenant-onboarding.md)
- [Architecture Documentation](docs/architecture/mvp-beta-tenant-path.md)
- [Test Documentation](docs/por/T023-e2e-tenant-path/e2e_test.md)