docs: fix typos and fill empty sections in README

2024-06-20 16:56:13 +03:00 · 2024-06-20 16:56:13 +03:00 · 5101296673
commit 5101296673
parent c2af812770
1 changed files with 168 additions and 54 deletions
--- a/README.md
+++ b/README.md
@ -1,9 +1,11 @@
 # SUPERKIT
-Build high-performance apps swiftly with minimal team resources in GO.
+
+Build high-performance apps swiftly with minimal team resources in Go programming language. **SUPERKIT** is a full-stack web framework that provides a set of tools and libraries to help you build web applications quickly and efficiently. **SUPERKIT** is built on top of the Go programming language and is designed to be simple and easy to use.

 > The project (for now) is in the **experimental** phase.

 ## Table of content
+
 - [SUPERKIT](#superkit)
  - [Table of content](#table-of-content)
 - [Installation](#installation)
@ -29,96 +31,208 @@ Build high-performance apps swiftly with minimal team resources in GO.
  - [Testing handlers](#testing-handlers)
 - [Create a production release](#create-a-production-release)

-# Installation
-Create your SUPERKIT project in a single command:
-```
+## Installation
+
+To create a new **SUPERKIT** project, you can run the following command:
+
+```bash
+# Create your SUPERKIT project in a single command:
 go run github.com/anthdm/superkit@master [yourprojectname]
-```

-You can now navigate to your project:
-```
+# You can now navigate to your project:
 cd [myprojectname]
-```

-Run npm install to install both tailwindcss and esbuild locally.
-```
+# Run npm install to install both tailwindcss and esbuild locally.
 npm install
-```

-If you run into dependency issues you can run:
-```
+# If you run into dependency issues you can run:
 go clean -modcache && go get -u ./...  
-```

-If you have the authentication plugin enabled you need to migrate your database.
-```
+# If you have the authentication plugin enabled you need to migrate your database.
 make db-up 
 ```

-# Getting started
+## Getting started
+
 ## Application structure
+
+The **SUPERKIT** project structure is designed to be simple and easy to understand. The project structure is as follows:
+
+```bash
+├── bootstrap
+│   ├── app
+│     ├──  assets
+│     ├──  conf
+│     ├──  db
+│       ├── migrations 
+│     ├──  events
+│     ├──  handlers
+│     ├──  types
+│     ├──  views
+│       ├── components
+│       ├── errors
+│       ├── landing
+│       ├── layouts
+│   ├── cmd
+│     ├── app
+│     ├── scripts
+│       ├── seed
+│   ├── plugins
+│     ├── auth
+│   ├── public
+│     ├── assets
+│   ├── env.local
+│   ├── go.mod
+│   ├── go.sum
+│   ├── Makefile
+│   ├── package-lock.json
+│   ├── package.json
+│   ├── tailwind.config.js
+├── db
+├── event 
+├── kit
+│   ├── middleware
+├── validate
+├── view
+├── go.mod
+├── install.go
+├── README.md
+```
+
 ### assets
+
+Assets are stored in the `assets` directory. This directory contains all your CSS and JavaScript files. The `assets` directory is structured as follows:
+
+```bash
+assets
+├── css
+│   ├── app.css
+├── js
+│   ├── app.js
+```
+
 ### conf
+
+Configuration. First, config.yml is read, then environment variables overwrite the yaml config if they match. The config structure is in the config.go. The env-required: true tag obliges you to specify a value (either in yaml, or in environment variables).
+
+Reading the config from yaml contradicts the ideology of 12 factors, but in practice, it is more convenient than reading the entire config from ENV. It is assumed that default values are in yaml, and security-sensitive variables are defined in ENV.
+
 ### db
+
+The `db` directory contains all your database related files. The `db` directory is structured as follows:
+
+```bash
+db
+├── migrations
+│   ├── 20210919123456_create_users_table.sql
+├── seeds
+│   ├── seed.go
+```
+
 ### events
+
+The `events` directory contains all your event related files. These files are used to define custom events and event handlers for the project. The `events` directory is structured as follows:
+
+```bash
+events
+├── event.go
+```
+
 ### handlers
+
+The `handlers` directory contains the main handlers or controllers for the project. These handlers handle incoming requests, perform necessary actions, and return appropriate responses. They encapsulate the business logic and interact with other components of the project, such as services and data repositories.
+
+It is important to note that the project structure described here may not include all the directories and files present in the actual project. The provided overview focuses on the key directories relevant to understanding the structure and organization of the project.
+
 ### types
+
+The `types` directory contains all your type related files. For example, you can define your models, structs, and interfaces in this directory. The `types` directory is structured as follows:
+
+```bash
+types
+├── user.go
+├── auth.go
+```
+
 ### views

-## Development server
-You can run the development server with the following command:
+The `views` directory contains all your view related files. These files are used to render HTML templates for the project. The `views` directory is structured as follows:
+
+```bash
+views
+├── home.go
+├── about.go
 ```
+
+## Development server
+
+You can run the development server with the following command:
+
+```bash
 make dev 
 ```

 ## Hot reloading the browser
+
 Hot reloading is configured by default when running your application in development.

 > NOTE: on windows or on in my case (WSL2) you might need to run `make watch-assets` in another terminal to watch for CSS and JS file changes.

-# Migrations
-## Create a new migration
-```
+## Migrations
+
+### Create a new migration
+
+```bash
 make db-mig-create add_users_table
 ```

 The command will create a new migration SQL file located at `app/db/migrations/add_users_table.sql`

-## Migrate the database 
-```
+### Migrate the database
+
+```bash
 make db-up
 ```

-## Reset the database 
-```
+### Reset the database
+
+```bash
 make db-reset
 ```

 ## Seeds
-```
+
+```bash
 make db-seed
 ```
+
 This command will run the seed file located at `cmd/scripts/seed/main.go`

-# Creating views with Templ 
+## Creating views with Templ
+
 superkit uses Templ as its templating engine. Templ allows you to create type safe view components that renders fragments of HTML. In-depth information about Templ can be found here:
 [Templ documentation](https://templ.guide)

-# Validations
+## Validations
+
 todo

-# Testing
-## Testing handlers
+## Testing
+
+### Testing handlers
+
+## Create a production release

-# Create a production release
 superkit will compile your whole application including its assets into a single binary. To build your application for production you can run the following command:
-```
+
+```bash
 make build
 ```
+
 This will create a binary file located at  `/bin/app_prod`.

 Make sure you also set the correct application environment variable in your `.env` file.
-```
+
+```bash
 SUPERKIT_ENV = production
 ```
-