DEV Community: Tiago Ribeiro Navarro de Andrade

The Database Is a Detail. The Data Is Not.

Tiago Ribeiro Navarro de Andrade — Wed, 30 Sep 2026 19:44:04 +0000

Clean Architecture was right to push the database to the edge. The mistake was pushing everything the product needs to know about itself along with it.

The diagram filled the entire screen. It showed the new order flow: creation, payment, inventory, cancellation, and refund, each handled by its own service. Queues were named, retries configured, there was a circuit breaker between payment and inventory, and even the authentication flow had been drawn arrow by arrow. It was good work.

In the bottom-right corner, there was a gray box, smaller than the others, labeled "Analytics." A dotted arrow pointed to it.

Nobody mentioned it during the presentation.

Nobody asked, for example, how the business would know why orders were being cancelled. The cancellation service changed the order status to CANCELLED and moved on. The reason lived in a log, if it was recorded at all.

A reconstruction of the scene: everything was detailed except the box where the business would eventually discover why orders were being cancelled.

I have seen this scene two or three times, across different teams, working with very good software engineers. And as a data engineer, it bothers me for a specific reason.

That gray box is where the product finds out whether it is actually working.

It is where conversion metrics come from. It is where the risk model gets its inputs and where the regulatory report gets its numbers. Increasingly, it is also where an AI agent gets the context it needs to make a decision.

The question behind this article is simple: if data is so central to the product, why does it appear as a footnote in the architecture?

What Uncle Bob Said, and Why He Was Right

In Clean Architecture, Robert C. Martin dedicates an entire chapter to a provocative statement: "The Database Is a Detail."

The argument is solid.

Business rules, the entities and use cases at the center of the circles, should not know whether their data lives in Oracle, MySQL, or a file. The database belongs in the outermost ring, alongside frameworks, drivers, and the web interface.

Dependencies always point inward: the database knows about the domain, but the domain does not know about the database.

I agree with this completely.

An architectural decision should not be held hostage by the choice between Postgres and DynamoDB. Anyone who has migrated a system tightly coupled to an ORM knows the cost of ignoring that advice.

But there is a detail in that chapter that is easy to overlook.

Martin distinguishes between two things: the data model, which he considers architecturally significant, and the technology used to store and retrieve that data, which is the detail.

The database is a detail.

The structure of the information is not.

In the order flow from the beginning of this article, the distinction is easy to see. Storing a cancellation in a Postgres table or a MongoDB document is a detail. But the rule that a cancellation has a reason, a refunded amount, and a timestamp, and that this fact matters to the business, belongs to the model.

That was exactly the part missing from the diagram.

The problem starts when this distinction gets lost in practice.

Where the Interpretation Goes Wrong

In practice, "the database is a detail" has often turned into "data is a detail."

They sound similar, but they are not.

The transactional database is where the system stores its state so it can operate. But the product needs to know much more about its own data than its current state:

what happened, not just what the current state is. The order was cancelled, but when, by whom, and after how many attempts?
reliable history for auditing, regulation, and learning;
whether a feature actually produced the expected outcome;
the information required by models, recommendation systems, and now agents that make decisions autonomously based on that context.

None of these are infrastructure details. They are business requirements.

The decision that a "payment declined" event needs to include the reason for the decline does not belong to the DBA or the data team. It comes from the business rules.

When architecture pushes all of this into the frameworks & drivers ring, something predictable happens.

The use case does not produce the information the business actually needs.

So someone comes along later and tries to reconstruct it from the final state of the transactional database.

That is how we end up with pipelines reverse-engineering application tables, updated_at columns being treated as sources of truth, and dashboards that "sometimes don't match."

The gray box in the corner is not small because its job is simple.

It is small because its work was postponed.

And postponing it makes it more expensive.

Data Engineering Has Already Become Software Engineering

Part of the problem is perception.

Many software engineers still picture data engineering as it existed fifteen years ago.

In 2004, Google published the MapReduce paper. Hadoop followed, with HDFS and batch jobs running overnight. Back then, "data" really was a separate world: scripts, nightly loads, specialized tools, and a separate team receiving a production database dump and figuring out what to do with it.

That world has changed.

