diff --git a/pkg/services/apiserver/README.md b/pkg/services/apiserver/README.md
index 98df14b6dc1..fca557a4dde 100644
--- a/pkg/services/apiserver/README.md
+++ b/pkg/services/apiserver/README.md
@@ -79,3 +79,15 @@ The Kubernetes compatible API can be accessed using existing Grafana AuthN at: [
 
 The equivalent openapi docs can be seen in [http://localhost:3000/swagger](http://localhost:3000/swagger), 
 select the relevant API from the dropdown in the upper right.
+
+## General Structure
+
+The folder structure aims to follow the patterns established in standard (https://github.com/kubernetes/kubernetes)[kubernetes] projects when possible.
+
+* [pkg/apimachinery](/pkg/apimachinery) - this is based on the structure of [apimachinery](https://github.com/kubernetes/apimachinery). it contains types and utils that are used by both API clients and servers
+* [pkg/apiserver](/pkg/apiserver) - this is based on the structure of [apiserver](https://github.com/kubernetes/apiserver). it contains apiserver library code used for both standalone app apiservers and the one embedded in grafana. it depends on `pkg/apimachinery`
+* [pkg/services/apiserver](/pkg/services/apiserver) - this is where the embedded grafana API server background service is currently configured. it depends on `pkg/apiserver` and `pkg/apimachinery`. the closest analog in the Kubernetes monorepo is the [kube-apiserver cmd](https://github.com/kubernetes/kubernetes/tree/master/cmd/kube-apiserver/app).
+* [pkg/apis](/pkg/apis) - where API resource types are defined. this is based on the structure of the [sample-apiserver](https://github.com/kubernetes/sample-apiserver/tree/master/pkg/apis)
+* [hack/update-codegen.sh](/hack#kubernetes-hack-alert) - this script is used to run [k8s codegen](https://github.com/kubernetes/code-generator/), which generates the code that is used by the API server to handle the types defined in `pkg/apis`. it is based on the [update-codegen.sh from sample-apiserver](https://github.com/kubernetes/sample-apiserver/blob/master/hack/update-codegen.sh)
+* [pkg/registry/apis](/pkg/registry/apis) - where all of the types in `pkg/apis` are registered with the API server by implementing the [builder](/pkg/apiserver/builder/common.go#L18) interface. this pattern is unique to grafana, and is needed to support using wire dependencies in legacy storage implementations. this is separated from `pkg/apis` to avoid issues with k8s codegen.
+* [pkg/cmd/grafana/apiserver](/pkg/cmd/grafana/apiserver) - this is where the apiserver is configured for the `grafana apiserver` CLI command, which can be used to launch standalone API servers. this will eventually be merged with the config in `pkg/services/apiserver` to reduce duplication.
\ No newline at end of file