[docs]: Restructure project README

README.md

@@ -1,4 +1,12 @@
-# Open Cloud Datacenter (OCD)
+<p align="center">
+  <img src="docs/media/RepoBanner.png" alt="Open Cloud Datacenter" width="100%">
+</p>
+
+# Open Cloud Data Center (OCD)
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Issues](https://img.shields.io/github/issues/wso2/open-cloud-datacenter)](https://github.com/wso2/open-cloud-datacenter/issues)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](docs/CONTRIBUTING.md)
 
 Turn an on-prem datacenter into a self-service cloud. OCD is an open, modular control plane and module set for running compute, Kubernetes clusters, and networking on your own hardware — without public-cloud lock-in.
 
@@ -7,11 +15,49 @@ Turn an on-prem datacenter into a self-service cloud. OCD is an open, modular co
 - **Cost-efficiency** — optimize resource usage and avoid vendor lock-in.
 - **Community-driven** — built on open standards and collaborative development.
 
-> ℹ️ **This `main` branch is the index — it carries no code.** The work lives on three branches, mapped below. `main` is intentionally kept as the front door + roadmap.
+> ℹ️ **This `main` branch is the index — it carries no code.** Each layer of the
+> stack lives on its own branch, mapped below; `main` is intentionally kept as
+> the front door + roadmap, not a place to build from.
+
+## Architecture
+
+Two paths to provision a resource, one platform underneath:
+
+```mermaid
+flowchart TD
+    U["you"] --> A["dcctl / cloud-ui"]
+    A --> B["controlplane<br/>(dispatches custom resources)"]
+    B --> C["operators<br/>(DBaaS · Key Vault)"]
+    C --> H
+
+    P["platform admin"] --> T["terraform<br/>(IaC modules)"]
+    T --> H
+
+    H["Harvester + Rancher<br/>VMs · Kubernetes clusters · storage"]
+
+    style H fill:#2d5,stroke:#163,color:#000
+```
+
+- **Self-service path** — `dcctl` (CLI) or `cloud-ui` (web) talk to `controlplane`'s DC-API, which dispatches custom resources that the `operators` reconcile into real VMs on Harvester.
+- **Infrastructure path** — a platform admin applies `terraform` modules directly against Harvester + Rancher to stand up or operate the platform itself — including deploying the operators and the control plane's own hosting cluster.
+
+## `terraform` — infrastructure as code
 
-## See it in action
+The foundation everything else builds on: modules that wrap the Harvester + Rancher providers to stand up the platform (Rancher, networking, storage, identity, monitoring), onboard tenants (projects, quotas, VMs, clusters), and optionally deploy the operators and the control-plane's hosting infrastructure.
 
-The same control plane, two ways — provision a virtual network from the **CLI** or the **web console**:
+→ [`github.com/wso2/open-cloud-datacenter/tree/terraform`](https://github.com/wso2/open-cloud-datacenter/tree/terraform)
+
+## `operators` — platform services
+
+Kubernetes operators that turn Harvester capacity into managed, as-a-service resources — **Database** (PostgreSQL) and **Key Vault** today, more landing alongside. Each is a self-contained kubebuilder project that reconciles custom resources dispatched by the control plane into real VMs on Harvester.
+
+→ [`github.com/wso2/open-cloud-datacenter/tree/operators`](https://github.com/wso2/open-cloud-datacenter/tree/operators)
+
+## `controlplane` — the self-service cloud experience
+
+A REST API (**DC-API**), a CLI (**dcctl**), and a web console (**cloud-ui**) that turn the raw platform into a cloud-like experience — provision VMs and Kubernetes clusters with a single command, no Terraform knowledge required.
+
+The same control plane, two ways — provisioning a virtual network from the **CLI** or the **web console**:
 
 <table>
 <tr>
@@ -20,59 +66,23 @@ The same control plane, two ways — provision a virtual network from the **CLI*
 </tr>
 </table>
 
-## How this repo is organized
-
-```text
-              ┌─────────────────────────────────────────────┐
-              │          Open Cloud Datacenter (OCD)         │
-              │   turn an on-prem datacenter into a cloud    │
-              └───────────────────────┬─────────────────────┘
-                          branch = layer of the stack
-      ┌───────────────────────────────┼───────────────────────────────┐
-      ▼                               ▼                               ▼
-┌──────────────┐              ┌──────────────────┐            ┌────────────────┐
-│  terraform   │   Phase 1    │   controlplane   │  Phase 2   │   operators    │
-│  IaC modules │   Platform   │  DC-API · dcctl  │  Cloud     │  K8s operators │
-│  Harvester + │   Foundation │  cloud-ui (web)  │  Control   │  DBaaS, Key    │
-│  Rancher,    │ ─ consumed ─▶│  REST/CLI/UI     │◀─ backed ─ │  Vault, …      │
-│  net/backup/ │     by       │  cloud facade    │     by     │                │
-│  monitoring  │              │                  │            │                │
-└──────────────┘              └──────────────────┘            └────────────────┘
-      ▲
-      └─ main (this branch): index + roadmap only — no code
-
-  request flow:  user → dcctl / cloud-ui → DC-API → Harvester (VMs)
-                                                   → Rancher (clusters)
-                                                   → operators · PostgreSQL (state)
-```
-
-| Branch | Phase | What's here |
-|---|---|---|
-| **[`terraform`](https://github.com/wso2/open-cloud-datacenter/tree/terraform)** | Phase 1 — Platform Foundation | Terraform / IaC modules wrapping the Harvester + Rancher providers: tenancy, networks, backup, monitoring. Start here to provision the platform. |
-| **[`controlplane`](https://github.com/wso2/open-cloud-datacenter/tree/controlplane)** | Phase 2 — Cloud Control Plane | The cloud facade — **DC-API** (REST), **dcctl** (CLI), **cloud-ui** (web). Detailed plan in [`MILESTONES.md`](https://github.com/wso2/open-cloud-datacenter/blob/controlplane/MILESTONES.md). |
-| **[`operators`](https://github.com/wso2/open-cloud-datacenter/tree/operators)** | Supporting | Kubernetes operators (Database, Key Vault, …) that back the control-plane services. |
-| `main` | — | This index + roadmap. No code. |
-
-## Roadmap
-
-### Phase 1 — Platform Foundation · `terraform`
+→ [`github.com/wso2/open-cloud-datacenter/tree/controlplane`](https://github.com/wso2/open-cloud-datacenter/tree/controlplane)
 
-- **Tenancy & identity** — tenant isolation; Asgardeo OIDC claim-based RBAC (no local Rancher users); per-tenant quotas (CPU / memory / storage) at the project and namespace level.
-- **Terraform modules** — wrap the Harvester & Rancher providers for easy provisioning; modules to provision database instances.
-- **Network abstraction** — VLAN-backed networks in Harvester; load-balancer services via kube-vip with per-environment IP pools.
-- **Backup** — etcd backups to object storage; full Kubernetes backup via Velero.
-- **Monitoring** — a single Grafana stack covering Harvester HCI and tenant clusters; Alertmanager routing.
+## Reporting issues
 
-### Phase 2 — Cloud Control Plane · `controlplane`
+Found a bug or have a feature request? Use the [issue templates](.github/ISSUE_TEMPLATE)
+on this repo — bug reports and feature/improvement requests are triaged
+separately from general questions. Issues that apply to a specific layer
+(e.g. a Terraform module, an operator) are still filed here; mention the
+relevant branch in the report.
 
-Phase 1 gives tenants a Terraform-consumable sandbox; Phase 2 delivers a **cloud experience** — a REST API (DC-API), a CLI, and eventually a portal — that abstracts away Harvester, Rancher, and Kubernetes. The interface resembles a public cloud, with the Phase 1 platform as the backend. Detailed milestones live in [`MILESTONES.md`](https://github.com/wso2/open-cloud-datacenter/blob/controlplane/MILESTONES.md).
+## Contributing
 
-- **M1 — Compute & cluster provisioning API** — a facade API for provisioning compute and Kubernetes clusters.
-- **M1.5 — Full RBAC** — integrate an external identity provider.
-- **M2 — Storage & networking** — network load balancers; a Kube-OVN virtual-network model (VPC, default gateway, DHCP, DNS); Longhorn-based storage.
-- **M3 — Platform services (as-a-Service)** — **Database**, **Key Vault**, **Registry**, and **Cache** *(planned)*.
-- **M4 — Self-service portal** — a React-based web UI.
-- **M5 — Tenant & project hierarchy** — an organization hierarchy for managing infrastructure.
+Contributions are welcome on every branch. Start with
+[`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) for the workflow, and the
+[pull request template](pull_request_template.md) for what a good PR looks
+like here. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before
+participating.
 
 ## License