update docs

README.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <img src="./static/img/logo.webp" alt="anvil" width="500" height="500">
+<div>
+
 # Anvil
 
 Anvil is like OpenAPI schemas for microservices, but instead of only documenting your http routes, it helps you to manage most of the aspects of all your microservices at a global scale. It's created to medium~big companies and suffer on delivering things with velocity and consistency.
@@ -74,7 +78,7 @@ Anvil plugins:
 
 ## How Anvil work
 
-Anvil has 4 main parts, each one responsible for a specific complementary role.
+Anvil has 5 main parts, each one responsible for a specific complementary role.
 
 ### `*.anv` files
 
@@ -103,20 +107,10 @@ Generators allows you to generate code based on a `.anv` config. They come in va
 
 Generator are were the magic oh Anvil happens.
 
-## Meaning
-
-- Domain: Name of the domain being documented
-- Relationships: The relationships that your domain have with other domains and micro-services
-- Types: Generic types to be used as Input or Output for `Repository` and `Usecase` methods
-- Enums: Enums to be used as types for `Entity`, `Events` and `Repository` and `Usecase` methods
-- Entities: Tables on your database
-- Repository: The way that you communicate with the tables on your database
-- Events: Events emitted by this domain
-- Usecase: Where all the business logic stays, has the methods to be used by the consumers through delivery methods
-- Delivery: General config for delivery methods
+### Plugins
 
-## Recommended Confidentiality Levels
+Plugins do side-effects with Anvil, like:
+- Create tasks in Jira based on the changes of the schema.
+- Notify breaking changes to dependent projects
 
-- Low: Can be accessed by anyone with access to the service, can be logged and send in events
-- Medium: Can only be accessed by services with special permission, cannot be logged or send in events
-- High: Can only be accessed inside the domain, cannot be accessed by other services, logged or send in events
+Very useful for Agile environments.

docs/docs/generators/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Generators",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "How to develop generators"
+  }
+}

docs/docs/generators/communication.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 3
+---
+
+# Communication between CLI & generator

docs/docs/generators/generator-parts.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 4
+---
+
+# Parts of a generator
+
+Usually, you generator will have the following parts:
+- Methods:
+  - `create`
+  - `update`
+  - `delete`

docs/docs/generators/internal-schema.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 2
+---
+
+# Internal Schema
+
+We have 2 `schema`s.
+
+The first thing that you need to know when developing for Anvil is that the `schema` that Anvil uses internally is completly different than the one that the users write (`.anv` files).
+
+While the `schema` for written by users is focosed on:
+- Beign easily understandable for humans
+- Beign able to share knowledge to other humans (trough comments)
+- Beign easy and lean to write
+- Beign divisible in multiple files
+- Organized in the way that you architect your API
+
+The internal `schema` that Anvil uses is focused on:
+- Beign performatic to parse by the machine
+- Having everything that you need in one single file
+- Already have all the references resolved
+- Most performative as possible to access all the values that you may need
+- Organized on the way that your program will generate things
+
+To identify the difference between processed / internal `schema`s and "user-friendly" `schema`s, we have 2 different types of files:
+- `.anv`: user friendly schema, the one described [here](../schema).
+- `.anvp`: processed schema, made by the machine for the machine
+
+You will never touch a `.anvp` file, but Anvil will always use this format to communicate to your generator.
+
+## When and how does Anvil CLI communicates with the generator?
+
+Anvil CLI calls your generator when the configuration says so.
+
+Anvil CLI uses `stdout`, a decision inspired by LSPs. All the information is formmated in **JSON string**.

docs/docs/generators/intro.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 1
+---
+
+# Introduction
+
+Thanks for wanting to develop things for Anvil! We are here to try to make your journey as smooth as possible.
+
+In this page, we will guide you about the necessary things that you need to know **BEFORE** starting to create your generator.
+
+## What is a generator?
+
+Generators are CLIs that generate things.
+
+These things can be code, schemas, migrations, anything you want.
+
+They should not be used to perform side-actions, like create tasks on Jira, or do things that aren't related to generate things: Yout generator MUST have an output.
+
+To do side actions use [plugins](../plugins).
+
+## Do I need to use a specific language to create?
+
+No, you can use any programming language that you want, you just need to make it executable by the final user.
+
+Example: If you are creating a generator for NodeJs projects using NodeJs, the final user probably will have NodeJs installed, so you can ship JS files directly.
+
+You can run your generator any way that you want, the command to run it is specified on the `.anvilconfig` file.
+
+## How to create a generator?
+
+:::warning
+
+**BEFORE** creating your generator, please get to know and understand our [internal schema](./internal-schema).
+
+:::

docs/docs/intro.md

@@ -1,47 +1,68 @@
 ---
 sidebar_position: 1
 ---
+# Anvil
 
-# Tutorial Intro
+Anvil is like OpenAPI schemas for microservices, but instead of only documenting your http routes, it helps you to manage most of the aspects of all your microservices at a global scale. It's created to medium~big companies and suffer on delivering things with velocity and consistency.
 
