DEV Community: Marabesi

[Boost]

Marabesi — Mon, 16 Feb 2026 05:19:34 +0000

Marabesi

Jan 18

Hexagonal architecture - Another way to the hexagone

#programming #webdev #architecture #opensource

Comments

7 min read

Five Years of json-tool and 3,000 Active Users Later

Marabesi — Tue, 03 Feb 2026 19:54:19 +0000

Five years ago, I started working on json-tool out of necessity. I needed aJSON formatting tool I could trust with sensitive data: one that wouldn't send my information to third-party servers filled with ads and tracking scripts. What began as a personal weekend project has quietly grown into something used by 3,000 active users. This milestone made me pause and reflect on what this journey has taught me about building and maintaining open source software.

3k users?: The number of weekly active users are fetched from the snapcraft channel distribution. The 3k comes from there, however,
I would think this number is higher if adding taking into account the web version. I am
unable to know that as there are no trackers.

Privacy First

In 2021, my workflow involved frequent JSON manipulation: debugging API responses, integrating with third-party services, and inspecting data structures. Like many developers, I defaulted to googling "JSON prettier" and using whatever website appeared first. Tools like JSON Formatter and JSON Pretty Print worked fine, but they came with a cost: ads everywhere, no transparency about data handling, and zero guarantee that my JSON strings weren't being logged somewhere.

For personal projects, this was mildly annoying. For work involving production data or sensitive information, it felt irresponsible. ThoughtWorks Tech Radar volume 27 later highlighted this exact concern, warning developers about formatting tools that don't comply with data jurisdiction requirements.

I wanted something different: a tool that collected no data, showed no ads, and remained transparent through open source code. No complex feature set, just reliable JSON formatting that respected user privacy. That's how json-tool was born.

