Humming-Bird is a very unopinionated web framework. It allows the developer to structure their projects however they like. As the creator of Humming-Bird I can openly say that this was on purpose, and takes after a few other popular frameworks.

Though this was on purpose, it can seem daunting, especially to people new to the Raku ecosystem, or new to designing web-applications in general. I hope to underline the few structures I have employed to making sure my application makes sense from a developers point of view, but also from a Raku point of view.

The Single File Service

If you find that your service will be small, you may want to consider building your system in a single-file. This is done very simply with a structure like:

App-MyService/    ├── bin/    │   └── my-service    ├── lib/    │   └── App/    │       └── MyService.rakumod    ├── META6.json    └── Dockerfile

In yourMETA6.json you'll have:

...    "provides": {        "App::MyService": "lib/App/MyService.rakumod"    }...

Then in yourbin file you'll want to import your service, and Humming-Bird, something like:

use Humming-Bird::Core;use App::MyService;listen(1234);

It is important that you importApp::MyService afterHumming-Bird::Core to avoid having some weird side-effects with route declarations in your service.

Model-View-Controller

Some web-apps would prefer to be elevated above the status of service, and would prefer to have a dynamic UI. This is typically done with theModel-View-Controller orMVC architecture. In a typical MVC application you separate concerns between the model, the view, and the controller by keeping them in separate name-spaces or folders.

With Humming-Bird, nothing really changes except that yourviews probably don't have to be individual Raku modules. I like to structure such applications like:

my-service/    ├── templates/    │   ├── foo.mustache    │   └── bar.mustache    ├── bin/    │   └── my-service    ├── lib/    │   └── App/    │       ├── MyService/    │       │   ├── Controller/    │       │   │   ├── Foo.rakumod    │       │   │   └── Bar.rakumod    │       │   └── Model/    │       │       ├── User.rakumod    │       │       ├── Friend.rakumod    │       │       └── Post.rakumod    │       └── MyService.rakumod    ├── META6.json    └── Dockerfile

You'll still want the sameuse statements in yourbin file, but this time you'll have to do a provide in yourMETA6 file for each of the nested modules.

..."provides": {    "App::MyService": "lib/App/MyService.rakumod",    "App::MyService::Controller::Foo": "lib/App/MyService/Controller/Foo.rakumod"    ...},...

Now you can layer your code nicely, having the controllers call to the models to get data, and then rendering pages based on your templates. In this example I usedTemplate::Mustache bysoftmoth, but you can also user other templating languages likeTemplate6 by theRaku Community, orRyML by the dashingtony-o.

Note: this is following an "Active-Record" approach to database management, where the sub-class of a type handlesRepository type actions. You can use either. If you are looking for an "Active-Record" style database manager ORM thing, you can useRed.

Microservice

With a microservice I'm typically more focused around data and its flow, because of this, I adapt my single-file structure to also have aRepository section, allowing me to nicely package my database interactions. I also like to have aQueue orCommunication module that handles talking with other service if I need to. This typically includes talking to queues, or establishing otherUDP orTCP connections.

With Microservices I prefer the more fine-grainedRepository approach where I can hone in on writing fast SQL vs the "Active-Record" approach that something likeRed gives you. Because of this, I typically useDBIish for microservices.

My simple microservice structure typically looks like:

my-service/    ├── bin/    │   └── my-service    ├── lib/    │   └── App/    │       ├── MyService/    │       │   ├── Communication/    │       │   │   ├── Queue.rakumod    │       │   │   └── Upstream.rakumod    │       │   ├── Repostiory/    │       │   │   ├── Foo.rakumod    │       │   │   └── Bar.rakumod    │       │   └── Controller/    │       │       ├── Foo.rakumod    │       │       └── Bar.rakumod    │       └── MyService.rakumod    ├── META6.json    └── Dockerfile

This blog post was fairly erratic, but I hope it demystified a little bit about project structure using Humming-Bird. I'm currently writing a smallMVC example for Humming-Bird, make sure to check theexamples directory to see some existing apps, and check back soon to see the full-fledgedMVC example.

Thanks for reading, Raku rocks!