Pular para o conteúdo principal

Arquitetura Técnica

1. Resumo Executivo​

tupynambalucas.dev é um portal de desenvolvedor pessoal, portfólio, blog e motor de automação. O sistema é construído sobre uma arquitetura Monorepo usando PNPM Workspaces e Turborepo, priorizando alto desempenho, tipagem estrita e isolamento de domínio por meio de uma estratégia de Contexto Delimitado (Bounded Context).

A arquitetura é projetada para hospedar o site central do desenvolvedor (hub) e o compilador automatizado de estatísticas (profile), logicamente desacoplados no nível raiz.

2. Estrutura Monorepo e Contextos Delimitados​

A base de código do tupynambalucas.dev é organizada em Contextos de Domínio no nível raiz. Para um detalhamento dos papéis da aplicação, filosofia de contextos e estruturas de diretórios, por favor consulte o guia de Contextos Delimitados:

3. Estratégia de Build e Resolução de Workspace​

Empregamos uma Arquitetura Híbrida de Alto Desempenho otimizada pelo Turborepo para gerenciar dependências internas e orquestração de tarefas.

3.1. Orquestração de Tarefas (Turborepo)​

O Turborepo é o motor por trás da nossa produtividade no monorepo. Ele lida com:

  • Grafo de Dependências: Identificação automática de quais pacotes precisam ser construídos ou verificados com base em alterações locais.
  • Acoplamento de Infraestrutura: Orquestração de serviços do Docker Compose como pré-requisitos para o desenvolvimento da aplicação (por exemplo, pnpm hub:up inicia os bancos de dados antes da API).
  • Cache: Aceleração de builds, checagem de tipos e linting ao pular módulos não alterados.
  • Saídas Unificadas: Padronização de artefatos de build em dist/ (para aplicativos e core) e build/ (para Docusaurus).

4. Comandos Operacionais​

Usamos uma interface CLI unificada definida no package.json raiz para orquestrar e gerenciar o monorepo em todos os ambientes (desenvolvimento, homologação e produção).

Para uma lista de referência completa de scripts de orquestração, comandos de serviços e fluxos de trabalho da pilha de desenvolvimento, por favor consulte a Referência de Comandos:

5. Princípios Arquiteturais​

Para garantir manutenibilidade extrema, legibilidade a longo prazo e limites claros entre nossos contextos de domínio, o tupynambalucas.dev segue quatro princípios arquiteturais fundamentais.

Clique em qualquer cartão abaixo para explorar uma análise aprofundada de cada princípio:

6. Pilha de Tecnologia​

6.1. Gerenciamento e Orquestração de Pacotes​

  • Ambiente de Execução (Runtime): Node.js 22+ (LTS).
  • Gerenciador de Pacotes: PNPM v11 (Gerenciamento estrito de dependências via symlinks e armazenamento de conteúdo por links físicos/hard-links).
  • Gerenciamento de Dependências: Catálogos do PNPM (PNPM Catalogs) (Controle de versão centralizado para dependências compartilhadas no workspace usando o protocolo catalog:).
  • Orquestrador de Tarefas: Turborepo (Cache otimizado e execução paralela).
  • Ferramental (Tooling): TypeScript 6, ESLint 10 (Configuração Plana/Flat Config), Prettier 3, Vite 8, Zig.

6.2. Backend (Camada de API)​

  • Framework: Fastify v5 (Otimizado para alta taxa de transferência/throughput).
  • ORM/ODM: Mongoose com MongoDB (com Replica Set ativado para transações ACID).
  • Validação: Zod (Integrado através de pacotes core específicos de domínio).
  • Processamento: BullMQ + Redis para tarefas assíncronas.

6.3. Frontend (Camada de UI)​

  • Framework: React 19.
  • Gerenciamento de Estado: Zustand (Estado atômico e performático usando Slices e Selectors).
  • Estilização: TailwindCSS v4 + CSS Modules para estilos com escopo local.
  • Animações: GSAP (Feedback interativo de alta fidelidade).

7. Padrões Arquiteturais​

7.1. Responsabilidades em Camadas (Backend)​

