Control plane structure (#19)

Signed-off-by: Miguel Martinez Trivino <miguel@chainloop.dev>

Author: migmartri

CONTRIBUTING.md

@@ -29,15 +29,13 @@ information on using pull requests.
 
 To learn more about how to run the project locally refer to our development [guide](./devel/README.md).
 
-## I Have a Question
+## Feedback and Questions
 
-> If you want to ask a question, we assume that you have read the available [Documentation](https://docs.chainloop.dev).
-
-Before you ask a question, it is best to search for existing [Issues](https://github.com/chainloop-dev/chainloop/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.
-
-If you then still feel the need to ask a question and need clarification, we recommend the following:
+If you have any question or piece of feedback don't hesitate to
 
 - Open an [Issue](https://github.com/chainloop-dev/chainloop/issues/new)
 - Reach out via our [Discord Server](https://discord.gg/f7atkaZact)
 
+We are very excited to have you on board!
+
 Welcome contributor!

app/controlplane/README.md

@@ -1,7 +1,97 @@
-## Chainloop Control Plane
+# Control Plane
 
-### Testing
+## Structure overview
 
-We've implemented two kinds of tests, unit tests (`make run test-unit`) and integration tests. The latter talks to a containerized database and hence are expensive to run.
+The control plane is a [Go](https://go.dev/) service that leverages [protocol buffers](https://github.com/protocolbuffers/protobuf) and [gRPC](https://grpc.io/) for its API, [ent](https://entgo.io) as ORM, [wire](https://github.com/google/wire/) for dependency injection and the [kratos framework](https://github.com/go-kratos/kratos) for additional utilities such middlewares, configuration management or error handling.
 
-Note: to run all the tests just run `make test`
+It's implemented following(ish) [Hexagonal architecture](https://netflixtechblog.com/ready-for-changes-with-hexagonal-architecture-b315ec967749) with the following top to down layers.
+
+- API definition layer `./api/`. proto definitions and generated code for the external gRPC API
+- Server layer `./internal/server`. Definition and registration of the HTTP and gRPC servers and middlewares.
+- Service layer `./internal/service`. Implementation of the protocol buffer services.
+- Business layer `./internal/biz`. Implementation of use-cases referenced by the service layer and definition of the data repository abstractions.
+- Data layer `./internal/data`. Implementation of data repositories interfaces defined in the business layer.
+
+## System Dependencies
+
+The control plane has 4 main dependencies
+
+![controlplane](../../docs/img/controlplane-overview.png)
+
+- OpenID Connect (OIDC) provider. Chainloop authentication backend is delegated to a OIDC provider (i.e Google, GitHub or [Auth0](https://auth0.com/)) for single sign on.
+- The persistance layer requires a [PostgreSQL](https://www.postgresql.org/) database.
+- Sensitive information provided by the user such as OCI registry credentials is sent to a secret storage backend. Currently we support both [Hashicorp Vault](https://www.vaultproject.io/) and [AWS Secret Manager](https://aws.amazon.com/secrets-manager/).
+- In addition to those third party dependencies, the control plane also has a dependency on Chainloop own [Artifact CAS](../artifact-cas). It is used to upload the received attestation to the end-user storage backend.
+
+> NOTE: The control plane does not store attestation or artifact data, these get forwarded to the user storage backend through the Artifact CAS.
+
+## Runbook
+
+We leverage `make` for most development tasks. Run `make -C app/controlplane` to see a list of the available tasks.
+
+### Run the project in development
+
+Refer to [development guide](../../devel/README.md) for more information but in a nutshell.
+
+```
+# Run external dependencies (Dex for OIDC, bitnami/postgreSQL container for persistence and Vault for secret management)
+
+docker compose -f devel/docker-compose.yml up
+
+# Run the control plane
+make -C app/controlplane run
+```
+
+Next, follow the steps that can be found [here](../../devel/README.md#4---using-the-cli-pointing-to-the-local-environment) to configure the CLI
+
+### Run tests
+
+We've implemented two kinds of tests, unit tests (`make run test-unit`) and integration tests. The latter launch a containerized database and hence they are expensive to run.
+
+To run all the tests `make test`
+
+### Generate API code from protocol buffer defintions (\*.proto)
+
+We leverage buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first.
+
+Once done, generating the API code is as easy as executing
+
+```
+make api
+```
+
+### Update Application data model
+
+We use [ent](https://entgo.io) as database Object Relational Mapping (ORM).
+
+The way a change in the data model will works is
+
+- Add a new/update an existing entity via a schema update. Schemas can be found at `internal/data/ent/schema`
+- Generate the code changes associated with that schema change. `make generate`
+- Restarting the control plane will cause the schema change to be automatically migrated.
+
+### Update configuration schema
+
+The service runtime configuration is implemented by using [kratos built-in config module](https://go-kratos.dev/en/docs/component/config/).
+
+Meaning that the configuration schema is defined at `internal/conf/conf.proto`.
+
+To regenerate it run:
+
+```
+make config
+```
+
+### Update dependency injection
+
+In order to enforce inversion of control and prevent import cycles we use [wire](https://github.com/google/wire/) for dependency injection.
+
+Wire has a fairly steep learning curve, so we recommend taking a look [at their tutorial](https://github.com/google/wire/blob/main/_tutorial/README.md). In practice, in this project you will find a couple of wire_gen.go files (i.e `cmd/wire_gen.go`) and different provider defined.
+
+If you need to re-generate the injection code after a change just run `make generate`
+
+## Contribution guidelines
+
+Please make sure to review the [Contribution guidelines](../../CONTRIBUTING.md) and feel free to reach out if you have any questions!
+
+Welcome!