Merge pull request #3 from merico-dev/documents-improvement

Documents improvement

Author: basicthinker

README.md

@@ -6,24 +6,71 @@
 
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat&logo=github&color=2370ff&labelColor=454545)](http://makeapullrequest.com)
 [![Discord](https://img.shields.io/discord/844603288082186240.svg?style=flat?label=&logo=discord&logoColor=ffffff&color=747df7&labelColor=454545)](https://discord.gg/83rDG6ydVZ)
-![Test](https://github.com/merico-dev/stream/actions/workflows/master-builder.yaml/badge.svg)
+![Test](https://github.com/merico-dev/stream/actions/workflows/main-builder.yml/badge.svg)
 [![Go Report Card](https://goreportcard.com/badge/github.com/merico-dev/stream)](https://goreportcard.com/report/github.com/merico-dev/stream)
 
 # DevStream
 </div>
-Open-source DevOps tool manager (DTM).
 
-<br/>
+## DevStream, What Is It Anyway?
+
+DevStream is an open-source DevOps tool manager (DTM).
+
+Imagine you are in a new project. Before writing the first line of code, you would have to figure out the tools needed in the whole Software Development Life Cycle (SDLC). You would probably need the following pieces:
+
+- some kind of project management software or issue tracking tools (e.g., Jira);
+- someplace for source code management (GitHub and alike);
+- some tools for continuous integration (e.g., Jenkins, GitHub Actions, CircleCI, Travis CI);
+- some tools for continuous delivery or continuous deployment (e.g., fluxcd/flux2, ArgoCD, etc.);
+- someplace serving as the single source of truth for secrets and credentials (secrets manager, e.g., Vault by HashiCorp);
+- some tools for centralized logging and monitoring (for example, ELK, Prometheus/Grafana);
+
+and maybe more. The list could go on for quite a bit.
+
+And, there are multiple challenges in creating YOUR ideal SDLC workflow:
+
+- There are too many choices. Even for a particular field, there are too many. Which is best? There is no "one-size-fits-all" answer because it totally depends.
+- Integration between different pieces.
+- The software world (and the DevOps world) changes and it changes fast. What's best for today might not be the best tomorrow. You want to switch some parts out and get some new state-of-the-art pieces in so that you always keep your efficiency high.
+
+To be fair, there are a few integrated products out there that may contain everything you might need, but they might not suit your specific requirements perfectly. So, the chance is, you will still want to go out and do your research, find the best pieces for you, and integrate them. And, it would be a lot of operational overhead if all you had to do all day was install and uninstall and integrate things.
+
+You probably have already seen where we are going with this, and you are right: DevStream, an open-source DevOps tool manager (DTM), aims to be the solution here.
+
+Think of the Linux kernel V.S. different distributions. Different distros offer different packages so that you can always choose the best for your need.
+
+Or, Think of `yum`, `apt`, or `apk`. You can easily set it up with your favorite packages for any new environment using these package managers.
 
+DevStream aims to be the package manager for DevOps tools. To be more ambitious, DevStream wants to be the Linux kernel, around which different distros can be created with various components so that you can always have the best components for each part of your SDLC workflow.
+
+## Why Using DevStream?
+
+No more manual curl/wget download, apt install, helm install; no more local experiments and playing around just to get a piece of tool installed correctly.
+
+Define your wanted DevOps tools in a single human-readable YAML config file, and at the press of a button (one single command), you will have your whole DevOps toolchain and SDLC workflow set up.
+
+Want to install another different tool for a try? No problem. Want to remove or reinstall a specific piece in the whole workflow? Got your back.
+
+## Architecture
+
+See [docs/architecture.md](./docs/architecture.md).
 
 ## Build
 
 ```bash
 make
 ```
 
+## Configuration
+
+See [examples/config.yaml](./examples/config.yaml).
+
 ## Run
 
 ```bash
 ./dtm install -f examples/config.yaml
 ```
+
+## Contribute
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).

docs/architecture.md

@@ -0,0 +1,39 @@
+# DevStream Architecture Summary
+
+This document summarizes the main components of DevStream and how data and requests flow between these components.
+
+## DevStream Request Flow
+
+The following diagram shows an approximation of how DevStream executes a user command:
+
+![DevStream Architecture Diagram](./images/architecture-overview.png)
+
+## CLI (The `devstream` Package)
+
+Every time a user runs the `dtm` program, the execution transfers immediately into one of the "command" implementations in the [`devstream`](https://github.com/merico-dev/stream/tree/main/cmd/devstream) package, in which folder all commands' definitions reside. Then, each command calls the corresponding package under [`internal/pkg`](https://github.com/merico-dev/stream/tree/main/internal/pkg).
+
+The flow illustrated above applies to the main DevStream commands like `dtm install`, `dtm uninstall` (_TODO_), and `dtm reinstall` (_TODO_). For these commands, the role of the command is to parse all the config, load each plugin, and call the [predefined interface](https://github.com/merico-dev/stream/blob/main/internal/pkg/plugin/plugin.go#L12).
+
+## Configuration Loader
+
+Model types in package [`config`](https://github.com/merico-dev/stream/blob/main/internal/pkg/config/config.go) represent the top-level configuration structure.
+
+## State Manager
+
+_TODO_
+
+## Plugin Engine
+
+The plugin engine has various responsibilities:
+
+- making sure the required plugins (according to the config) are present (_TODO_)
+- generate a plan according to the state (_TODO_)
+- execute the plan by loading each plugin and running the desired operation
+
+_Note: there will be a rework of the engine to generate and execute a plan according to the state manager, which hasn't been implemented yet._
+
+## Plugins
+
+A _plugin_ implements the aforementioned predefined interfaces.
+
+It executes operations like install, reinstall (_TODO_), uninstall (_TODO_), and stores state (_TODO_).