Cada domínio segue uma hierarquia estrita para isolar responsabilidades: Controller -> Service -> Repository -> Model

  • Controller: Lida com E/S HTTP (HTTP I/O), definições de rotas e validação de esquemas Zod.
  • Service: Orquestra regras de negócio, lógica complexa e transações entre modelos.
  • Repository: Abstrai a lógica de persistência de dados (Padrão de Repositório/Repository Pattern) para manter os serviços agnósticos ao banco de dados.
  • Model: Define a estrutura do banco de dados Mongoose e as regras de integridade dos dados.

Exemplo de Implementação (Repository Pattern)​

Para manter a tipagem estrita e o desacoplamento, os repositórios recebem o modelo do Mongoose por meio de injeção de dependência.

// hub/services/api/src/domains/auth/auth.repository.ts
import type { Model } from 'mongoose';
import type { IUser } from '@tupynambalucas-hub/core';

export class AuthRepository {
  constructor(private readonly userModel: Model<IUser>) {}

  async findByEmail(email: string): Promise<IUser | null> {
    return this.userModel.findOne({ email }).exec();
  }

  async create(data: Partial<IUser>): Promise<IUser> {
    return this.userModel.create(data);
  }
}

7.2. Orquestração de Estado no Frontend (Zustand e FSD)​

Para evitar stores monolíticas e renderizações desnecessárias no React 19, o frontend adota um Padrão de Seletores Atômicos (Atomic Selectors Pattern) estrito acoplado a Hooks de Domínio:

  1. Separação de Estado vs. Ações: A store do Zustand separa o state (estado) das actions (ações). A lógica pura de domínio (como cálculos) é extraída para fora da store para manter a Fonte Única da Verdade (SSOT) e a testabilidade.
  2. Seletores Atômicos: Exportações monolíticas (export const useAuthStore = create(...)) são envelopadas em hooks específicos.
  3. Hooks de Domínio (src/domains/*/hooks): Os seletores são expostos como hooks individuais (por exemplo, useAuthUser(), useProductActions()). Isso garante que um componente seja renderizado novamente apenas quando a fatia exata do estado que ele assina for alterada.

Exemplo de Implementação (Zustand Atomic Selectors)​

// hub/services/web/src/domains/cart/hooks/useCart.ts
import { useCartStore } from '../cart.store';

// Atomic Selectors
export const useCartItems = () => useCartStore((state) => state.items);
export const useCartActions = () => useCartStore((state) => state.actions);

// Derived State Selector (Never stored in state)
export const useCartTotal = () =>
  useCartStore((state) => state.items.reduce((acc, item) => acc + calculateItemPrice(item), 0));

7.3. Injeção de Dependência​

Gerenciamento modular por meio de decoradores do Fastify e um registro centralizado para desacoplar componentes e facilitar testes.

8. Infraestrutura e Implantação​

Projetado para Excelência Auto-Hospedada na Hetzner Cloud, nossos padrões de conteinerização, topologias Docker Compose multisserviço, estratégia de variáveis de ambiente e padrões de rede são gerenciados de forma centralizada.

Para um guia completo e aprofundado sobre estruturas de diretórios, modelos de Docker Compose de alto padrão e padrões avançados de multisserviços (incluindo os padrões Gateway e Pilha Distribuída), consulte a documentação dedicada:

9. Automação de Studio e IA (Arquitetura)​

Os workspaces Studio e Cortex fornecem a infraestrutura para alinhamento de design-para-código, pipelines de automação e engenharia assistida por IA.

10. Padrões de Segurança​

O tupynambalucas.dev segue uma estratégia de segurança em múltiplas camadas. Para detalhes detalhados de implementação, consulte o documento de Arquitetura de Segurança.

  • Proteção contra Bots: Integração com o Cloudflare Turnstile para todos os pontos de entrada de autenticação.
  • Mitigação de Força Bruta: Limitação de taxa baseada em IP e lógica de bloqueio de conta.
  • Tipagem Estrita: Modo estrito do TypeScript (TypeScript Strict Mode) ativado em todo o projeto.
  • Integridade de Build: Aprovações automatizadas de scripts de build via pnpm.onlyBuiltDependencies.
  • Integridade de Dados: Módulo de Replica Set do MongoDB (rs0) para confiabilidade transacional e conformidade com ACID.
  • Validação: Validação estrita com Zod em cada ponto de entrada (requisições de API, variáveis de ambiente, contratos internos).