Magic middleware documentation
This is the documentation for Magic itself, implying the “middleware” found in Magic’s core. This part documents everything that wires up Magic, and the backend of modules such as Hyper IDE and the CRUDifier. This is where you will find information about the file system of Magic, system endpoints, system slots, and everything that makes Magic “tick”. This is hence the documentation of Magic itself.
There are 4 primary folders in Magic, these are as follows.
- etc - Your private “data files”
- misc - Magic’s “data files”
- modules - Your own custom modules goes here
- system - Magic’s system modules goes here
The “modules” folder and the “system” folders are the only folders that allows for resolving Hyperlambda endpoints, while the other folders are for helper files, and/or uploaded files. If you use the docker images of Magic, Magic will automatically update the following folders as you pull the Docker images from Docker hub.
This implies that you should not edit files in these folders, since if you do, your changes might vanish the next time you update Magic. You should also not store your own files in these folders, since your files might disappear the next time you update Magic. The only folder where it’s safe to store your own files and folders within are as follows.
- etc - For dynamic files, uploads and downloads, etc
- modules - For your own custom Hyperlambda modules
The two remaining folders; “misc” and “system” should be kept for Magic’s internals, and not tampered with in any ways. If in doubt, most folders in Magic has README files you can open to see the purpose of a specific folder, and/or its files - And in fact, becoming acquinted with Magic’s file and folder structure is probably a smart investment, since everything in Magic is based upon “conventions”, implying folders have semantic value of some sort. As a general rule of thumb you should keep all your Hyperlambda code inside “modules” and everything else in “etc”.
Creating startup logic
Most modules requires some sort of “initialisation” logic. This can be to for instance create dynamic slots the module depends upon to function, and/or ensure the module’s database exists, etc. This can be accomplished by creating a folder inside your module and name this module “magic.startup”. All files recursively found inside this folder will be executed as the system starts, and/or the module is installed. You can also create such startup folders inside of sub folders within your module’s main folder.
When you start Magic for the first time, the system might need to initialise itself, which implies doing 3 things.
- Create a magic database, insert a root user into it, and initialise the authentication secret
- CRUDify the magic database
- Create a cryptography key pair for your server
These 3 steps is what you’re going through as you initially install Magic, either locally, or on
a VPS of your chosing. The first step requires you to have a database of some sort somewhere, where
Magic can create its internal
magic database. Magic will use this database for authenticating users,
logging, persisting tasks, etc.
The second step implies generating CRUD HTTP backend endpoints wrapping this database, to allow
you to interact with it through a client of some sort. The 3rd step is required to create a
public and private server key pair. This key is used for cryptographically secured lambda
invocations, but also in other parts of the system. Below is a screenshot of how this process
looks like as you install Magic initially.
After you have followed the above process, you can see that inside your “modules” folder there exists Hyperlambda endpoint files wrapping your entire magic database into CRUD HTTP endpoints. These files were created in the second step of the above process, and is required to have Magic functioning properly. Below you can see a screenshot of how the folder structure looks like in Magic through Hyper IDE.
The “exceptions.hl” file at the root of your folder structure is the default exception handler that will be used if no module creates its own exception handler logic to override the default handler. Most folders have “README.md” files that somehow describes the purpose of the folder. Hyper IDE is as a general rule of thumb your “goto component” when you need to create something using Magic.
- Log component
- Assumptions component
- Cache component
- Endpoints component
- Sockets component
- Hyper IDE component
- Evaluator component
- SQL component
- Crudifier component
- Terminal component
- Tasks component
- Auth component
- Config component
- Crypto component
- Bazar component
- Profile component