Modern data engineering uses version control, automated testing, CI/CD, infrastructure as code, schema contracts, observability, and real-time streaming. Tools like dbt brought pull requests and code reviews into data transformation workflows. Kafka, created at LinkedIn and open-sourced in 2011, became a common component in microservice architectures.

And here is the irony: software engineers already use data engineering practices every day.

Topics, queues, events, event sourcing, CDC (change data capture, capturing database changes as a stream of events), and the outbox pattern are part of the same vocabulary.

The boundary between the two disciplines has almost disappeared in the code.

But it is still there in the diagram.

With AI agents, that boundary becomes even harder to defend.

An agent making decisions based on customer history depends on the quality, semantics, and freshness of that data. If the data is bad, the agent does not simply become "less accurate."

It starts making the wrong decisions autonomously and at scale.

So Should the Database Move to the Center?

No.

This is important because it is the easy, and wrong, conclusion.

Moving the database, or the data platform, to the center of the circles would repeat exactly the mistake Uncle Bob was trying to prevent: coupling business rules to technology.

No use case should know whether an event is going to Kafka, Pub/Sub, or a bucket.

Something else needs to move to the center: data requirements.

My proposal is to treat as part of the domain what is usually left implicit today:

Domain events as use case outputs. "Order cancelled" is a business fact, with meaning and fields defined by the business. It should be modeled alongside the entity, not discovered later by comparing database snapshots.
Data contracts as interfaces. The schema of what a service exposes to the analytical world is a public API. It deserves versioning, review, and compatibility guarantees just like any endpoint.
Ports for publishing, adapters at the edge. The use case declares "I need to publish this fact" through an interface, a port in hexagonal architecture terminology. The technology implementing that interface remains a detail.

In other words, the dependency rule still holds.

What changes is that information is intentionally produced by the center instead of being hastily extracted from the edge.

Data requirements, shown in orange, originate at the center. Technology, shown in gray, remains at the edge, and dependencies still point inward.

What This Looks Like in Code

A minimal example makes the idea more concrete.

Below is a use case for cancelling an order. Notice that it knows nothing about Kafka, databases, or warehouses.

But as a business rule, it does know that a cancellation is a fact that must be published, and it knows which information that fact contains.

from dataclasses import dataclass
from datetime import datetime
from typing import Protocol


@dataclass(frozen=True)
class OrderCancelled:
    order_id: str
    customer_id: str
    reason: str             # defined by the business, not the data team
    refunded_amount: int    # in cents
    cancelled_at: datetime


class EventPublisher(Protocol):
    def publish(self, event: OrderCancelled) -> None: ...

The event and the port live at the center.

The use case simply brings them together:

class CancelOrder:
    def __init__(self, orders, events: EventPublisher):
        self.orders = orders
        self.events = events

    def execute(self, order_id: str, reason: str) -> None:
        order = self.orders.get(order_id)
        order.cancel(reason)
        self.orders.save(order)

        self.events.publish(OrderCancelled(
            order_id=order.id,
            customer_id=order.customer_id,
            reason=reason,
            refunded_amount=order.amount_paid,
            cancelled_at=datetime.now(),
        ))

Three things are worth noticing.

OrderCancelled is a domain structure, with a name and fields that anyone working on the product can understand.

The use case depends only on the EventPublisher interface, not on any specific technology.

And the concrete implementation, perhaps a transactional outbox that eventually publishes to Kafka, lives in the outer ring, exactly where it belongs.

The difference from the common scenario is that nobody needs to come along months later and figure out how to infer the cancellation reason from an overwritten status column.

The use case decides what to publish. Outbox, Kafka, and consumers can change without touching the domain.

What Changes in the Architecture Diagram

If I could ask for one change in architecture reviews, it would be this:

The gray box stops being a box and becomes a set of questions.

Before approving the design, the team should answer:

What business facts does this solution produce, and who needs them?
What is the contract for those facts, including fields, meaning, and version, and who owns it?
How will we use data to determine whether this feature actually worked?
What history do we need to preserve for auditing, regulation, or models?
If an agent or model consumes this data, what happens when the data is wrong or delayed?

None of these questions requires choosing a technology.