-Let's discover **Docusaurus in less than 5 minutes**.
+It follows an _schema-first_ approach, of instead of writing your code first, you write an schema, and it generates most of the code for you, all that parts that are repetitive and doesn't influence in the performance, while letting you have 100% control of the part that matters: the business logic.
 
-## Getting Started
+The schema is designed for **Event-Oriented, Domain-Driven, Decoupled MicroServices, with a Delivery-Usecase-Repository architecture and SQL Databases**. It still can be used for monoliths and other types of architectures, but we don't maintain the schema to be extremely flexible and a silver bullet for all the projects. Or goal here **IS NOT** to allow creativity, is to have a way to create scalable, secure and maintainable applications.
 
-Get started by **creating a new site**.
+## How Anvil can help you
 
-Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
+- Documentation tool:
+  - Were data is used across your whole system and projects
+  - If data is confidential / has any legal protection
+  - Which services and domains depends on each other
+  - Which events and routes does a service has, so you can subscribe to them without having to communicate with the owner team, making process faster
+- Code generation tool:
+  - Define your own project pattern and generate projects on your own way
+  - Ensure that developers follow a specific pattern
+  - Keep dependencies updated across all your projects
+  - Ensure that best practices / your practices are begin followed
+  - Automatic integrate observability tools, logging, anything you want, on your projects, by default
+  - Ensure standards on variable names, event names and patterns, folder structure and project architecture
+- Refactoring tool:
+  - Want to refactor an old project in a new language / pattern? Use the same schema, a different generator, and you only have to copy-paste / do small adjusts on the business logic. Decrease the refactoring time by an immensurable amount of time.
+  - Test the same project on different languages and architectures, to see which one is the best. Use one schema, different generators, and generate the same API in multiple languages in a fraction of the time that it would took.
 
-### What you'll need
+Anvil allows you to write once, document and generate everywhere. Once that you have your schema defined, a lot of doors opens to you.
 
-- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
-  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+## What INS'T Anvil
 
-## Generate a new site
+- Something to control/create/update your infrastructure like CloudFormation, Terraform or Serverless Framework
+- A framework to magically implement things under the hood, hide complexity and make you dependent on it
+- Something to guide exactly how you should implement your code, your architecture, your folder structure, and so on
+- A message bus to help you send and receive events
 
-Generate a new Docusaurus site using the **classic template**.
+## Why use Anvil
 
-The classic template will automatically be added to your project after you run the command:
+**TL;DR**
+Anvil will help you to:
+- Need less developers to accomplish the same (probably even best) results
+- Decrease the amount of time that it takes to create new products and features, without having to compromise the quality and security of the software
+- Better divide the responsibilities of your team, to get the best that they can offer and not needing so many experienced developers to create amazing products
 
-```bash
-npm init docusaurus@latest my-website classic
-```
+In large organizations, we usually have hundreds or even thousands of micro-services, teams, events, packages and team members changing teams in a daily basis. It's very hard and demanding to maintain everything, to share these knowledge of the best practices, to ensure that all developers not only know how to implement certain patterns but know the way that the company implements certain patterns.
 
-You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+Anvil is created for these kind of ecosystems. It allows you to have one centralized small team of extremely capable developers that say how the things will work, define rules, best practices, standard libraries, and everything else that you need or want to defined, and all the other teams and members of your organization will follow these rules and patterns.
 
-The command also installs all necessary dependencies you need to run Docusaurus.
+## How Anvil does these things?
 
-## Start your site
+Anvil by itself:
+- _Schema-first_ approaches help you to visualize the current state of your system in a very easy and fast way: Instead of having to understand code, the project pattern, searching in a bunch of files, go directly to the ONE file definition anf figure it out right away.
+- Instead of trying to reinvent the wheel, you can follow a standardized architecture that is scalable, clean, flexible, follows the best practices and allows the work to be divided in multiple steps that can be executed in parallel
+- Standardize all you micro-services to follow the exact same patterns for EVERYTHING, decreasing a lot the learning curve and the effort necessary to maintain them
+- Allows tracking and usage of confidential and private data, like user's emails, to complain with regulations
 
-Run the development server:
+Anvil generators:
+- Generate e2e tests, useful for early stage startups that can't afford a QA or have enough time to implement more complex tests
+- Generate `.proto` files for gRPC APIs and OpenAPI specs for REST APIs
+- Generate database migrations and automatically handle them, begin able to easily see the current state of your database by looking at the schema file
+- Generate standardized clients for your APIs, with automatically generate `CHANGELOG.md`s that follows [SemVer](https://semver.org)
+- You are not stuck to Anvil. It's not a framework, it generates code that you have 100% control of. If you don't want to use Anvil anymore, it will have no impact on your systems.
 
-```bash
-cd my-website
-npm run start
-```
-
-The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
-
-The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
-
-Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
+Anvil plugins:
+- Integration with other tools like Jira, Linear, Slack or your own custom system to send notifications / perform tasks
+- Easy to change things at a global scale: Do not get stuck into a language, framework or architecture anymore, if you want to change it one day, it will be 100x times easier and faster.

docs/docs/plugins/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Plugins",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "How to develop plugins"
+  }
+}