CodeArchDoc

Gerador automatico de documentacao de codigo com IA — modelo de arquitetura C4, diagramas de classes e muito mais.

Read in English

O que e o CodeArchDoc?

CodeArchDoc e uma ferramenta CLI open-source que analisa qualquer codebase e gera automaticamente documentacao arquitetural completa usando IA. Suporta multiplos providers de IA (Claude, OpenAI, DeepSeek) e produz documentacao detalhada com diagramas Mermaid.

O que ele gera

• C4 Model (todos os 4 niveis) — Diagramas de Contexto, Container, Componente e Codigo
• Diagrama de Classes — relacoes entre entidades, heranca, composicao
• Visao Geral da Arquitetura — descricao textual detalhada com decisoes de design
• Documentacao por Modulo — proposito, responsabilidades e API publica de cada modulo
• Glossario Tecnico — termos e conceitos-chave do projeto

Inicio Rapido

Instalacao

npm install -g codearchdoc

Configuracao

codearchdoc init

O wizard interativo vai perguntar:

1. Selecione seu provider de IA (Claude, OpenAI ou DeepSeek)
2. Informe sua API key
3. Escolha o formato de diagramas (Mermaid)
4. Escolha o idioma da documentacao (pt-BR, en-US ou ambos)

Gerar Documentacao

# Gera/atualiza apenas o que mudou
codearchdoc generate

# Forca regeneracao completa
codearchdoc generate --full

# Gera apenas um tipo especifico de documentacao
codearchdoc generate --only c4
codearchdoc generate --only classes
codearchdoc generate --only modules

Comandos

| Comando | Descricao | |---|---| | codearchdoc init | Wizard interativo de configuracao | | codearchdoc generate | Gera/atualiza documentacao (diff inteligente) | | codearchdoc generate --full | Forca regeneracao completa | | codearchdoc generate --only <tipo> | Gera tipo especifico (c4, classes, modules) | | codearchdoc status | Mostra o que mudou desde a ultima geracao | | codearchdoc cost-estimate | Estima uso de tokens e custo antes de rodar | | codearchdoc config set <chave> <valor> | Atualiza configuracao | | codearchdoc hook install | Instala git hook pre-commit opcional | | codearchdoc hook uninstall | Remove git hook pre-commit |

Configuracao

O CodeArchDoc usa um arquivo .codearchdoc.yml na raiz do seu projeto:

provider: claude                    # claude | openai | deepseek
apiKey: ${CODEARCHDOC_API_KEY}      # le da variavel de ambiente
model: claude-sonnet-4-5-20250929   # modelo a ser usado
diagramFormat: mermaid              # mermaid (plantuml em breve)
language: pt-BR                     # en-US | pt-BR
outputDir: docs                     # diretorio de saida
maxTokens: 100000                   # max tokens por execucao
timeout: 60000                      # timeout da API em ms
retries: 3                          # tentativas em caso de falha
maxFileSize: 500KB                  # ignora arquivos maiores que isso
ignore:                             # paths para ignorar
  - node_modules
  - dist
  - .git

Seguranca da API Key

Sua API key nunca e armazenada em texto plano no arquivo de config. Ela referencia uma variavel de ambiente:

# .env (adicione ao .gitignore)
CODEARCHDOC_API_KEY=sk-sua-chave-aqui

Ou passe diretamente:

codearchdoc generate --api-key=sk-sua-chave-aqui

Providers de IA

| Provider | Modelos | Configuracao | |---|---|---| | Claude | claude-sonnet-4-5, claude-haiku-4-5 | Obter API key | | OpenAI | gpt-4o, gpt-4o-mini | Obter API key | | DeepSeek | deepseek-chat, deepseek-reasoner | Obter API key |

Estrutura de Saida

docs/
├── architecture/
│   ├── c4-context.md          # C4 Nivel 1 - Diagrama de Contexto
│   ├── c4-container.md        # C4 Nivel 2 - Diagrama de Containers
│   ├── c4-component.md        # C4 Nivel 3 - Diagrama de Componentes
│   └── c4-code.md             # C4 Nivel 4 - Diagrama de Codigo
├── diagrams/
│   └── class-diagram.md       # Diagrama de classes
├── modules/
│   └── ...                    # Um arquivo por modulo detectado
├── glossary.md                # Glossario tecnico
├── overview.md                # Visao geral da arquitetura
└── .codearchdoc-cache.json    # Cache interno (nao editar)

Diff Inteligente

O CodeArchDoc e inteligente na regeneracao. Ele armazena hashes SHA de cada arquivo analisado. Nas execucoes seguintes, so envia para a IA os arquivos que mudaram, economizando tempo e custo de API.

Use codearchdoc status para ver o que esta desatualizado sem fazer nenhuma chamada de API.

Git Hooks (Opcional)

# Instalar hook pre-commit
codearchdoc hook install

# Remover
codearchdoc hook uninstall

O hook executa codearchdoc generate --silent antes de cada commit. Se a IA estiver indisponivel, o hook avisa mas nao bloqueia o commit.

Integracao CI/CD

GitHub Actions

name: Update Docs
on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm i -g codearchdoc
      - run: codearchdoc generate --silent
        env:
          CODEARCHDOC_API_KEY: ${{ secrets.CODEARCHDOC_API_KEY }}
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: auto-update documentation [skip ci]"

Como Funciona

codearchdoc generate
        │
        ▼
  1. Scan Codebase     → Le a arvore de arquivos, aplica ignores
        ▼
  2. Diff Analysis     → Compara hashes do cache com estado atual
        ▼
  3. Chunking          → Agrupa arquivos em chunks (respeita context window)
        ▼
  4. AI Analysis       → Envia chunks pro provider com prompts especializados
        ▼
  5. Assembly          → Monta os .md finais a partir das respostas
        ▼
  6. Cache Update      → Atualiza .codearchdoc-cache.json

Contribuindo

Contribuicoes sao bem-vindas! Leia as diretrizes de contribuicao antes de enviar um PR.

Licenca

MIT