They require business decisions.

That is why they belong at the center of the conversation, not in a footnote.

Where I Might Be Wrong

Not every system needs this.

An internal CRUD application with ten users does not need versioned event contracts. Requiring them would just create bureaucracy.

There is also a real risk of polluting the domain with analytical requirements that change every week. If every dashboard request turns into a new field on an entity, the solution becomes another problem.

The filter I use is simple:

Would this fact still make sense to the business if no dashboard existed?

"Order cancelled because the item was out of stock" passes the test.

"Helper column for the quarterly report" does not.

There is also an organizational argument I respect. In many companies, the boundary in the architecture diagram reflects the boundary between teams. Changing the diagram without changing ownership does not solve anything.

Approaches such as data mesh and "data as a product" are, in part, attempts to address exactly this problem.

Data Is Not a Detail

Uncle Bob was right about the database.

Oracle, MySQL, and Kafka are details, and the architecture should remain independent of them.

But the data a product generates about itself is not a detail.

It is how the business knows what happened, proves what it did, and decides what to do next, increasingly without a human in the loop.

If you design software architecture, try three things in your next proposal:

model domain events alongside entities, as explicit outputs of use cases;
treat event schemas as public contracts, with ownership and versioning;
bring someone from data into the architecture review before the final design, not after the first broken dashboard.

The gray box in the corner was never small.

It was just drawn in the wrong place.

If you have experienced the scene from the beginning of this article, from either side of the table, share it in the comments. I would like to hear how other teams have approached this problem.

Redes Sociais — 2ª verdade dolorosa

Tiago Ribeiro Navarro de Andrade — Wed, 10 Aug 2022 17:39:52 +0000

Ontem me peguei contemplando as maravilhas dos avanços tecnológicos que mudaram a minha rotina, e o modo como se deu essa mudança. Fiz o pedido do meu almoço pelo iFood, e me dei conta, que o aplicativo não permitia eu acompanhar o deslocamento da refeição até minha casa (e o pedido demorou mais de 01 hora pra chegar), fiquei um pouco irritado com o fato, e como a aplicação não me dava a possibilidade de acompanhar o que estava acontecendo. Daí pude refletir na 2ª verdade dolorosa das redes sociais.

Por definição rede social é:

Uma estrutura social composta por pessoas ou organizações, conectadas por um ou vários tipos de relações, que compartilham valores e objetivos comuns.

E na definição de estrutura social temos que:

Refere-se à colocação e à posição de indivíduos e de grupos dentro de um sistema, partindo-se da constatação de que os membros e os grupos de uma sociedade são unidos por um sistema de relações de obrigação, isto é, por uma série de direitos e deveres, aceitos e praticados entre si.

Diante disso podemos compreender as redes sociais como sistemas de informação. A proliferação de aplicativos como Uber, iFood, e qualquer outro que mudou nossas relações com as empresas de serviço, no fundo, veem funcionando como sistemas de informações.

Os Sistemas de Informações são modelos, automatizados ou manuais, de processos responsáveis por coletar e transmitir dados que sejam úteis ao desenvolvimento de produtos ou serviços das empresas, organizações e de demais projetos. Portanto essas aplicações expandiram suas fronteiras, e/ou aproximaram os clientes de seus processos de descoberta de conhecimento.

Aproximadamente há 10 anos atrás tínhamos a predominância dos sistemas para desktop, e as técnicas de marketing ainda eram voltadas para as pesquisas de perfis de cliente. Vimos chegar até nós Orkut, Facebook e as demais redes sociais, e com eles a possibilidade de exploração dos perfis de usuários.

É por esse motivo que a cada dia mais empresas se valem do fenômeno da Uberização. Notaram que pode-se valer da coleta de dados dos clientes de forma consentida, e mais aproximada da necessidade do cliente, de suas preferencias e até obter feedbacks menos enviesados, pois virá de livre e espontânea vontade, não de respostas dadas pra se livrar do formulário de satisfação. Através do aplicativo também há a possibilidade de se mapear as preferencias por áreas, os fluxos sazonais. Uma grande concentração de informações valiosas para a saúde financeira das empresas.

