Creating Your First Project with Torpedo: A Step-by-Step Guide

When building applications in Golang, adhering to the principles of Hexagonal Architecture can ensure clean, modular, and maintainable code. With Torpedo, you can easily implement this architecture while speeding up your development process. In this guide, we’ll walk through how to create your first project with Torpedo, from installation to generating entities and use cases.

This post is a summary of the documented quick start guide

1. Getting Started with Torpedo

Before we dive into creating a project, make sure you have Go installed on your system. Then, install Torpedo following the instructions at installation guide

This CLI tool will handle project generation, entity creation, and use case scaffolding for you. Once installed, you’re ready to create your first project.

2. Setting Up Your First Project

Lets begging with our first application built with Torpedo!. We will be building a fly reservation app called Booking Fly.

With Torpedo installed, creating a new project is as simple as running:

mkdir booking-fly && cd booking-fly

torpedo init

This command will generate the folder .torpedo where you should defines your entities and use cases. More info about this folder can be found at .torpedo dir struct

3. Defining Your First Entity

Next, you’ll want to define your domain entities. Entities are the core objects in your application’s business logic, representing things like User, Product, or Order.

To define your first entity, create a YAML file under the .torpedo/entities directory. For example, let’s create a simple User entity:

.torpedo/entities/user.yaml

version: torpedo.darksub.io/v1.0
kind: entity
spec:
    name: "user"
    plural: "users" 
    description: "The frequent flyer user"
    doc: |
        The user entity represents a system user but also a frequent flyer. 
        This entity is only for the example purpose.
    schema:
        reserved:
            id:
                type: ulid 

        fields:
          - name: name
            type: string
            description: "The user full name"

          - name: email
            type: string
            description: "The user contact email"

          - name: password # it is not recommended to save passwords, this is an example only
            type: string
            encrypted: true
            description: "The user system password"

          - name: plan
            type: string
            description: "The user membership plan"
            validate:
              list:
                values:
                  - GOLD
                  - SILVER
                  - BRONZE

          - name: miles
            type: integer
            description: "The accumulated flyer miles"

    relationships:
        - name: trips
          type: $rel
          ref: ".torpedo/entities/trip.yaml"
          cardinality: hasMany
          load:
            type: nested
            metadata:
                maxItems: 100

    adapters:
        input:
            - type: http

        output:
          - type: memory 

Additionally the Trip entity is required, so, let’s create a Trip entity:

.torpedo/entities/trip.yaml

version: torpedo.darksub.io/v1.0
kind: entity
spec:
    name: trip
    plural: trips
    description: "The user fly trip reservations"
    doc: |
        The trip entity handles all data related with the frequent flyer trip
    schema:
        reserved:
            id:
                type: ulid

        fields:
          - name: departure
            type: string
            description: "The trip departure airport"

          - name: arrival
            type: string
            description: "The trip arrival airport"

          - name: miles
            type: integer
            description: "The trip miles"

          - name: from
            type: date
            description: "The trip from date"

          - name: to
            type: date
            description: "The trip to date"

    adapters:
        input:
            - type: http

        output:
            - type: memory

Torpedo will generate the Go code for the User and Trip entities along with its corresponding CRUD operations, including the repository interfaces and any necessary database handling code.

4. Creating Use Cases

Once your entities are in place, it’s time to define how they’ll interact with the application’s workflows using use cases. Use cases encapsulate the business rules and processes that act upon your entities.

Create a YAML file under the .torpedo/use_cases directory to define your use case. Here’s an example of a simple use case for booking a fly:

.torpedo/use_cases/booking_fly.yaml

version: torpedo.darksub.io/v1.0
kind: useCase
spec:
    name: "BookingFly"
    description: "Fly reservation use case"
    doc: | 
        Given a frequent flyer user should be able to do a booking fly from our well known fly routes, selecting the
        departure airport and the arrival airport, also setting up the from-to fly dates. If the booking is successful, so the
        system should calculate the user awards and upgrade it.
    domain:
        entities:
            - user.yaml
            - trip.yaml

This definition tells Torpedo to create the skeleton code to put your custom logic for processing a fly reservation given a Trip and a User.

Torpedo will scaffold the complete use case, including interactions with your entities.

After complete the next step (#5) please read the quick start guide to learn about how to code your logic within the generated skeleton use case at Use Cases

5. Wiring It All Together

Once you’ve defined your entities and use cases, Torpedo ensures that the wiring between these components follows Hexagonal Architecture principles. The use cases will interact with the entities through the service interfaces, while your adapters (such as databases or APIs) handle persistence and external communication.

Now it's time to write your app specification to put all together!. The application definition is the most important file because here is described your app. The following example shows how to define the Booking Fly app:

.torpedo/app.yaml

version: torpedo.darksub.io/v1.0
kind: app
spec:
  name: "Booking Fly System"
  description: "Application example"
  stack:
    lang: go
    package: "github.com/darksubmarine/booking-fly" 
  domain:
    entities:
      - user.yaml
      - trip.yaml
    useCases:
      - booking_fly.yaml

To generate the application code (entities, use cases and more) run the command:

torpedo fire

This command will generate a project scaffold, setting up the directory structure based on the Hexagonal Architecture. The project will include core folders for entities, use cases, and adapters. It ensures that your business logic and infrastructure remain decoupled from the get-go.

You can now extend your project by adding more entities, use cases, and even custom adapters. Torpedo’s structure allows you to keep your code clean and modular, making it easy to scale your application as it grows.

Also take a look at how to code your own logic withing generated Use Case code.

6. Running Your Application

After setting up entities and use cases, you’re ready to run your application. Torpedo includes a lightweight server, based on Gin Gonic project, that you can run for testing and development. Simply use:

Don't forget to run go mod tidy before to update dependencies!

go run main.go

You can now interact with your application’s API, running the CRUD operations and use cases you’ve defined.

7. What’s Next?

Torpedo makes it easy to generate clean, structured Go code with Hexagonal Architecture. But this is just the beginning! You can continue to explore Torpedo’s features by adding more complex workflows, integrating external services, and customizing the framework to suit your needs.

Stay tuned for more advanced features coming soon to Torpedo, and feel free to share your feedback as you explore what’s possible!

---

Conclusion

Creating your first project with Torpedo is simple and fast. By leveraging the power of entity schemas and use case definitions in YAML, you can quickly scaffold a robust Golang application while maintaining clean architectural principles. Now it's time to dive in and start building! Let us know what you think and how Torpedo can help your future projects.