diff --git a/README.md b/README.md
index 4de080b9..99f4b15d 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,12 @@
-# Open Cloud Datacenter (OCD)
+
+ 
+
+
+# Open Cloud Data Center (OCD)
+
+[](LICENSE)
+[](https://github.com/wso2/open-cloud-datacenter/issues)
+[](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
(dispatches custom resources)"]
+ B --> C["operators
(DBaaS · Key Vault)"]
+ C --> H
+
+ P["platform admin"] --> T["terraform
(IaC modules)"]
+ T --> H
+
+ H["Harvester + Rancher
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**:
@@ -20,59 +66,23 @@ The same control plane, two ways — provision a virtual network from the **CLI*
-## 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
diff --git a/docs/media/RepoBanner.png b/docs/media/RepoBanner.png
new file mode 100644
index 00000000..cb76cd49
Binary files /dev/null and b/docs/media/RepoBanner.png differ