Construindo DevDocAI - Uma IA que Escreve Seus Documentos | Parte 1: Fundação
Série: Construindo DevDocAI — Um Sistema Multi-Agente LangGraph em Produção
Parte 1 de 6 — Fundamentos: Backend, Autenticação, Banco de Dados, GitHub OAuth, Servidor MCP
O Problema
Toda equipe de engenharia tem o mesmo segredo sujo: os documentos estão mentindo.
Não intencionalmente. O código avança rápido, a documentação não. Um novo desenvolvedor entra → passa 2 semanas lendo wikis desatualizados → ainda precisa incomodar 3 engenheiros seniores apenas para entender um serviço.
Eu cansei disso. Então estou construindo DevDocAI.
O que é DevDocAI?
DevDocAI é um sistema multi-agente LangGraph de nível de produção que:
- Conecta-se ao seu repositório GitHub
- Lê sua base de código no nível AST (não apenas texto — estrutura de código real)
- Gera automaticamente documentação estruturada por módulo/função
- Atualiza a documentação automaticamente toda vez que um PR é mesclado
- Possui um chatbot de integração — novos desenvolvedores podem perguntar "o que esta função faz?" e obter respostas reais do código ao vivo
A palavra-chave é agente — não apenas um chatbot RAG. Este sistema entende seu código.
O Pipeline Completo do Agente (O que Estou Construindo)
INÍCIO
↓
codebase_parser ← Análise no nível AST do repositório GitHub
↓
doc_generator ← LLM gera documentação estruturada por módulo/função
↓
brave_researcher ← enriquece com contexto externo (bibliotecas, melhores práticas)
↓
HITL checkpoint ← VOCÊ revisa a documentação gerada antes da publicação
↓
doc_publisher ← salva no banco de dados + atualiza o armazenamento vetorial
↓
pr_watcher ← webhook do GitHub reativa a cada mesclagem de PR
↓
FIM
Paralelo → onboarding_chatbot ← RAG sobre o armazenamento vetorial para novos desenvolvedores
A parte HITL (Human-in-the-Loop) é o que torna isso real. O pipeline LangGraph literalmente pausa, espera que um desenvolvedor aprove via o frontend e, em seguida, retoma. Não apenas vibrações — fluxo de trabalho real.
Stack Tecnológico
| Camada | Tecnologia | Por quê |
|---|---|---|
| Framework de Agente | LangGraph | Multi-agente, HITL, checkpointing |
| Backend | FastAPI + Python | Assíncrono, rápido, limpo |
| Frontend | Next.js + Tailwind | (vindo na Fase 6) |
| LLM | Groq llama-3.3-70b | Inferência extremamente rápida |
| Embutidos | Cohere | Embutidos de classe mundial |
| Banco de Dados Vetorial | Qdrant | Nível de produção, cliente Python puro |
| Busca na Web | Brave Search API | Focado em desenvolvedores, priorizando a privacidade |
| Observabilidade | LangSmith | Rastreamento de agentes, depuração |
| Protocolo de Ferramenta | MCP | Padrão moderno de ferramentas |
| Autenticação | JWT + GitHub OAuth | Seguro, padrão da indústria |
| Cache | Redis (Upstash) | (vindo na Fase 5) |
| Armazenamento | AWS S3 | Armazenamento de documentos |
| Banco de Dados | PostgreSQL | Neon (produção), Docker (desenvolvimento) |
| Implantação | ECR + ECS Fargate | (vindo na Fase 7) |
| CI/CD | GitHub Actions | (vindo na Fase 7) |
Arquitetura — O Padrão Que Sigo
Cada camada tem uma função. Sem exceções.
Rota → Apenas HTTP (requisição/resposta)
↓
Serviço → Lógica de negócios
↓
Repositório → Apenas consultas ao banco de dados
↓
Banco de Dados
Isso é o que separa uma demonstração de algo real. Quando 5 engenheiros tocam a mesma base de código, esse padrão salva você.
Estrutura de Pastas
backend/
├── auth/
│ ├── jwt.py ← criação/verificação de token
│ ├── github_oauth.py ← fluxo GitHub OAuth
│ └── routes.py ← apenas camada HTTP
├── db/
│ ├── database.py ← PostgreSQL assíncrono
│ └── models.py ← modelos SQLAlchemy
├── repositories/
│ └── user_repository.py ← todas as consultas ao banco de dados aqui
├── schemas/
│ └── auth_schemas.py ← requisição/resposta Pydantic
├── services/
│ └── auth_service.py ← lógica de negócios
├── utils/
│ ├── helper_auth.py ← auxiliares bcrypt
│ └── encryption.py ← criptografia de token Fernet
├── mcp/
│ └── github_server.py ← Ferramentas GitHub para agentes
├── agents/ ← Fase 4
├── graph/ ← Fase 3
├── webhooks/ ← Fase 5
└── main.py
Design do Banco de Dados
4 tabelas, todas conectadas:
Usuário
└── Repositório
├── Documento ← documentos gerados (PENDENTE → APROVADO → PUBLICADO)
└── PipelineRun ← rastreamento de execução do LangGraph
Algumas decisões de produção que tomei:
UUIDs em vez de IDs inteiros — sem ataques de enumeração de ID sequencial.
Criptografia Fernet para tokens do GitHub — nunca armazene tokens de acesso em texto simples. Nunca.
# utils/encryption.py
from cryptography.fernet import Fernet
_fernet = Fernet(settings.ENCRYPTION_KEY.encode())
def encrypt(value: str) -> str:
return _fernet.encrypt(value.encode()).decode()
def decrypt(value: str) -> str:
return _fernet.decrypt(value.encode()).decode()
Índices na tabela Documento — repo_id, file_path, status estão todos indexados porque serão consultados constantemente em grande escala.
Enumeração DocStatus para a máquina de estados adequada:
PENDENTE → APROVADO → PUBLICADO
PENDENTE → REJEITADO
Fluxo GitHub OAuth
Frontend → GET /auth/github → URL de redirecionamento do GitHub
↓
Usuário autoriza no GitHub
↓
GitHub → POST /auth/github/callback?code=xxx
A implementação de DevDocAI pode revolucionar a forma como as empresas brasileiras gerenciam a documentação de software, reduzindo o tempo de integração de novos desenvolvedores. Além disso, a automação da documentação pode aumentar a eficiência e a precisão das informações, impactando positivamente a produtividade das equipes.
