Pular para o conteúdo principal

Monorepo tupynambalucas.dev

Este repositório é um monorepo que contém um gerador de estatísticas de perfil de desenvolvedor, site/hub pessoal, ferramentas de desenvolvedor, tokens de design e documentação.

1. Visão Geral do Produto & Proposta de Valor​

O monorepo coordena o site pessoal do desenvolvedor (hub), visualizações de estatísticas automatizadas (profile), sistemas de design (studio), hub de processamento de IA (cortex) e ferramentas de automação (tools).

A principal aplicação voltada para o cliente é o Developer Hub (@tupynambalucas-hub/*):

Para VisitantesPara o Desenvolvedor (Admin)
Portfólio: Visualizar projetos, arquiteturas de código e destaques.Publicação de Blog: Publicar artigos técnicos e estudos de caso.
Formulário de Contato: Enviar mensagens ou consultas de serviço.Coleta de Leads: Gerenciar envios e dados do painel.
Catálogo de Serviços: Solicitar serviços de desenvolvimento.Automação de Perfil: Atualizar métricas do GitHub via Zig.

2. Fluxo Operacional​

O site de portfólio e o gerador de estatísticas operam em um fluxo de trabalho simplificado:

  1. Apresentação de Portfólio: Os visitantes exploram o frontend @tupynambalucas-hub/web, consumindo postagens de blog e destaques de projetos servidos por @tupynambalucas-hub/api.
  2. Envio de Contato: As entradas do formulário são validadas por meio de chaves anti-spam do Turnstile, serializadas usando schemas do Zod do @tupynambalucas-hub/core e persistidas em uma instância do MongoDB.
  3. Geração de Estatísticas de Perfil: O workspace @tupynambalucas/profile compila métricas do GitHub usando uma CLI nativa em Zig e sobrescreve dinamicamente o arquivo README.md raiz.

3. Estratégia de Hospedagem & Implantação​

O monorepo utiliza o Cloudflare e ambientes VPS padrão para uma operação de alto desempenho e livre de manutenção.

Infraestrutura & Hospedagem​

  • Cloudflare Pages: O hub de documentação do Docusaurus (docs/) e o frontend React SPA do desenvolvedor (hub/services/web) são implantados nas Pages do Cloudflare para entrega otimizada de CDN.
  • Hetzner Cloud VPS / Linux VPS: A API REST Fastify de backend (hub/services/api) e as pilhas do Docker Compose com MongoDB/Redis são executadas em uma instância VPS leve.
  • DNS & SSL: O roteamento de DNS e a proteção de proxy são gerenciados globalmente através do Cloudflare.

4. Arquitetura & Workspaces do Monorepo​

Usamos PNPM Workspaces com um layout de Raiz Centrada em Contexto para isolar nossos domínios.

Para uma análise abrangente de nossa filosofia de contexto, estrutura de diretórios e funções de aplicativos, leia nossos guias arquitetônicos dedicados:

5. Workspaces Independentes​

Nossa prioridade é a implantação e manutenção de:

  • @tupynambalucas-hub/*: Hub pessoal React/Fastify.
  • @tupynambalucas/profile: Compilador de estatísticas de perfil do GitHub baseado em Zig.

6. Início Rápido​

Certifique-se de ter o Node.js 22+, PNPM 11+, Zig e Docker instalados.

  1. Instalar Dependências:

    pnpm install

  2. Configurar Arquivos de Ambiente: Cada workspace e serviço tem seu próprio arquivo de ambiente. Copie os modelos de exemplo e adicione seus parâmetros locais:

    # Configuração do Hub
    cp hub/infrastructure/docker/.env.example hub/infrastructure/docker/.env.dev

  3. Iniciar Infraestrutura Local & Aplicações: Fornecemos scripts de orquestração unificados via Turborepo para inicializar containers Docker e servidores de desenvolvimento local simultaneamente. Consulte MONOREPO.readme.md ou a Referência de Comandos para obter detalhes sobre a execução do pnpm hub:dev.

7. O Framework Diátaxis​

Uma abordagem sistemática para a criação de documentação técnica.

O Diátaxis é uma forma de pensar e fazer documentação.

Ele prescreve abordagens para conteúdo, arquitetura e forma que surgem de uma abordagem sistemática para compreender as necessidades dos usuários de documentação.

O Diátaxis identifica quatro necessidades distintas e quatro formas correspondentes de documentação — tutoriais, guias de como fazer, referência técnica e explicação. Ele os coloca em uma relação sistemática e propõe que a própria documentação seja organizada em torno das estruturas dessas necessidades.

O Diátaxis resolve problemas relacionados ao conteúdo da documentação (o que escrever), ao estilo (como escrever) e à arquitetura (como organizar).

Além de atender aos usuários da documentação, o Diátaxis tem valor para os criadores e mantenedores de documentação. É leve, fácil de entender e simples de aplicar. Ele não impõe restrições de implementação. Ele traz um princípio ativo de qualidade para a documentação que ajuda os mantenedores a pensarem de forma eficaz sobre seu próprio trabalho.

Começando​

A melhor maneira de começar com o Diátaxis é aplicando-o após a leitura de uma breve introdução.

Aplicação Prática​

Estas páginas ajudarão a dar um sentido imediato e concreto à abordagem.

Compreendendo o Diátaxis​

Esta seção explora a teoria e os princípios do Diátaxis mais profundamente e apresenta a compreensão das necessidades que o fundamentam.

O Diátaxis é comprovado na prática. Seus princípios foram adotados com sucesso em centenas de projetos de documentação.

Depoimento

O Diátaxis nos permitiu construir um conjunto de documentação interna de alta qualidade que nossos usuários adoram, e no qual nossos colaboradores adoram adicionar conteúdo.

—Greg Frileux, Vonage

Depoimento

Na Gatsby, reorganizamos recentemente nossa documentação de código aberto, e o framework Diátaxis foi nosso recurso de referência durante todo o projeto. Os quatro quadrantes nos ajudaram a priorizar o objetivo do usuário para cada tipo de documentação. Ao reestruturar nossa documentação em torno do framework Diátaxis, tornamos mais fácil para os usuários descobrirem os recursos de que precisam quando precisam deles.

— Megan Sullivan

Depoimento

Ao redesenhar a documentação do desenvolvedor da Cloudflare, o Diátaxis tornou-se nossa estrela-guia para a arquitetura de informação. Quando não tínhamos certeza de onde um novo conteúdo deveria se encaixar, consultávamos o framework. Nossa documentação está agora mais clara do que nunca, tanto para leitores quanto para colaboradores.

— Adam Schwartz