How codaqui/institucional works
Para criar um diagrama de arquitetura detalhado e fiel ao projeto “CODAQUI” — um site estático gerado via MkDocs e hospedado no GitHub Pages — siga os passos abaixo.
Identificação do Tipo e Propósito do Projeto
• Trata-se de um site institucional e de documentação estática. É desenvolvido em Markdown e HTML via MkDocs, versionado no GitHub, e publicado no GitHub Pages (domínio customizado codaqui.dev).
Análise da Estrutura de Arquivos
• Top-level:
• mkdocs.yml: configuração do gerador (temas, plugins).
• docs/: conteúdo do site (páginas Markdown, assets estáticos, posts de blog, trilhas).
• overrides/: personalização de templates Jinja2 do MkDocs.
• .github/workflows/: pipelines de CI/CD (build e deploy).
• scripts/: utilitários para pós-processamento (adjust-index.sh).
• CNAME: domínio customizado.
Insights do README
• Indica ambiente de desenvolvimento colaborativo e CI rodando em GitHub Actions.
Componentes Principais para o Diagrama
a. Repo GitHub “institucional”: código-fonte + conteúdo (docs/, mkdocs.yml, overrides/)
b. Pipeline CI (GitHub Actions):
• Evento: push em branches (develop, main)
• Passos: checkout → instalar dependências Python (requirements.txt) → rodar mkdocs build → executar scripts (adjust-index.sh, claat.sh) → deploy (gh-pages)
c. Site Generator (MkDocs + plugins)
d. Artefatos estáticos (HTML/CSS/JS gerados)
e. Hospedagem (GitHub Pages + Cloudflare/GitHub DNS apontando para CNAME codaqui.dev)
f. Colaboradores: GitHub Discussions, Issues, Pull Requests
g. Usuário final: browser acessando https://codaqui.dev
Relacionamentos e Fluxo de Dados
1. Colaborador faz push ou PR no repositório → dispara workflow GitHub Actions.
2. Workflow executa MkDocs e scripts → gera pasta site/ (artefatos).
3. Artefatos são publicados na branch gh-pages.
4. GitHub Pages lê gh-pages → publica em https://codaqui.dev.
5. Usuário acessa o site.
Padrões Arquiteturais e Princípios
• Static Site Generator: separação clara entre conteúdo (Markdown) e apresentação (templates + CSS).
• CI/CD declarativo: GitHub Actions YAML.
• Infra zero-server: tudo são arquivos estáticos servidos por CDN/GitHub Pages.
Guias de Desenho do Diagrama
• Use caixas retangulares para cada componente (Repo, CI Pipeline, MkDocs, Hosting, Usuário).
• Conecte com setas direcionais indicando o fluxo (ex.: Git push → CI).
• Utilize cores para diferenciar:
• Azul: sistema interno (GitHub, Actions)
• Verde: gerador de site (MkDocs)
• Laranja: artefatos estáticos e hosting
• Cinza: scripts utilitários
• Inclua legendas ou rótulos: ex. “Checkout + Install”, “mkdocs build”, “gh-pages deploy”.
Elementos Obrigatórios no Diagrama
• Labels claros: “GitHub Repo”, “GitHub Actions”, “MkDocs Build”, “Site Static Files”, “GitHub Pages / CDN”, “Browser”.
• Setas com direção e rótulos: “push/PR →”, “build → publish →”, “request → response”.
• Diferenciação visual (cores/ícones) para conteúdo vs. pipeline vs. hosting.
Seguindo esse guia, você terá um diagrama completo, mostrando desde a contribuição de código até a publicação do site estático em produção, destacando todos os componentes e fluxos críticos do projeto CODAQUI.