# General introduction

## What is MycroForge?

MycroForge is an opinionated CLI tool that is meant to facilitate the development of FastAPI & SQLAlchemy based backends.
It provides a command line interface that allows users to generate a skeleton project and other common items like 
database entities, migrations, routers and even basic CRUD functionality. The main purpose of this tool is to generate
boilerplate code and to provide a unified interface for performing recurrent development activities.


## Generating a project

To generate a project you can run the following command.

`m4g init <name>`

```
Description:
  Initialize a new project

Usage:
  m4g init <name> [options]

Arguments:
  <name>  The name of your project

Options:
  --without <api|db|git>  Features to exclude
  -?, -h, --help          Show help and usage information

```

Running this command will generate the following project structure.

```
📦<project_name>
 ┣ 📂.git
 ┣ 📂.venv
 ┣ 📂api
 ┃ ┗ 📂routers
 ┃ ┃ ┗ 📜hello.py
 ┣ 📂db
 ┃ ┣ 📂engine
 ┃ ┃ ┗ 📜async_session.py
 ┃ ┣ 📂entities
 ┃ ┃ ┗ 📜entity_base.py
 ┃ ┣ 📂versions
 ┃ ┣ 📜README
 ┃ ┣ 📜env.py
 ┃ ┣ 📜script.py.mako
 ┃ ┗ 📜settings.py
 ┣ 📜.gitignore
 ┣ 📜alembic.ini
 ┣ 📜db.docker-compose.yml
 ┣ 📜m4g.json
 ┣ 📜main.py
 ┗ 📜requirements.txt
```

Let's go through these one by one.

### .git

The project is automatically initialised with git by the `m4g init` command.
If you don't want to use git you can run `m4g init <name> --without git`.

### .venv

To promote isolation of Python dependencies, the project is initialized with a virtual environment by default.

### api/routers/hello.py

This file defines a basic example router, which is imported and mapped in `main.py`.

### db/engine/async_session.py

This file defines the `async_session` function, which can be used to asynchronously connect to a database.

### db/entities/entity_base.py

This is the automatically generated base class that all database entities will inherit from.
SQLAlchemy requires a base entity class to properly function.

### db/entities/versions

This is where the generated database migrations will be kept.

### db/README

This README file is automatically generated by the alembic init command.

### db/env.py

This is the database environment file that is used by alembic to interact with the database.
If you take a close look at the imports, you'll see that the file has been modified to include the entity metadata,
i.e. `EntityBase.metadata` and you should also notice that the `DbSettings` class is used to get the connectionstring.
Any time you generate a new database entity or create a many-to-many relation between two entities, this file will also
be modified.

### db/script.py.mako

This file is automatically generated by the alembic init command.

### db/settings.py

This file defines a class that is responsible for retrieving the connectionstring.

### .gitignore

The default .gitignore file/

### alembic.ini

The alembic ini file

### db.docker-compose.yml

A docker compose file for running a database locally.

### m4g.json

The m4g config file, this file contains some configs that are used by the CLI, 
for example the ports to map to the API and database.

### main.py

The entrypoint for the application.

### requirements.txt

The requirements file containing the Python dependencies.