As redes sociais tem aproximado e alienado as sociedades, muitos terão essa opinião, mas, vale a pena ter em mente que, as empresas privadas visão o lucro, e por esse motivo, sempre se reinventarão e buscaram encontrar métodos e técnicas que possibilitem ampliar sua produção e escoamento de suas produções materiais e imateriais, e por conta disso, irão sempre necessitar da participação do ser humano. O que nos aproxima ou distancia é a nossa incapacidade de lidar com as abstrações da realidade, o nosso desejo de encontrar significados em instrumentos que tornem nossa vivencia menos dolorosa.

Os sistemas de descoberta de conhecimento sempre existiram. O nosso desejo de compreender o que nos rodeia sempre existirá. Caberá sempre a todos nós estarmos a par com os avanços que o futuro nos trará.

Redes Sociais — 1ª verdade dolorosa

Tiago Ribeiro Navarro de Andrade — Wed, 10 Aug 2022 17:38:00 +0000

No inicio dos anos 2000 fomos surpreendidos por uma significativa mudança na nossa relação com o universo tecnológico — o Second Life. Para quem não se lembra ou não fez questão de conhece-lo na época, se trata de um jogo que prometia virtualizar a nossa realidade num ambiente gráfico tridimensional contento aspectos que simularia nossas vidas real e social.

O jogo alcançou seu auge lá por volta do ano de 2007, após 4 anos do seu lançamento, chamando a atenção da mídia internacional pela quantidade de participantes, porem, depois desse período ele foi superado por outras redes sociais.

Sem entrar em detalhes da complexidade desse ambiente virtual que pretendia simular muitos aspectos do que denominamos “vida real”, e o que me levou a pensar em uma análise das redes sociais em mais de um post (por isso o título enumerando mais de uma verdade, parafraseando Budda em sua metodologia para estudar o sofrimento humano — as 8 nobres verdades), vamos observar um ponto que o transformava em uma pedra no sapato dos usuários — a monetização da rede social.

Qualquer rede social se sustenta em dois pilares, em uma ponta há os usuários e na outra os seus desenvolvedores, e por mais que nos esqueçamos, todo aquele que empreende almeja receber o retorno do seu esforço em empreender.

Estou desenvolvendo um estudo em que avalia a propagação das postagens em redes sociais. Tem me chamado a atenção o modo como nos rendemos a essa virtualização de nossas realidades, como precisamos da validação de nossas opiniões em redes sociais e como tem sido importante concordarmos com uma sutil imposição que elas nos apresenta — devemos ter opiniões formadas sobre qualquer assunto.

De maneira geral as redes sociais funcionam com o compartilhamento de informações dentro de seus ambientes virtuais. Em muitas delas o objeto a ser compartilhado é um texto, fotos, vídeos, ou qualquer outro conteúdo de mídia que expresse uma opinião ou sentimento, e que é convertido naquela plataforma como informação sobre os usuários. Essas informações são a monetização da rede social, elas possuem muito valor agregado e que o nosso encantamento por estar pertencendo a um ambiente virtual nos leva a distração dessa verdade.

Atualmente quase todas as redes sociais limitam a propagação de nossas postagens a uma taxa de conversão muito baixa, o que nos permite dizer que as viralizações estão sumindo do nosso cotidiano às custas de postagens patrocinadas, quer dizer, deve-se remonetizar a nossa experiência para ser vistos e “ouvidos”. As redes sociais que ainda mantem taxas orgânicas de propagação são o YouTube, pois esse é o seu negocio — se passar a limitar views perderá o sentido de ser, e o LinkedIn, que até incentiva os seus usuários a criarem artigos.

Quem deseja ser reconhecido nas redes sociais, principalmente as empresas, que buscam o ambiente virtual para tornarem suas marcas conhecidas, deverá se tornar consciente das limitações que por enquanto encontramos nas realidades virtualizadas. Há necessidade de se investir tempo e dinheiro, e afastar a crença de que o meio virtual seja mais simples, em realidade é o oposto, se faz necessário muito estudo, das métricas de cada rede, e dedicação no fortalecimento do seu empreendimento.

Por hora vou ficar por aqui e em breve trago um novo ponto para refletirmos.