Replace high level architecture diagram with editable PNG

CONTRIBUTING.md

@@ -46,12 +46,16 @@ documentation, fixing a bug, adding or enhancing a feature, or fixing a typo.
 
 Changes to the behavior of `korifi/api` or `korifi/controllers` will require that you build and test your changes.
 
-When adding new functionality, or fixing bugs, add appropriate test coverage
+When adding new functionality or fixing bugs, add appropriate test coverage
 where possible. Different parts of the code base have different strategies and
 patterns for testing, some of which may be in flux at any point in time.
-Consider commenting on the issue to seek input or  or opening a draft pull
+Consider commenting on the issue to seek input or opening a draft pull
 request to seek feedback on approaches to testing a particular change.
 
+When contributing new diagrams to the docs, provide a way for others to update the diagrams in the future.
+We recommend using [Draw IO](https://www.drawio.com/) since it supports embedding diagram metadata within
+the PNG files themselves. This allows future contributors to import the diagram and update it.
+
 To build the project from source, please consider the docs on [local development](HACKING.md).
 
 ### Commit Messages

docs/architecture.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-![Korifi Architecture Diagram](images/korifi_architecture.jpg)
+![Korifi Architecture Diagram](images/korifi-high-level-architecture.drawio.png)
 
 ### Core Components
 Korifi is built up of the following core components:
@@ -88,7 +88,7 @@ Cloud Foundry has a tiered tenancy system consisting of the cluster or "foundati
 We model these using Kubernetes namespaces. There is a root "cf" namespace that can contain multiple `CFOrg` custom resources. These trigger the creation of K8s namespaces for each org which themselves will contain `CFSpace` resources that point to additional namespaces for each space. This is convenient because it maps closely to the CF model in terms of app isolation and user permissions on Kubernetes. Initially we used the [Hierarchical Namespaces Controller project](https://github.com/kubernetes-sigs/hierarchical-namespaces) to manage this hierarchy, but moved away to a custom implementation for [various reasons](https://docs.google.com/document/d/1AVZPcoOphbWU8tVJ2gM7UkEC0EvHaki6scWgp8DuCDY/edit).
 
 ### Routing
-![Korifi Routing Diagram](images/korifi_routing.jpg)
+![Korifi Routing Diagram](images/korifi-routing-diagram.drawio.png)
 
 We integrate with the [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) to implement routing to both the Korifi API and app workloads. The `CFRoute` custom resource supports the  CF route management APIs and is converted into GatewayAPI `HTTPRoute` and Kubernetes `Service` resources. We use a validating webhook to apply Cloud Controller's validation rules to the routes (e.g. no duplicate routes, route has a matching `CFDomain`, etc).