mycroforge-docs/docs/project_layout.md

sidebar_position
4

Project layout

When you generate a new project with m4g init <project_name>, it will create a folder like the example below.

📦<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 m4g init command will initialize new projects with git by default. If you don't want to use git you can pass the option --without git to m4g init.

.venv

To promote isolation of Python dependencies, new projects are initialized with a virtual environment by default. When you clone a MycroForge repository from git, it won't have a .venv folder yet. You can run m4g hydrate in the root folder of the project to restore the dependencies.

api/routers/hello.py

This file defines a basic example router, which is imported and mapped in main.py. This router is just an example and can be removed or modified at you discretion.

db/engine/async_session.py

This file defines the async_session function, which can be used to open an asynchronous session to a database.

db/entities/entity_base.py

This file contains an automatically generated entity base class that derives from the DeclarativeBase. All entities must inherit from this class, so that SQLAlchemy & alembic can track them. The entities directory is also where all newly generated entities will be stored.

db/versions

This is where the generated database migrations will be stored.

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 closer look at the imports, you'll see that the file has been modified to assign EntityBase.metadata to a variable called target_metadata, this will allow alembic to track changes in your entities. You'll also find 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 to include the generated classes.

db/script.py.mako

This file is automatically generated by the alembic init command.

db/settings.py

This file defines the DbSettings class, that is responsible for retrieving the database connectionstring. You will probably want to modify this class to retrieve the connectionstring from a secret manager at some point.

.gitignore

The default .gitignore file that is generated by the m4g init command. Modify this file at your discretion.

alembic.ini

This file is automatically generated by the alembic init command.

db.docker-compose.yml

A docker compose file for running a database locally.

m4g.json

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. When generating entities, many-to-many relations or routers, this file will be modified to include the generated files.

requirements.txt

The requirements file containing the Python dependencies. Whenever you run m4g install or m4g uninstall this file will be updated too.