# codaqui/institucional architecture

> Architecture diagram of the GitHub repository codaqui/institucional, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codaqui/institucional
- Repository: https://github.com/codaqui/institucional

## Overview

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.

## Diagram (Mermaid)

```mermaid
graph TB
    Contrib["Collaborator"]:::external
    subgraph "Collaboration Workflow"
        disc["GitHub Discussions"]:::internal
        issues["Issues"]:::internal
        pr["Pull Requests"]:::internal
        issueTemplate[".github/ISSUE_TEMPLATE/"]:::internal
        prTemplate["pull_request_template.md"]:::internal
        readme["README.md"]:::internal
        devmd["DEVELOPMENT.md"]:::internal
    end
    Contrib --> disc --> issues --> pr --> Repo

    subgraph "GitHub Repository"
        Repo["GitHub Repo"]:::internal
        mkdocsYml["mkdocs.yml"]:::generator
        docsFolder["docs/"]:::generator
        overrides["overrides/"]:::generator
    end
    click mkdocsYml "https://github.com/codaqui/institucional/blob/main/mkdocs.yml"
    click docsFolder "https://github.com/codaqui/institucional/tree/main/docs/"
    click overrides "https://github.com/codaqui/institucional/tree/main/overrides/"

    Contrib -->|"push/PR"| Repo

    Repo --> CI["GitHub Actions"]:::internal

    subgraph "CI/CD Pipeline"
        ghWorkflow["gh-deploy.yml"]:::internal
        claatScript["claat.sh"]:::script
        adjustScript["adjust-index.sh"]:::script
    end
    click ghWorkflow "https://github.com/codaqui/institucional/blob/main/.github/workflows/gh-deploy.yml"
    click claatScript "https://github.com/codaqui/institucional/blob/main/.github/workflows/scripts/claat.sh"
    click adjustScript "https://github.com/codaqui/institucional/blob/main/scripts/adjust-index.sh"

    CI -->|"checkout & install"| Build["MkDocs Build"]:::generator

    subgraph "Site Generator"
        req["requirements.txt"]:::generator
    end
    click req "https://github.com/codaqui/institucional/blob/main/requirements.txt"

    Build -->|"generates site/"| Artifacts["site/"]:::artifact
    click Artifacts "https://github.com/codaqui/institucional/tree/main/site/"

    Artifacts -->|"deploy to gh-pages"| DeployBranch["gh-pages branch"]:::artifact
    DeployBranch -->|"publish"| Hosting["GitHub Pages / CDN"]:::artifact

    subgraph "Hosting & DNS"
        cname["CNAME"]:::artifact
    end
    click cname "https://github.com/codaqui/institucional/tree/main/CNAME"

    Hosting -->|"serve"| Browser["User Browser"]:::external

    subgraph "Assets & Documentation"
        assets["docs/assets/"]:::generator
        css["docs/stylesheets/extra.css"]:::generator
        images["images/"]:::generator
        contact["docs/contact.md"]:::generator
        conducta["docs/conduta.md"]:::generator
        team["docs/team.md"]:::generator
        trilha["docs/trilhas/"]:::generator
        blog["docs/blog/"]:::generator
    end
    click assets "https://github.com/codaqui/institucional/tree/main/docs/assets/"
    click css "https://github.com/codaqui/institucional/blob/main/docs/stylesheets/extra.css"
    click images "https://github.com/codaqui/institucional/tree/main/images/"
    click contact "https://github.com/codaqui/institucional/blob/main/docs/contact.md"
    click conducta "https://github.com/codaqui/institucional/blob/main/docs/conduta.md"
    click team "https://github.com/codaqui/institucional/blob/main/docs/team.md"
    click trilha "https://github.com/codaqui/institucional/tree/main/docs/trilhas/"
    click blog "https://github.com/codaqui/institucional/tree/main/docs/blog/"

    classDef internal fill:#cce5ff,stroke:#000,stroke-width:1px;
    classDef generator fill:#d4edda,stroke:#000,stroke-width:1px;
    classDef artifact fill:#ffe5b4,stroke:#000,stroke-width:1px;
    classDef script fill:#e2e3e5,stroke:#000,stroke-width:1px;
    classDef external fill:#f8d7da,stroke:#000,stroke-width:1px;
```