The initial implementation was straightforward: an Electron app built with React, published to snapcraft.io. I applied outside-in TDD using Cypress and React Testing Library (a practice I've written about to ensure the core functionality worked reliably from the start.

When Users Broke Things

The first version worked well for typical use cases. Developers could paste JSON from logs, validate it, format it with custom spacing, and copy the result back to their clipboard. The privacy-first approach meant enterprise developers working with sensitive data could use it without corporate firewall concerns, and most importantly it runs offline once installed via Snapcraft.

Then reality hit: users started pasting JSON strings larger than 1MB.

The application froze. Completely. The user interface became unresponsive, buttons stopped working, and the whole experience fell apart. Through benchmarking with console.time() and console.timeEnd(), I traced the bottleneck to the JSON parsing and formatting happening on the main thread. JavaScript's single-threaded nature, combined with the event loop execution model, meant any blocking operation would freeze the entire UI.

This is where web workers entered the picture.

Moving to Web Workers

According to Ido Green's book "Web Workers: Multithreaded Programs in JavaScript", if your web application needs to complete a task that takes more than 150 milliseconds, you should consider using web workers. Green specifically lists "encoding/decoding a large string" as a primary use case, this is what json-tool was doing.

The architecture shift was significant. What was previously synchronous code:

const onJsonChange = useCallback(async (value: string) => {
  setError('');
  if (!spacing) return;

  try {
    if (value) {
      JSON.parse(value);
    }
  } catch (e: any) {
    setError('invalid json');
  }

  let format = new Formatter(value, 2);
  const parseSpacing = parseInt(spacing);
  if (!isNaN(parseSpacing)) {
    format = new Formatter(value, parseSpacing);
  }

  const result = await format.format();
  setOriginalResult(value);
  setResult(result);
}, [spacing]);

Became an event-driven system where the main thread delegates heavy computation to a dedicated worker:

const onChange = (eventValue: string, eventSpacing: string) => {
  if (worker.current) {
    worker.current.postMessage({ 
      jsonAsString: eventValue, 
      spacing: eventSpacing 
    });
  }
  setOriginalResult(eventValue);
  setInProgress(true);
};

The worker itself handles the actual parsing and formatting:

importScripts('https://unpkg.com/format-to-json@2.1.2/fmt2json.min.js');

if('function' === typeof importScripts) {
  addEventListener('message', async (event) => {
    const value = event.data.jsonAsString;
    const spacing = event.data.spacing;

    if (value) {
      const format = await fmt2json(value, {
        expand: true,
        escape: false,
        indent: parseInt(spacing)
      });

      try {
        JSON.parse(value);
      } catch (e) {
        postMessage({ 
          error: true, 
          originalJson: value, 
          result: format.result 
        });
        return;
      }

      postMessage({ 
        error: false, 
        originalJson: value, 
        result: format.result 
      });
    }
  });
}

Did this improve performance? No. The actual computation time remained the same. But the user experience was transformed.
Developers could continue interacting with the application while JSON processing happened in the background. I documented this technical journey in detail in Web Workers to the Rescue, where I explored the architecture changes and performance implications.

Web Workers and TDD

One of my non-negotiables for json-tool was maintaining TDD discipline. I had written about using outside-in TDD from the beginning, and I wasn't going to compromise on that.

Web workers introduced testing complexity I hadn't anticipated. The Worker object exists in the browser under the window scope, but in Jest's jsdom environment, it's undefined. My test suite broke immediately after introducing workers.

The solution came from Jason Miller's jsdom-worker library, which provides a Worker API implementation for jsdom. It doesn't create actual threads, it mocks the behavior. The setup required two steps:

Install: npm i jsdom-worker
Import in setupTests.ts: import 'jsdom-worker'

The library had limitations, it doesn't support shared workers, and it required using the Blob pattern instead of separate
script files. But it allowed me to maintain my existing tests without coupling them to implementation details:

it('should format json from uploaded file', async () => {
  const file = new File(
    ['{"a":"b"}'], 
    'hello.json', 
    { type: 'application/json' }
  );

  const { getByTestId } = render(<App />);

  await act(async () => {
    await userEvent.upload(getByTestId('upload-json'), file);
  });

  await waitFor(() => {
    expect(getByTestId('raw-result')).toHaveValue(`{
  "a": "b"
}`);
  })
});

The test describes behavior, not implementation. It doesn't care whether a web worker handles the formatting or not, it just verifies that uploaded JSON gets formatted correctly. This became a valuable lesson: web workers are implementation details. Tests should focus on user-facing behavior.

I later explored this testing approach further during a live coding session with web workers, where we applied TDD in a coding dojo setting and demonstrated that you can refactor synchronous code to use workers while maintaining test coverage.

Challenges and Learnings

Performance vs. Simplicity

The web worker implementation solved the UI freezing problem but introduced complexity. The codebase went from straightforward synchronous code to an event-driven architecture. New contributors would need to understand worker lifecycle management, message passing, and the implications of moving code off the main thread.

I balanced this by keeping the worker implementation isolated. The rest of the application remains simple: React components, straightforward state management, minimal abstractions. The complexity is contained, documented, and necessary for the user experience.

Maintenance Reality

Open source maintenance is time-consuming. Dependencies need updates. Security vulnerabilities require patches. Browser APIs change. Testing libraries evolve.

For json-tool, I aimed for sustainability over rapid development. The tech stack (React, TypeScript, Tailwind, CodeMirror) consists of stable, well-maintained projects with large communities. I avoid cutting-edge dependencies that might break or get abandoned.

Updates happen in batches, typically when I'm actively using the tool and notice something that needs improvement. This isn't a business with support SLAs, it's a community tool maintained alongside other responsibilities.

The Open Source Philosophy

Building json-tool taught me what open source means beyond "putting code on GitHub":

Transparency builds trust. Users can audit the entire codebase. They can verify no tracking happens, no data gets sent anywhere, no ads get injected. Trust isn't demanded, it's proven through openness.
Focused tools solve problems better. Json-tool doesn't try to be everything to everyone. It does one thing well: formats JSON with privacy guarantees. This focus makes it maintainable and useful.

Test-driven development pays long-term dividends. The initial TDD investment enabled the web worker refactoring without breaking existing functionality. Tests served as a safety net, allowing confident changes years after initial development.

Looking Forward

Json-tool will continue as it is: a focused, privacy-first tool for developers who need trustworthy JSON formatting. I have no plans to monetize it, add analytics, or transform it into something bigger. The value lies in its simplicity and reliability. However, sponsorships are welcome via GitHub Sponsors.

Future improvements will likely focus on:

Performance optimization for extremely large JSON files (>100MB)
Better accessibility (screen reader support, keyboard navigation improvements)
Editor synchronization so both scroll simultaneously

Nothing revolutionary. Just steady improvements that serve the existing user base better. For example, update with the latest version of CodeMirror to benefit from performance and accessibility enhancements, ReactJs updates, and TypeScript improvements.

The most rewarding part of this journey wasn't reaching 3,000 users, it was building something that solves a real problem without compromising on principles. No tracking. No ads. No data collection. Just a tool that does what it promises and respects its users.

The source code for json-tool remains available at github.com/marabesi/json-tool. The tool itself is available at marabesi.github.io/json-tool. It's been five years. Here's to many more of building software that respects privacy and serves developers well.

[Boost]

Marabesi — Sat, 24 Jan 2026 20:38:57 +0000

Marabesi

Jan 18

Hexagonal architecture - Another way to the hexagone

#programming #webdev #architecture #opensource

Comments

7 min read

[Boost]

Marabesi — Sun, 18 Jan 2026 11:46:24 +0000

Testing ReactJS Context - A Guide with test-doubles

Marabesi ・ Dec 3 '24

#react #webdev #javascript #mock

Hexagonal architecture - Another way to the hexagone

Marabesi — Sun, 18 Jan 2026 11:45:52 +0000

Theory

Hexagonal Architecture, also known as the Ports and Adapters pattern, offers a powerful way to design software systems that are modular, testable, and adaptable to change. This architectural style emphasizes the separation of concerns, ensuring that core business logic remains independent of external systems such as databases, user interfaces, or third-party services.

In this blog post, we’ll explore Hexagonal Architecture in two parts. The first part dives into the theory, explaining its principles, benefits, and how it contrasts with traditional layered architectures. The second part brings these concepts to life with a real-world implementation based on my interpretation of Hexagonal Architecture, demonstrating how to structure code for flexibility and maintainability.

Hexagonal

I got to know hex architecture (I am going to follow this pattern from now on to refer to the hexagonal architecture) in the clean architecture book, indeed it was inspired by Uncle Bob to get the clean architecture in place. Alistair Cockburn realized that there was a different approach to building applications instead of the classical layered architecture:

The attempted solution, repeated in many organizations, is to create a new layer in the architecture, with the promise that this time, really and truly no business logic will be put into the new layer.

A more flexible way of dealing with different adapters in the application and using the same code to process business rules. Even though experts argue that there are differences between open and closed layers, to avoid such interactions or constraint violations, in the hex architecture the approach is different stating that the goal is to avoid it by design instead of trying to enforce a constraint. Nevertheless, Stenber in his blog written for infoQ says that hexagonal architecture is an example of a layered architecture as it conforms to all the constraints and properties of a layered architecture.

Hexagonal vs Clean Architecture?

Hexagonal architecture is usually mixed with clean architecture, even though, it was used as an inspiration for the clean architecture, they are different. Valentina Cupác
describes that in her talk with details.

In my observations throughout code bases, both are often mixed together. However, Clean Architecture is more prescriptive than Hexagonal Architecture. For example, Juan Manuel Garrido de Paz
describes that "Ports & Adapters pattern says nothing about the structure of the inside of the hexagon." Ports & Adapters is another way to name the same architectural style.

Which goes against the opinion from Juan Manuel, who says that the "pattern" says nothing about layers. However, what I see lacking in his argument is: what is a layer anyway? Such an abstract definition as an architectural style may be interpreted differently by different people, which leads to those different opinions. The naming "layer" might be too abstract, leading to confusion when communicating the same idea.

Another way to the hexagone

Alistair in the "hexagone" - YouTube playlist DDD - FR elaborates on his insights when developing and formalizing the architectural style that is widely known today by developers. For curious people, this is a video that explains the why's behind the naming, the decision and the need from Alistair to create the style.

Definition

Let's start with the diagram from the architectural style creator Alistair Cockburn that has this image in his blog post:

Hexagonal architecture is defined in different aspects. These aspects are something that was created to define this architectural style, and I believe they are the key:

ports, as the author describes "The term “port and adapters” picks up the ‘’purposes’’ of the parts of the drawing. A port identifies a purposeful conversation".
adapters, you might have many adapters for a single port.

In the book Strategic Monoliths and Microservices
Vaughn Vernon and Tomasz Jaskula also used a similar definition, on the other hand, what caught my attention to their definition is the way used to differentiate the layered architecture from hexagonal.

Ports and Adapters are the one of the aspects of this architectural style that deserves attention. A driver adapter implements a driver port interface, translating requests from a specific technology into a technology-agnostic format that the driver port can understand and process.

Paz uses the naming "Driver" to refer to the interface that will control how to interact with the application and "Driven" to refer to the interface that will act as an output boundary.

A note on the implementation In my implementation that is referenced later in this post, I used the naming "inbound" and "outbound" to refer to the interfaces that are used to interact with the application. The inbound is the interface that is used to interact with the application, while the outbound is the interface that is used to interact with the external systems: - inbound: Driver - outbound: Driven

In that sense, the driver can be a CLI, a GUI, or even a REST API, while the driven can be a database, a message broker, or any external system that the application interacts with.

What are the disadvantages of hexagonal architecture?

At first, the hexagonal architecture seems to be a magical approach that will automagically give testability to any application, at least this is what some of the articles on the web sells the hexagonal architecture. Nevertheless, some of the implications that come when adopting hexagonal architecture are:

The developer experience: as the implementation of hexagonal architecture depends on interpretation, it varies based on the programming language and the years of experience of the developer writing the code. Hexagonal architecture usually is not the first style that one starts with. It is MVC that comes embedded in different frameworks.
The understanding of the developer on the libraries and the frameworks being used: the different ecosystems of different programming languages bring challenges as they offer a pre-created structure of how the problem should be solved. Understanding each piece of them is key to creating abstraction to create the inside and the outside of the hexagon. For example, Davi Vieira shared his opinions on implementing hexagonal architecture with Java in the book "Designing Hexagonal Architecture with Java".
Other architectural styles are also testable: other styles are posed as "not testable" or that are difficult to test, regardless, frameworks are set to use the famous Model-View-Controller.

Being said that, the shift to using hex architecture is mostly due to the developer experience at hand. With experience, the other points mentioned will have less impact.

Related subjects

References

Stenber, J. (2014). Exploring the Hexagonal Architecture. https://www.infoq.com/news/2014/10/exploring-hexagonal-architecture

Vaughn Vernon, T. J. (2021). Strategic Monoliths and Microservices. The Addison-Wesley Signature Series.

Vieira, D. (2021). Designing Hexagonal Architecture with Java: An architect’s guide to building maintainable and change-tolerant applications with Java and Quarkus. Packt Publishing.

Hexagonal in practice

Let's dive into the implementation of this architectural style to translate the theory into concrete implementation. We will
do that through a fictitious application that is used for scheduling posts on social media.

Problem statement

Given the number of people who are generating content for social media and making it a business is increasing, the need for automated tools to support the day-to-day work of those people also increases. Creating, scheduling, and sending content to those platforms are some of the focuses of social publisher.

Social publisher

To depict what I have implemented thinking about hexagonal architecture we will use this made up business that aims at posting
content into social media, currently the application is used through the Command Line Interface and it was built using kotlin. Let's dive into the features:

Create posts and focus on the content
Delete posts
Schedule posts to be sent based on a date and time
Send posts to social media (X.com is supported for the time being)

The source code for social publisher is available on GitHub.

Structure overview

The packages of the application were split into application and adapters. The aim was to be strict with the naming from the image and explanation from Alistair in his interpretation of the architecture. The application has all the business logic needed to fulfill the requirements of scheduling and posting. The adapters, on the other hand, were split into two: the inbound and the outbound. The idea is as follows:

Inbound are the adapters that offer input to the application. In this case, it is only the CLI. Outbound represents
the output that the application writes to. In this case, the CLI as well as storing the data in CSV.

src/main/kotlin/
├── Main.kt
├── adapters
│   ├── inbound
│   │   └── cli
│   │       ├── CliFactory.kt
│   │       ├── Configuration.kt
│   │       ├── Post.kt
│   │       ├── Poster.kt
│   │       └── scheduler
│   │           ├── Scheduler.kt
│   │           ├── SchedulerCreate.kt
│   │           ├── SchedulerDelete.kt
│   │           └── SchedulerList.kt
│   └── outbound
│       ├── cli
│       │   └── CliOutput.kt
│       ├── csv
│       │   ├── FileSystemConfigurationRepository.kt
│       │   ├── FileSystemPostRepository.kt
│       │   └── FileSystemSchedulerRepository.kt
│       ├── inmemory
│       │   ├── ConfigurationInMemoryRepository.kt
│       │   ├── InMemoryPostRepository.kt
│       │   └── InMemorySchedulerRepository.kt
│       └── social
│           ├── CouldNotCreateTweetException.kt
│           ├── CreateTweet.kt
│           ├── DeleteTweet.kt
│           └── TwitterCredentialsValidator.kt
└── application
    ├── Messages.kt
    ├── Output.kt
    ├── configuration
    │   ├── ConfigurationGivenHasInvalidProperty.kt
    │   ├── Create.kt
    │   └── List.kt
    ├── entities
    │   ├── ScheduledItem.kt
    │   ├── SocialConfiguration.kt
    │   └── SocialPosts.kt
    ├── persistence
    │   ├── PostsRepository.kt
    │   ├── SchedulerRepository.kt
    │   └── configuration
    │       ├── ConfigurationRepository.kt
    │       └── MissingConfiguration.kt
    ├── post
    │   ├── Create.kt
    │   └── List.kt
    ├── poster
    │   └── Executor.kt
    ├── scheduler
    │   ├── Create.kt
    │   ├── List.kt
    │   ├── SocialMedia.kt
    │   └── filters
    │       ├── Criterion.kt
    │       ├── DateTimeValidation.kt
    │       ├── StartDate.kt
    │       └── UntilDate.kt
    └── socialnetwork
        ├── CreateTweet.kt
        ├── DeleteTweet.kt
        ├── MissingConfigurationSetup.kt
        └── SocialThirdParty.kt

As previously mentioned, the structure of the application focuses only on representing the architectural style to communicate
with maintainers how the code should be structured.

Testing approach

Given an already defined architectural style, the testing strategy also has already structured boundaries to be followed. In this structure, the application is tested based on the boundaries defined at the architectural layer.

For example, adapters are tested in isolation, which helps with testability of edge cases and granular complexity. The inbound,
which is used here, is tested through a CLI application. The outbound adapters, defined as the adapters that talk with the external world, are also tested in isolation. The last layer is the e2e testing that is done using the defined adapters in the configuration. Later on, I found that Nat Pryce depicts this in detail.