Pular para o conteúdo principal

Fonte Única da Verdade (SSOT)

O princípio da Fonte Única da Verdade (SSOT - Single Source of Truth) garante que cada estrutura de dados, esquema e regra de negócio principal seja definido em exatamente um local autoritativo, eliminando a duplicação e problemas de sincronização entre diferentes aplicações no monorepo.

1. Conceito Arquitetural e Visão Geral​

A Fonte Única da Verdade (SSOT) é um paradigma de engenharia fundamental que estabelece que todos os componentes do sistema devem referenciar uma definição única e centralizada para modelos de dados, contratos de validação e constantes. Esse design evita estados de "cérebro dividido" (split-brain) onde pacotes independentes (como backends de API, filas de mensagens e interfaces de usuário) divergem em nomes de propriedades, tipos de dados ou limites de esquemas.

Ao centralizar os esquemas principais, nós:

  • Garantimos segurança de tipo (type safety) completa do banco de dados até a UI.
  • Permitimos atualizações instantâneas de propriedades (props) e esquemas em todas as aplicações após modificações.
  • Reduzimos a duplicação de código e a sobrecarga de ferramentas (tooling).

2. Utilização Específica no Projeto​

No tupynambalucas.dev, o princípio SSOT é implementado nativamente por meio de nossa arquitetura monorepo:

A. Bibliotecas Core Centralizadas​

Os workspaces @tupynambalucas-hub/core e @tupynambalucas-hub/core servem como o SSOT absoluto para seus respectivos contextos delimitados. Qualquer esquema, interface ou tipo compartilhado por mais de uma aplicação (como a API do backend e a SPA web do frontend) deve ser declarado aqui primeiro, seguindo nossa diretriz de Design Direcionado ao Core (Core First Design).

B. Compartilhamento de Contratos e Tipos​

Aplicações downstream como @tupynambalucas-hub/api (Fastify) e @tupynambalucas-hub/web (React SPA) não mantêm interfaces de objetos de transferência de dados (DTO) ou modelos de banco de dados duplicados. Em vez disso, importam diretamente tipos, interfaces e classes do pacote core compartilhado:

// Core package definition
// instance/packages/core/src/domains/cycle/cycle.types.ts
export interface ICycle {
  id: string;
  name: string;
  startDate: Date;
  endDate: Date;
  status: 'active' | 'closed' | 'draft';
}
// Consumed directly in downstream API
// instance/apps/api/src/domains/cycle/cycle.service.ts
import type { ICycle } from '@tupynambalucas-hub/core';

C. Consistência na Validação de Esquemas​

Esquemas de validação compartilhados são declarados uma única vez usando Zod dentro das bibliotecas core. A API do backend consome esses esquemas em seus controllers para validar payloads HTTP recebidos, enquanto a aplicação web frontend usa os mesmos esquemas para validação de formulários no lado do cliente.

A modificação de um campo exige a atualização de apenas um único arquivo no workspace core, o que se propaga automaticamente por todo o pipeline de build durante a verificação em tempo de compilação, eliminando a sincronização manual de contratos de API.