doc(main): Updated documentation (#191)

README.md

@@ -8,30 +8,75 @@
 > Simple, modular, and observable Go framework for backend applications.
 
 <p align="center">
-  <img src="docs/assets/images/yokai-bck.png" width="350" height="350" />
+  <img src="docs/assets/images/yokai-bck.png" width="300" height="300" />
 </p>
 
-## Documentation
+<!-- TOC -->
+* [Goals](#goals)
+* [Overview](#overview)
+  * [Documentation](#documentation)
+  * [Architecture](#architecture)
+  * [Foundations](#foundations)
+  * [Extensions](#extensions)
+* [Getting started](#getting-started)
+* [Contributing](#contributing)
+<!-- TOC -->
+
+## Goals
+
+Building backend applications with [Go](https://go.dev/) is amazing.
+
+But to build production-grade applications, you need to put in place a bunch of efforts and boilerplate code, introducing complexity not even related to the logic of your application (like dependencies wiring, configuration management, observability instrumentation, etc.).
+
+To solve this, Yokai was created with the following goals in mind:
+
+- `Simple`: it is easy to use, configure and test, enabling you to iterate fast and deliver quickly maintainable applications.
+- `Modular`: it can be extended with the available Yokai modules, or with your own, to build evolvable applications.
+- `Observable`: it comes with built-in logging, tracing and metrics instrumentation, to build reliable applications.
+
+In other words, Yokai lets you focus on your application logic, while taking care of the rest.
+
+## Overview
+
+### Documentation
 
 Yokai's documentation is available online: [https://ankorstore.github.io/yokai](https://ankorstore.github.io/yokai).
 
-## Getting started
+### Architecture
+
+![Architecture](docs/assets/images/architecture.jpg)
+
+- Yokai `core modules` preloads logging, tracing, metrics and health check instrumentation, and expose a private HTTP server for infrastructure and debugging needs.
+- Yokai `extensions modules` can be added to enrich your application features, like public HTTP / gRPC servers, workers, ORM, etc. You can also add the [contrib modules](https://github.com/ankorstore/yokai-contrib) or your own.
+- Those are made available in Yokai `dependency injection system`, on which you can rely to build your application logic.
+
+### Foundations
 
-Yokai's documentation provide tutorials to help you create:
+Yokai was built using `robust` and `well known` Go libraries, like:
 
-- [HTTP applications](https://ankorstore.github.io/yokai/tutorials/http-application/)
-- [Worker applications](https://ankorstore.github.io/yokai/tutorials/worker-application/)
+- [Echo](https://github.com/labstack/echo) for HTTP servers
+- [gRPC-go](https://github.com/grpc/grpc-go) for gRPC servers
+- [Viper](https://github.com/spf13/viper) for configuration management
+- [OTEL](https://github.com/open-telemetry/opentelemetry-go) for observability instrumentation
+- [Fx](https://github.com/uber-go/fx) for dependency injection system
+- and more...
 
-## Templates
 
-Yokai provides repository templates to start creating your applications:
+### Extensions
 
-- [HTTP application template](https://github.com/ankorstore/yokai-http-template)
-- [Worker application template](https://github.com/ankorstore/yokai-worker-template)
+Yokai's `extension system` enables you to `enrich` your application features with:
+
+- the Yokai `built-in` modules
+- the Yokai [contrib modules](https://github.com/ankorstore/yokai-contrib)
+- your own modules
+
+## Getting started
 
-## Demos
+Yokai provides ready to use `application templates` to start your projects:
 
-Yokai provides a [showroom for demo application](https://github.com/ankorstore/yokai-showroom), where you can find several applications implementations examples.
+- for [gRPC applications](https://ankorstore.github.io/yokai/getting-started/grpc-application.md)
+- for [HTTP applications](https://ankorstore.github.io/yokai/getting-started/http-application.md)
+- for [worker applications](https://ankorstore.github.io/yokai/getting-started/worker-application.md)
 
 ## Contributing
 

docs/assets/stylesheets/extra.css

@@ -6,4 +6,14 @@
     display: block;
     margin: 0 auto;
     border: 5px solid hsla( 225deg ,15%,8%,1);
+}
+
+#overview-architecture {
+    background-color: #16181dde;
+    background-position: center center;
+    border-radius: 1em;
+    background-repeat: no-repeat;
+    display: block;
+    margin: 0 auto;
+    border: 2px solid hsla( 225deg ,15%,8%,1);
 }

docs/demos/grpc-application.md

@@ -0,0 +1,107 @@
+---
+icon: material/folder-eye-outline
+---
+
+# :material-folder-eye-outline: Demo - gRPC application
+
+> Yokai provides a [gRPC demo application](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo).
+
+## Overview
+
+This [gRPC demo application](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo) is a simple gRPC API offering a [text transformation service](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo/proto/transform.proto).
+
+It provides:
+
+- a [Yokai](https://github.com/ankorstore/yokai) application container, with the [gRPC server](../modules/fxgrpcserver.md) module to offer the gRPC API
+- a [Jaeger](https://www.jaegertracing.io/) container to collect the application traces
+
+### Layout
+
+This demo application is following the [standard go project layout](https://github.com/golang-standards/project-layout):
+
+- `cmd/`: entry points
+- `configs/`: configuration files
+- `internal/`:
+	- `interceptor/`: gRPC interceptors
+	- `service/`: gRPC services
+	- `bootstrap.go`: bootstrap (modules, lifecycles, etc)
+	- `services.go`: dependency injection
+- `proto/`: protobuf definition and stubs
+
+### Makefile
+
+This demo application provides a `Makefile`:
+
+```
+make up     # start the docker compose stack
+make down   # stop the docker compose stack
+make logs   # stream the docker compose stack logs
+make fresh  # refresh the docker compose stack
+make stubs  # generate gRPC stubs with protoc
+make test   # run tests
+make lint   # run linter
+```
+
+## Usage
+
+### Start the application
+
+To start the application, simply run:
+
+```shell
+make fresh
+```
+
+After a short moment, the application will offer:
+
+- `localhost:50051`: application gRPC server
+- [http://localhost:8081](http://localhost:8081): application core dashboard
+- [http://localhost:16686](http://localhost:16686): jaeger UI
+
+### Available services
+
+This demo application provides a [TransformTextService](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo/proto/transform.proto), with the following `RPCs`:
+
+| RPC                     | Type      | Description                                                  |
+|-------------------------|-----------|--------------------------------------------------------------|
+| `TransformText`         | unary     | Transforms a given text using a given transformer            |
+| `TransformAndSplitText` | streaming | Transforms and splits a given text using a given transformer |
+
+This demo application also provides [reflection](../modules/fxgrpcserver.md#reflection) and [health check ](../modules/fxgrpcserver.md#health-check) services.
+
+If you update the [proto definition](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo/proto/transform.proto), you can run `make stubs` to regenerate the stubs.
+
+### Authentication
+
+This demo application provides example [authentication interceptors](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo/internal/interceptor/authentication.go).
+
+You can enable authentication in the application [configuration file](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo/configs/config.yaml) with `config.authentication.enabled=true`.
+
+If enabled, you need to provide the secret configured in `config.authentication.secret` as context `authorization` metadata.
+
+### Examples
+
+Usage examples with [grpcurl](https://github.com/fullstorydev/grpcurl):
+
+- with `TransformTextService/TransformText`:
+
+```shell
+grpcurl -plaintext -d '{"text":"abc","transformer":"TRANSFORMER_UPPERCASE"}' localhost:50051 transform.TransformTextService/TransformText
+{
+  "text": "ABC"
+}
+```
+
+- with `TransformTextService/TransformAndSplitText`:
+
+```shell
+grpcurl -plaintext -d '{"text":"ABC DEF","transformer":"TRANSFORMER_LOWERCASE"}' localhost:50051 transform.TransformTextService/TransformAndSplitText
+{
+  "text": "abc"
+}
+{
+  "text": "def"
+}
+```
+
+You can use any gRPC clients, for example [Postman](https://learning.postman.com/docs/sending-requests/grpc/grpc-request-interface/) or [Evans](https://github.com/ktr0731/evans).

docs/demos/http-application.md

@@ -0,0 +1,83 @@
+---
+icon: material/folder-eye-outline
+---
+
+# :material-folder-eye-outline: Demo - HTTP application
+
+> Yokai provides a [HTTP demo application](https://github.com/ankorstore/yokai-showroom/tree/main/http-demo).
+
+## Overview
+
+This [HTTP demo application](https://github.com/ankorstore/yokai-showroom/tree/main/http-demo) is a simple REST API (CRUD) to manage [gophers](https://go.dev/blog/gopher).
+
+It provides:
+
+- a [Yokai](https://github.com/ankorstore/yokai) application container, with the [HTTP server](../modules/fxhttpserver.md) module to offer the gophers API
+- a [MySQL](https://www.mysql.com/) container to store the gophers
+- a [Jaeger](https://www.jaegertracing.io/) container to collect the application traces
+
+### Layout
+
+This demo application is following the [standard go project layout](https://github.com/golang-standards/project-layout):
+
+- `cmd/`: entry points
+- `configs/`: configuration files
+- `internal/`:
+	- `handler/`: HTTP handlers
+	- `middleware/`: HTTP middlewares
+	- `model/`: models
+	- `repository/`: models repositories
+	- `service/`: services
+	- `bootstrap.go`: bootstrap (modules, lifecycles, etc)
+	- `routing.go`: routing
+	- `services.go`: dependency injection
+
+### Makefile
+
+This demo application provides a `Makefile`:
+
+```
+make up     # start the docker compose stack
+make down   # stop the docker compose stack
+make logs   # stream the docker compose stack logs
+make fresh  # refresh the docker compose stack
+make test   # run tests
+make lint   # run linter
+```
+
+## Usage
+
+### Start the application
+
+To start the application, simply run:
+
+```shell
+make fresh
+```
+
+After a short moment, the application will offer:
+
+- [http://localhost:8080](http://localhost:8080): application dashboard
+- [http://localhost:8081](http://localhost:8081): application core dashboard
+- [http://localhost:16686](http://localhost:16686): jaeger UI
+
+### Available endpoints
+
+On [http://localhost:8080](http://localhost:8080), you can use:
+
+| Route                   | Description      | Type     |
+|-------------------------|------------------|----------|
+| `[GET] /`               | Dashboard        | template |
+| `[GET] /gophers`        | List all gophers | REST     |
+| `[POST] /gophers`       | Create a gopher  | REST     |
+| `[GET] /gophers/:id`    | Get a gopher     | REST     |
+| `[PATCH] /gophers/:id`  | Update a gopher  | REST     |
+| `[DELETE] /gophers/:id` | Delete a gopher  | REST     |
+
+### Authentication
+
+This demo application provides an example [authentication middleware](https://github.com/ankorstore/yokai-showroom/blob/main/http-demo/internal/middleware/authentication.go).
+
+You can enable authentication in the application [configuration file](https://github.com/ankorstore/yokai-showroom/blob/main/http-demo/configs/config.yaml) with `config.authentication.enabled=true`.
+
+If enabled, you need to provide the secret configured in `config.authentication.secret` as request `Authorization` header.