Architecture docs (#22)

* WIP: doc added

* added some architecture docs

* updated architecture diagram

* adding README badges

* removing invalid group definitions from test yamls

* added description about actions

README.md

@@ -1,3 +1,5 @@
+[![Go Reference](https://pkg.go.dev/badge/github.com/kubermatic-labs/registryman.svg)](https://pkg.go.dev/github.com/kubermatic-labs/registryman) ![CI](https://github.com/kubermatic-labs/registryman/actions/workflows/ci.yaml/badge.svg)
+
 -----
 # Registryman
 
@@ -118,7 +120,7 @@ command. Similarly to apply, you have to specify the directory where the YAML
 files describing the registries reside.
 
 ```bash
-$ registryman state <path-to-configuration-dir>
+$ registryman status <path-to-configuration-dir>
 ```
 
 ### Generating the Swagger API

cmd/apply.go

@@ -32,13 +32,10 @@ var dryRun bool
 // applyCmd represents the apply command
 var applyCmd = &cobra.Command{
 	Use:   "apply",
-	Short: "A brief description of your command",
-	Long: `A longer description that spans multiple lines and likely contains examples
-and usage of using your command. For example:
-
-Cobra is a CLI library for Go that empowers applications.
-This application is a tool to generate the needed files
-to quickly create a Cobra application.`,
+	Short: "Apply the configuration",
+	Long: `The necessary configuration steps are performed based
+on the configuration files which describe the expected
+state of the system.`,
 	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		fmt.Println("apply called")
@@ -99,13 +96,4 @@ func init() {
 	rootCmd.AddCommand(applyCmd)
 
 	applyCmd.PersistentFlags().BoolVar(&dryRun, "dry-run", false, "if specified, no operation will be performed")
-	// Here you will define your flags and configuration settings.
-
-	// Cobra supports Persistent Flags which will work for this command
-	// and all subcommands, e.g.:
-	// applyCmd.PersistentFlags().String("foo", "", "A help for foo")
-
-	// Cobra supports local flags which will only run when this command
-	// is called directly, e.g.:
-	// applyCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
 }

cmd/root.go

@@ -35,12 +35,9 @@ var cfgFile string
 
 // rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
-	Use:   "kubermatic-harbor",
-	Short: "Harbor API testing",
-	Long:  `Test the Harbor API`,
-	// Uncomment the following line if your bare application
-	// has an action associated with it:
-	// Run: func(cmd *cobra.Command, args []string) { },
+	Use:   "registryman",
+	Short: "RegistryMan global registry manager",
+	Long:  `RegistryMan global registry manager`,
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.
@@ -74,9 +71,9 @@ func initConfig() {
 		home, err := homedir.Dir()
 		cobra.CheckErr(err)
 
-		// Search config in home directory with name ".kubermatic-harbor" (without extension).
+		// Search config in home directory with name ".registryman" (without extension).
 		viper.AddConfigPath(home)
-		viper.SetConfigName(".kubermatic-harbor")
+		viper.SetConfigName(".registryman")
 	}
 
 	viper.AutomaticEnv() // read in environment variables that match

cmd/status.go

@@ -31,6 +31,7 @@ var statusCmd = &cobra.Command{
 	Use:   "status",
 	Short: "Get registry status information",
 	Long:  `Get registry status information`,
+	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		config.SetLogger(logger)
 		logger.Info("reading config files", "dir", args[0])

doc/actions.md

@@ -0,0 +1,48 @@
+# Actions
+
+Actions are the results of the `globalregistry.reconciler/Compare` function when
+the expected and actual registry state are compared. Actions describe the
+operations that are to be performed on the registry to reach the actual state.
+Action is defined as an interface:
+
+``` go
+type Action interface {
+	String() string
+	Perform(globalregistry.Registry) (SideEffect, error)
+}
+```
+
+An action has a string representation via the `String` method and and action can
+be executed via the `Perform` method.
+
+Examples for action implementation are:
+
+  * creating a project
+  * removing a member from a project
+  * assign a scanner to a project, etc.
+
+# SideEffects
+
+On one hand Actions can succeed or fail, which is reflected in the returned
+error. On the other hand, Actions may require further operations to be performed
+which are not related to the registry. For example a file shall be stored in the
+local file system. Such an operation is implemented as a SideEffect, which is
+created when an Action is performed.
+
+A SideEffect is an interface too:
+
+``` go
+type SideEffect interface {
+	Perform(ctx context.Context) error
+}
+```
+
+The parameters of the SideEffect shall be encapsulated into the `ctx` parameter
+of the `Perform` method.
+
+The `globalregistry/reconciler` package implements a `nilEffect` variable that
+can be used as a no-op SideEffect.
+
+<!-- Local Variables: -->
+<!-- mode: gfm -->
+<!-- End: -->