Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
94 lines (78 loc) · 5.05 KB

ARCHITECTURE.md

File metadata and controls

94 lines (78 loc) · 5.05 KB
Raw

📐 Arquitetura do GlassHub Quasar

Bem-vindo à documentação de arquitetura do GlassHub Quasar! Este documento foi escrito para ser claro, acessível e educativo para desenvolvedores de todos os níveis — do estagiário ao staff engineer.

🧭 1. Visão Geral da Solução

O GlassHub Quasar é um gerador dinâmico de imagens vetoriais (SVG) com estilo visual Glassmorphism Cosmic/Neon, projetado especificamente para ser incorporado em perfis do GitHub e arquivos README.md.

flowchart TD
    A[Usuário abre README no GitHub] --> B[GitHub Camo Proxy Image Server]
    B --> C[GlassHub Quasar API /api/*]
    D{Existe GITHUB_TOKEN?}
    D -- Sim --> E[GitHub GraphQL API v4]
    D -- Não / Falha --> F[GitHub REST API v3]
    F -- Falha / Rate-Limit --> G[Mock Data Resilience Generator]
    E --> H[Dynamic SVG Renderer Engine]
    F --> H
    G --> H
    H --> I[Vetor SVG estilizado com Glassmorphism]
    I --> B
    B --> A
Loading

⚡ 2. Princípios Fundamentais de Design

  1. Zero Cold Start (Resposta Instantânea):

    • Construído com Next.js 14 (App Router) e otimizado para rodar em Serverless Edge Functions (na Vercel ou Cloudflare Pages), garantindo que as imagens carreguem sem atraso.

  2. Resiliência Máxima de API (Tripla Camada de Fallback):

    • Camada 1 (GraphQL API v4): Consulta agregações completas (commits restritos, contribuições, PRs e estrelas) em um único payload HTTP rápido.
    • Camada 2 (REST API v3): Se a chave GraphQL não estiver presente ou falhar, o motor alterna automaticamente para REST.
    • Camada 3 (Mock Resilience Fallback): Se a API do GitHub estiver indisponível ou estourar o limite sem token (60 req/h), dados realistas simulados são injetados. Resultado: As imagens nos seus projetos NUNCA ficam quebradas.

  3. Camo Caching & Compatibilidade com GitHub:

    • O GitHub passa todas as imagens externas por um servidor proxy chamado GitHub Camo.
    • O GlassHub Quasar envia cabeçalhos HTTP de cache agressivos e amigáveis: 
      Cache-Control: public, max-age=1800, s-maxage=3600, stale-while-revalidate=86400

🧱 3. Estrutura dos Módulos

GlassHub Quasar/
├── app/                  # Next.js App Router (Páginas e Endpoints API)
│   ├── api/              # Endpoints HTTP que retornam respostas SVG
│   │   ├── activity-graph/# Gráfico de contribuições de 30 dias
│   │   ├── badge/        # Badges e botões vetoriais
│   │   ├── card/         # Cards de texto e destaques
│   │   ├── icon/         # Card de ícone dinâmico e monogramas
│   │   ├── image-filter/ # Molduras e efeitos sobre fotos
│   │   ├── logo/         # Logo oficial em vetor animado
│   │   ├── quote/        # Frases diárias de programação
│   │   ├── repo/         # Card de repositório em destaque
│   │   ├── socials/      # Bar de redes sociais e contato
│   │   ├── stats/        # Métricas de perfil e Rank orbital
│   │   ├── streak/       # Sequência de contribuições (Streak)
│   │   ├── table/        # Matrizes e tabelas de arquitetura
│   │   ├── tech-stack/   # Grid de tecnologias e habilidades
│   │   ├── title/        # Títulos e cabeçalhos em banner glass
│   │   ├── top-langs/    # Gráfico de linguagens mais usadas
│   │   └── wakatime/     # Estatísticas de tempo de código
│   ├── globals.css       # Estilos globais Tailwind CSS & Glassmorphism
│   ├── layout.tsx        # Layout raiz com fontes e metadados
│   └── page.tsx          # SPA do Playground Interativo
├── components/           # Componentes React da Interface Web
│   ├── CodeExporter.tsx  # Exportador de códigos (Markdown, HTML, SVG, PNG)
│   ├── Header.tsx        # Barra de navegação e topo
│   ├── PreviewContainer.tsx # Viewport de teste com Dark/Light Mode
│   └── WidgetPlayground.tsx # Playground interativo completo
├── lib/                  # Motor de Lógica e Integração
│   ├── github.ts         # Integração GraphQL, REST e Mock Data
│   ├── icons.ts          # Banco de caminhos vetoriais de ícones (SVG path)
│   ├── logo-svg.ts       # Gerador do logo oficial do GlassHub
│   ├── svg-utils.ts      # Utilitários de escape XML, sombras e filtros SVG
│   └── theme.ts          # Sistema de temas Glassmorphism e Theme Studio

🎨 4. O Sistema Visual Glassmorphism

O Glassmorphism no vetor SVG é construído sem bibliotecas pesadas de terceiros, utilizando apenas elementos nativos de SVG <defs> e <style>:

  • Painéis Translúcidos: rgba(15, 23, 42, 0.78)
  • Efeito de Vidro Refletivo: Gradientes lineares simulando luz incidente <linearGradient id="glassReflection">
  • Sombra Macia Projetada: Gradiente com desvio padrão de borrão <filter id="glassShadow">
  • Neon Glow: Efeito de incandescência neon usando filtros SVG <filter id="neonGlow">