DEV Community: Sebastian Arrubia

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

Sebastian Arrubia — Tue, 12 Nov 2024 17:22:30 +0000

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.

Introducing Torpedo: A Golang Framework Born Out of Frustration with Messy Codebases

Sebastian Arrubia — Tue, 12 Nov 2024 17:21:40 +0000

As a developer, I've spent countless hours wrestling with tangled codebases, trying to untangle business logic from the clutter of external dependencies like databases, APIs, and frontends. The deeper I went into complex projects, the more I realized how hard it was to keep things organized and maintainable over time. That’s when I started exploring architectural patterns that could help me build applications with a cleaner, more sustainable structure.

After discovering Hexagonal Architecture (aka Ports and Adapters), everything clicked. This architecture allowed me to separate my core business logic from the outside world, making my projects far more modular, testable, and adaptable. But even with this newfound clarity, implementing the architecture in Golang wasn’t as straightforward as I had hoped. I wanted a framework that embraced this pattern from the ground up—something that would not only speed up my development process but also ensure I was sticking to the principles of clean architecture without reinventing the wheel every time.

That’s how Torpedo was born.

Torpedo is a Golang framework designed to take the headaches out of building well-structured applications. It streamlines the implementation of Hexagonal Architecture, making it easier to write clean, decoupled code that scales. In this post, I’ll share my journey of building Torpedo, explain its core features, and show how it can help you ship faster without sacrificing code quality.

One of the standout features of Torpedo is its ability to generate entity code and CRUD operations from a simple YAML file. This file allows developers to define their domain entities in a clear, concise manner, specifying attributes and relationships without getting bogged down in boilerplate code. Once the entity schema is defined, Torpedo takes over, automatically generating the corresponding Go structs, repositories, and CRUD operations (Create, Read, Update, Delete) for each entity. This eliminates the need to manually write repetitive code, speeds up development, and ensures that the generated code is aligned with the Hexagonal Architecture principles—keeping your business logic clean and independent from infrastructure concerns.

Torpedo also simplifies the creation of application logic by automatically generating use case code based on a YAML definition file. In this file, developers can define the core actions or workflows that represent their application's business logic, such as processing payments, managing user accounts, or handling orders. Once the YAML file is set up, Torpedo generates the complete use case layer, including input and output handling, request validation, and interaction with repositories or external services. By automating the generation of this essential code, Torpedo helps developers stay focused on the unique business rules of their application, while ensuring that their use cases are neatly structured and adhere to the principles of Hexagonal Architecture.

In Torpedo, the relationship between entities and use cases is foundational to maintaining a clean separation of concerns, as per the Hexagonal Architecture. Entities represent the core business objects, encapsulating business rules and attributes, while use cases define how these entities are interacted with and manipulated based on specific workflows or actions. This clear division ensures that business logic remains isolated and independent from external systems, which makes the codebase more adaptable to change. The use case layer interacts with entities to enforce business rules, while repositories (or adapters) handle data persistence without violating the entity's internal logic.

Here’s a diagram to illustrate the flow between entities and use cases within Torpedo's Hexagonal Architecture:

This approach not only keeps the code modular and scalable but also allows for easier testing by decoupling external dependencies from core business logic.

We’re just getting started with Torpedo, and there’s so much more to come! This framework was built with the aim of making Golang development faster, cleaner, and more aligned with modern architectural principles. Whether you're working on a new project or refactoring an existing one, Torpedo can help you streamline your workflow, reduce boilerplate, and keep your business logic decoupled from external concerns.

We invite you to give it a try, explore its features, and see how it fits into your development process. We’d love to hear your feedback—your insights will help shape the future of Torpedo as we continue to evolve and add more features to make it even better. Stay tuned more is coming soon, let’s build something great together!

What's next? Take a look to Creating Your First Project with Torpedo: A Step-by-Step Guide