Flamingo Commerce: bounded contexts for Go shops, wired through ports and adapters

The shop is split into bounded contexts, not one application

Flamingo Commerce describes itself as a flexible e-commerce framework on top of Flamingo, used to build commerce portals and connect them to other services through individual adapters. The unit of design is the bounded context. Each module provides a separated context with its own domain, application and interface logic, and the README lists the main ones: product, cart, search and checkout, plus price, category, payment, customer, order and a w3cdatalayer module for rendering a data layer for tracking. The design goals are stated plainly and they are architectural rather than aspirational. The framework uses domain driven design with ports and adapters to keep a maintainable application, the adapter concept and resilience concepts are meant to make connecting to other microservices easy, and the frontend is decoupled from the backend for frontend so any frontend technology can be used. The stated problem it solves is breaking up monolithic e-commerce architecture so it can scale and stay maintainable.

Ports and adapters are the seam you own

The important idea is that the domain modules do not talk to your services directly. Ports and adapters separate the domain from technical details, so each module can be used with your own adapters to interact with any API or microservice you choose. The project description puts the same point differently, calling the framework a toolkit for building commerce experiences that connects to other services with the help of individual adapters. Two consequences follow for the teams using it. First, the framework is not tied to a specific payment provider, search engine or PIM, which is what makes the microservices story real rather than nominal. Second, you write the integration code yourself, so the framework gives you domain models and interfaces, not a finished shop. A demo shop built from the standalone adapters is hosted by the project, and its GraphQL console is linked from the README, so you can see the shape of the result before committing to it.

No page cache in the design

The performance goal in the README is unusual enough to quote in spirit: the project does not want to rely on any frontend caching, and instead says it is no problem to show every customer an individual experience. That rules out a whole class of standard e-commerce architecture, where the rendered page is cached and every visitor sees the same HTML until the cache expires. The stated alternative is real time commerce, building personalised experiences without the need to cache rendered pages, and headless commerce built on modern architecture. The cost of that choice is that every request does more work, so throughput and infrastructure cost are on you rather than being hidden behind a cache. The design also mentions GraphQL support, with each module providing GraphQL support you can use, and the demo shop exposes a GraphQL console, which is the natural fit for a frontend that asks for exactly the personalised data it needs to render.

Fake adapters keep tests off the network

Testability is one of the design goals, and the mechanism is specific. The framework provides Fake Adapters that supply test data, so an application can be tested without external dependencies. In a project where the cart module talks to a payment service through an adapter and the search module talks to a search engine through another, the swap from a real adapter to a fake is what makes the test suite fast and deterministic. The repository layout backs the same idea, with a test/ directory at the top level and an integrationtest/ tree inside it, plus a Makefile target that runs those integration tests ten times with the race detector enabled. The dependency list also shows the testing stack in use, with testify, go-cmp, goleak for goroutine leak detection, httpexpect for HTTP level assertions, and testcontainers for spinning up real dependencies during tests. That last one is the boundary: unit tests use fakes, integration tests use containers.

Adding a module to a Flamingo application

The project recommends Go modules, and the setup is an import plus a module registration. To use the product module you add it to the import block of your main file:

import (
  "flamingo.me/flamingo-commerce/v3/product"
)

Then the module is loaded in the application bootstrap, where flamingo.App takes a list of dingo modules and the commerce module is registered with new(product.Module) inside that list. The import path carries the major version, flamingo.me/flamingo-commerce/v3, which matters because the go.mod of this repository declares the same module path and requires Go 1.26.0, with dependencies on flamingo.me/dingo for the module system, flamingo.me/flamingo/v3 for the framework itself, flamingo.me/graphql, flamingo.me/form and flamingo.me/pugtemplate. The README also points out that Flamingo Commerce is built on the Flamingo framework, so reading the Flamingo documentation is a prerequisite rather than an optional extra.

The API is still Beta and the minor versions move fast

The README has a section titled Release Status, and its content matters more than the version numbers. The Flamingo Commerce API is Beta because the API, meaning models and methods, will still change, and users are encouraged to use it while being warned that an update might require adjusting their code to the latest changes. The release history shows how active that churn is: v3.12.0 in February 2025, then v3.13.0 on 2026-10-06 and v3.14.0 on 2026-10-14, with the last push on 2026-10-17. Ten releases in a version line that carries a Beta label is a reasonable pace, but it means your upgrade plan is part of the architecture. The licence is MIT, and the project states that both Flamingo Commerce and Flamingo are open source and will remain so, with a CHANGELOG.md and a Renovate configuration in the tree for dependency updates.

The Makefile shows the quality gate

Development tooling is visible in the Makefile, which gives a good sense of what a contribution has to pass. The test target runs the race detector across the package, then gofmt in diff mode, then golint, misspell with an error flag, and ineffassign:

	go test -race -v ./...
	gofmt -l -e -d .
	golint ./...
	misspell -error .
	ineffassign .

The lint target is narrower than a full run, since it computes the first commit that differs from origin/master and passes that to golangci-lint as the new-from-rev boundary, so only the code you touched is linted. Integration tests are a separate target that repeats the suite ten times with the race detector and the integration build tag, and another target regenerates the GraphQL resolvers for the integration test project before running it. The repository also carries a .golangci.yml configuration and a .mockery.yaml, the latter being the generator config for test doubles, which is what makes the fake adapter approach maintainable rather than hand written boilerplate.

Editorial conclusion

Adopt Flamingo Commerce if you are building a Go commerce backend with a headless frontend, you want product, cart, search, checkout, order and payment domains rather than a monolith, and you are prepared to write the adapters that connect those domains to your own APIs. Do not adopt it if you need a stable API contract today, because the README states the Flamingo Commerce API is Beta and that upgrades may require code changes, and do not adopt it if you want a turnkey shop, since the framework hands you the domain and the ports but not the integrations. Verify first which Flamingo version your project uses, since this module imports flamingo.me/flamingo/v3, and plan the adapter boundary for payment and search before you commit to the checkout module, which ships with a default implementation you can use or replace.

Frequently asked questions

Official sources

1. i-love-flamingo/flamingo-commerce on GitHub
2. License: MIT
3. Project website
4. README
5. Releases