Directory Structure & Files
As said, nothing here is a requirement, only a recommendation.
This is an example structure that is used in the "quokka-scratch" template and all my other modules.
| Path | Job |
|---|---|
/src/entity | This directory contains your entities and entity repositories, which communicate directly with the database. |
/src/service | Here is the home of the services. They are supposed to do the heavy lifting and your business logic. |
/src/service/page_loader | Whenever you want to provide data to your template, place a TemplateDataLoader in this directory. The TemplateDataLoaders are supposed as a thin wrapper between your template and services which refine the data of the services even more to make them usable in templates. This directory is somewhat optional, for smaller libraries it can be fine to have the loaders and stores in the service directory too. |
/src/command | If you need commands, this is the place to go. Put a struct here and implement the CommandHandler. Just don't forget to register your command in your bundle, so that it can actually be used. |
/src/controller | Every web application needs controllers! Most of them can probably be implemented using the template helpers like the StaticTemplate, DataTemplate or FormTemplate. |
/web/assets/$MODULE_NAME | Contains the static assets of the bundle. I'd like to recommand to provide a subdirectory named like your bundle to prevent collisions. The resources can be retrieved from /resources/$MODULE_NAME/$PATH. |
/web/templates | Contains the HTML templates, styles and scripts. Also here, providing a subdirectory, is recommended. I also personally like to keep all the resources (script, styles & templates) in the same "component" directory to have everything in a single place. But you might also very well create separate directories for each set of files. |
/web/templates/$MODULE | The template directory will get a subdirectory which is the name of you module. By this you can avoid to have template conflicts. Also others can target to overwrite your templates. |
/web/templates/$MODULE/style.scss | This style file should @use all your style files. The compiled file can then be loaded from the /styling/$MODULE/style.scss url. |
/web/templates/$MODULE/script.js | This script file should import all your script files. The compiled file can then be loaded from the /scripting/$MODULE/script.js url. To work properly the <script> should be imported with the type="module" attribute. |
/migrations | Contains the sqlx migrations. Either .sql migrations (up only), or .up.sql and .down.sql pairs to support up and down migrations. |