# PhotonCloud

PhotonCloud is a Nix-first cloud platform workspace that assembles a small control plane, network services, VM hosting, shared storage, object storage, and gateway services into one reproducible repository.

The canonical local proof path is the six-node VM cluster under [`nix/test-cluster`](/home/centra/cloud/nix/test-cluster/README.md). It builds all guest images on the host, boots them as hardware-like QEMU nodes, and validates real multi-node behavior.

## Components

- `chainfire`: replicated coordination store
- `flaredb`: replicated KV and metadata store
- `iam`: identity, token issuance, and authorization
- `prismnet`: tenant networking control plane
- `flashdns`: authoritative DNS service
- `fiberlb`: load balancer control plane and dataplane
- `plasmavmc`: VM control plane and worker agents
- `coronafs`: shared filesystem for mutable VM volumes
- `lightningstor`: object storage and VM image backing
- `k8shost`: Kubernetes-style hosting control plane
- `apigateway`: external API and proxy surface
- `nightlight`: metrics ingestion and query service
- `creditservice`: minimal reference quota/credit service
- `deployer`: bootstrap and phone-home deployment service
- `fleet-scheduler`: non-Kubernetes service scheduler for bare-metal cluster services

## Quick Start

```bash
nix develop
nix run ./nix/test-cluster#cluster -- fresh-smoke
```

## Main Entrypoints

- workspace flake: [flake.nix](/home/centra/cloud/flake.nix)
- VM validation harness: [nix/test-cluster/README.md](/home/centra/cloud/nix/test-cluster/README.md)
- shared volume notes: [coronafs/README.md](/home/centra/cloud/coronafs/README.md)
- minimal quota-service rationale: [creditservice/README.md](/home/centra/cloud/creditservice/README.md)
- archived manual VM launch scripts: [baremetal/vm-cluster/README.md](/home/centra/cloud/baremetal/vm-cluster/README.md)

## Repository Guide

- [docs/README.md](/home/centra/cloud/docs/README.md): documentation entrypoint
- [docs/testing.md](/home/centra/cloud/docs/testing.md): validation path summary
- [docs/component-matrix.md](/home/centra/cloud/docs/component-matrix.md): supported multi-component compositions
- [docs/storage-benchmarks.md](/home/centra/cloud/docs/storage-benchmarks.md): latest CoronaFS and LightningStor lab numbers
- `plans/`: design notes and exploration documents

## Scope

PhotonCloud is centered on reproducible infrastructure behavior rather than polished end-user product surfaces. Some services, such as `creditservice`, are intentionally minimal reference implementations that prove integration points rather than full products.

Host-level NixOS rollout validation is also expected to stay reproducible: the `deployer-vm-smoke` VM test now proves that `nix-agent` can activate a prebuilt target system closure directly, without recompiling the stack inside the guest.