- An import has failed. A supplier is waiting for approval.
- Every subsystem knows about its own problem.
- That was the operational problem we faced while extending Medusa into a multi-vendor procurement platform.
- We built a Control Center inside the Medusa administration instead.
The client problem
An import has failed. A supplier is waiting for approval. A batch of new products needs review. An email attachment could not be ingested. A background workflow has stopped progressing.
Every subsystem knows about its own problem. Nobody has one reliable answer to the question that matters:
What needs our attention now?
That was the operational problem we faced while extending Medusa into a multi-vendor procurement platform. The marketplace had become capable, but each new capability created another place where work could wait or fail. Adding more emails and notifications would only make the signal harder to follow.
We built a Control Center inside the Medusa administration instead. It translates current business exceptions from across the platform into one deduplicated, stateful action queue. Each item explains what needs doing, how urgent it is and where the operator must go to resolve it. When the underlying condition disappears, the queue can close the item automatically.
The result is not another monitoring dashboard. It is an operating system for marketplace work.
The client problem was fragmented responsibility
A marketplace is not one workflow.
Suppliers apply to join. Buyers request access. Vendors submit address or delivery changes. Product imports wait for review. New catalogue items need publication decisions. Files arrive by email. Image localisation can fail. Background commerce workflows can stop.
Each process can expose its own status page. Technically, that may be sufficient. Operationally, it forces the team to patrol the product.
An administrator has to remember which screens to inspect, which filters reveal pending work and which failures are urgent. If they rely on notifications, they inherit a different problem: alerts arrive at a moment in time, but the work may remain open for hours or days.
A notification answers, “What happened?”
An operations queue must answer, “What is still unresolved, who is handling it and what should happen next?”
We designed the Control Center around that second question.
Turn domain states into work items
The platform already knew the truth about each problem.
An approval request had a pending status. A product import was awaiting review. A newly imported product had not been accepted for publication. An email-ingestion record had failed. A workflow-monitor record was actionable.
We did not ask every feature team to manually send a new generic alert. The Control Center collects these current states and translates them into a shared operational language.
Each control item contains:
- a stable identity for the underlying problem;
- the source and type of action required;
- a human-readable title and summary;
- a status and severity;
- relevant seller or organisation context;
- timestamps showing when the source appeared and was last seen;
- a route to the screen where the operator can act.
This shared shape is small on purpose. The Control Center does not duplicate every approval, import or workflow model. It projects just enough context to coordinate the work and sends the operator back to the domain screen for the actual decision.
Why stable deduplication matters
Suppose the system scans every thirty seconds and discovers the same failed import each time.
A notification-style implementation can create a new record on every scan. The operator sees ten warnings, dismisses nine and still cannot tell whether the remaining one represents a new failure.
Our collectors emit a stable deduplication key derived from the business exception: the source type and the identity of the approval, import, seller, email or workflow involved.
The same problem therefore refreshes the same control item. Its context and last-seen time can change, but its operational identity remains stable.
That gives the team one card to own, discuss and resolve.
Stable keys also make the dashboard calmer. Repeated observation means “this still exists,” not “a new incident happened.” The queue grows when new work appears, not because the polling loop ran again.
This is not a universal exactly-once guarantee across the entire marketplace. It is a deliberate identity contract for the action queue, which is the level of certainty the operator actually needs.
Preserve human ownership during background refresh
A derived queue creates another subtle risk: the next background scan can overwrite the work a person has already organised.
Imagine an operator moves an item from Todo to In Progress. Thirty seconds later, the collector sees that the source condition still exists. If the upsert blindly restores Todo, the system erases ownership.
The Control Center preserves active human states during refresh. Items already marked In Progress or Waiting remain there while their source is still open. Closed decisions such as Done or Dismissed are also not casually reopened by a routine scan.
The collector owns current source context. The operator owns the workflow state.
That division makes the queue collaborative rather than decorative. A colleague can see that somebody is working on the issue. Waiting can mean the team needs information or an external action. Done records a human completion decision.
The interface supports those states in list, grouped and Kanban views, but the important part is not drag and drop. It is that the lifecycle survives the next synchronisation.
Let disappearing problems close themselves
Not every operational item needs a person to press Done.
A supplier may complete missing onboarding information. A delayed workflow may recover. A product may leave its pending state through another legitimate path. If the source condition is no longer present, keeping the warning active creates stale work.
After collecting the current set, the Control Center compares active items with the stable keys it just observed. An active item whose source condition has disappeared becomes Auto-resolved and receives a resolution time.
Auto-resolved has a precise meaning: the platform no longer detects the condition that created the item.
It does not claim that a person consciously fixed the issue, nor that every downstream consequence has been audited. That is why it is distinct from Done.
This distinction keeps the queue credible. Operators can trust that active means currently actionable, while history still explains what the platform previously observed.
Severity should help, not pretend to be intelligence
The system classifies items as informational, warning or urgent.
That is intentionally simpler than a mysterious risk score. A pending supplier request may deserve immediate commercial attention. A product import awaiting review is important but different. A failed background process can be urgent when it blocks a critical operation.
Severity is defined by the domain collector that understands the condition. The queue exposes counts for active work, workflow states and urgent or warning items. Operators can filter by severity, source and status.
Chronology still matters, so source creation time and current record time remain visible. Search can use titles, summaries and metadata when the team is looking for a company, person or event.
The goal is not to automate every priority decision. It is to give the team enough structure to see the difference between routine review and something that deserves immediate investigation.
Every item must lead to action
Many observability products stop at description.
They report that an operation failed, then leave the user to navigate through the application and reconstruct the context. That is useful for engineers, but weak for marketplace operations.
Each Control Center item carries a route to the relevant administrative screen. A pending buyer registration opens the approval queue. A catalogue publication request opens the correct review view. A failed import leads to import operations. A failed workflow leads toward its execution context.
The Control Center coordinates; the domain screen resolves.
This prevents the central queue from becoming a second, incomplete administration interface. Approval details still belong to approvals. Import correction still belongs to imports. The queue simply removes the discovery cost.
For an operator, the experience becomes: see the problem, understand its context, open the right screen and act.
Combine business work and technical failures carefully
The queue brings together two categories that products often keep apart.
Some items are expected business work: approve a supplier, review a product import or decide whether new products can be published. Others are exceptions: an email failed to ingest, image localisation failed or a workflow reached an actionable failure state.
Both categories require operational attention, but they should not be presented as identical errors.
Source type, action type, severity and wording preserve the distinction. The dashboard can group and filter by source. A seller onboarding task remains a commercial decision; a failed workflow remains a system exception.
This creates one front door without flattening the meaning of the work behind it.
It also makes gaps visible. When the team adds a new marketplace capability, they can ask a concrete question: which states from this feature require an operator, and how will they enter and leave the Control Center?
Operability becomes part of feature design rather than a page added after launch.
Why Medusa was the right foundation
Medusa provides the commerce engine and a modular application framework. We extended it with marketplace onboarding, supplier operations, catalogue ingestion, publication workflows and background processing.
The Control Center is another extension of the same principle.
It does not replace the modules that own those workflows. It resolves their current actionable states through the Medusa container, stores a small operational projection and exposes it inside the administration product.
That architecture lets a marketplace grow beyond standard e-commerce screens without giving up a coherent operating experience.
Choosing Medusa was not only a choice about checkout APIs. It was a choice to use a commerce foundation we could extend around the client's real organisation. When new business processes appeared, we could model them properly and then add the control plane required to run them.
The platform becomes more capable and more operable at the same time.
The interface follows the operating model
The administrative page offers several views over the same queue.
Date view helps answer what appeared recently. Status grouping shows Todo, In Progress, Waiting and closed work. Kanban supports the team when ownership and progression matter more than chronology.
Summary cards expose active, Todo, In Progress, Waiting and Done counts. Filters narrow the queue by status or source. Search helps locate a company, person or event. Background refresh keeps current conditions visible without continuously polling while the page is inactive.
These interface choices are useful because the data model already expresses an operational lifecycle. A Kanban board over raw logs would still be raw logs. A status view over duplicate notifications would still be noise.
The UI is the final expression of the architecture: one problem, one durable item, one current state and one path to action.
What this changed for the client
As the marketplace expanded, the operating team no longer had to understand the internal architecture merely to find pending work.
Approvals, supplier requests, catalogue review, email ingestion and actionable process failures could enter one vocabulary. The team could distinguish new work from work already owned, wait without losing context, dismiss irrelevant items and let vanished conditions close automatically.
The Control Center also made new feature conversations better. A feature was not complete simply because its happy path worked. We could ask how its exceptions become visible, how duplicates are prevented, where the operator resolves them and what proves that the condition has disappeared.
That is a different standard from adding notifications after the fact.
It treats marketplace operations as part of the product.
A practical design checklist
Before building a central operations queue, answer these questions:
- Which current business states genuinely require human attention?
- What stable key identifies one underlying exception across repeated scans?
- Which context belongs in the queue, and which belongs on the domain screen?
- What do Todo, In Progress, Waiting, Done, Dismissed and Auto-resolved mean?
- Can background refresh preserve human ownership states?
- What source condition proves an active item has disappeared?
- Is severity explicit and understandable rather than an unexplained score?
- Does every item link directly to a place where somebody can act?
- Can expected business review and technical failure share a queue without losing their meaning?
- How will a new feature declare its actionable and resolution states?
If those answers are missing, a central dashboard will aggregate noise. If they are explicit, it can coordinate the business.
The broader lesson
The client did not need another stream of alerts.
They needed a marketplace operator to open one screen and understand what still required attention across a growing Medusa platform.
We solved that by projecting domain truth into durable work. Collectors find current exceptions. Stable keys prevent duplication. Workflow states preserve ownership. Missing conditions auto-resolve. Severity and source help prioritise. Direct routes take the operator to the real resolution screen.
Logs explain software. Notifications announce events. A Control Center helps a team run the marketplace.