Gerador de Documento de Onboarding de Arquitetura de Codebase

**Contexto:** Sou um desenvolvedor que acabou de entrar no projeto e estou usando você, um assistente de codificação por IA, para obter uma compreensão profunda do código existente. Meu objetivo é me tornar produtivo o mais rápido possível e tomar decisões técnicas informadas com base em uma compreensão sólida do sistema atual. **Objetivo Primário:** Analisar o código-fonte fornecido neste projeto/workspace e gerar um documento Markdown detalhado, claro e bem estruturado que explique a arquitetura do sistema, recursos, fluxos principais, componentes-chave e stack de tecnologia. Este documento deve servir como um guia técnico de integração. Sempre que possível, melhore a navegabilidade fornecendo links diretos para arquivos, classes e funções relevantes, bem como exemplos de código que ajudem a esclarecer os conceitos. --- ## Instruções Detalhadas - Por favor, aborde os seguintes pontos: ### 1. Resumo dos Arquivos README / Instruções - Procure por arquivos como README.md, LEIAME.md, CONTRIBUTING.md ou documentação similar. - Forneça um resumo objetivo, porém detalhado, das seções mais relevantes para um novo desenvolvedor, incluindo: - Visão geral do projeto - Como configurar e executar o sistema localmente - Padrões e convenções adotados - Diretrizes de contribuição (se disponíveis) --- ### 2. Stack de Tecnologia Detalhado - Identifique e liste a stack de tecnologia completa usada no projeto: - Linguagem(ns) de programação, incluindo versões quando detectáveis (por exemplo, de package.json, pom.xml, .tool-versions, requirements.txt, build.gradle, etc.). - Principais frameworks (backend, frontend, etc. - por exemplo, Spring Boot, .NET, React, Angular, Vue, Django, Rails). - Banco(s) de dados: - Tipo (SQL / NoSQL) - Nome (PostgreSQL, MongoDB, etc.) - Estilo de arquitetura central (por exemplo, Monólito, Microsserviços, Serverless, MVC, MVVM, Arquitetura Limpa). - Plataforma de nuvem (se identificável via SDKs ou configuração - AWS, Azure, GCP). - Ferramentas de build e gerenciadores de pacotes (Maven, Gradle, npm, yarn, pip). - Quaisquer outras tecnologias relevantes (cache, message brokers, conteinerização - Docker, Kubernetes). - Referencie e vincule os arquivos de configuração que demonstram cada item. --- ### 3. Visão Geral do Sistema e Propósito - Descreva claramente o que o sistema faz e para quem é. - Quais problemas ele resolve? - Liste as funcionalidades principais. - Se possível, relacione o sistema aos domínios de negócio envolvidos. - Forneça uma descrição de alto nível dos principais recursos. --- ### 4. Estrutura do Projeto e Recomendações de Leitura - Ponto de Entrada: Por onde devo começar a explorar o código? Identifique os principais pontos de entrada (por exemplo, main.go, index.js, Program.cs, app.py, Application.java). Forneça links diretos para esses arquivos. - Organização Geral: Explique a estrutura geral de pastas e arquivos. Destaque convenções importantes. Use exemplos reais de nomes de pastas e arquivos. - Configuração: Existem arquivos de configuração principais? (por exemplo, config.yaml, .env, appsettings.json) Quais configurações são críticas? Forneça links. - Recomendação de Leitura: Sugira uma ordem ou um conjunto de arquivos/módulos-chave que devem ser lidos primeiro para compreender rapidamente os conceitos centrais do projeto. --- ### 5. Componentes-Chave - Identifique e descreva os módulos, classes, funções ou serviços mais importantes ou centrais. - Explique as responsabilidades de cada componente. - Descreva suas responsabilidades e interdependências. - Para cada componente: - Inclua um trecho de código representativo - Forneça um link para onde ele está implementado - Forneça links diretos e exemplos de código sempre que possível. --- ### 6. Fluxos de Execução e Dados - Descreva os workflows ou processos de negócio mais comuns ou críticos (por exemplo, processamento de pedidos, autenticação de usuário). - Explique como os dados fluem pelo sistema: - Onde os dados são persistidos - Como são lidos, modificados e propagados - Sempre que possível, ilustre com exemplos e vincule a funções ou classes relevantes. #### 6.1 Visão Geral do Esquema do Banco de Dados (se aplicável) - Para aplicações com uso intensivo de dados: - Identifique as principais entidades/tabelas/coleções - Descreva seus relacionamentos primários - Baseie-se em modelos ORM, migrações ou arquivos de esquema, se disponíveis --- ### 7. Dependências e Integrações - Dependências: Liste as principais bibliotecas externas, frameworks e SDKs usados. Explique brevemente o papel de cada um. Forneça links para onde estão configurados ou mais comumente usados. - Integrações: Identifique e explique integrações com serviços externos, bancos de dados adicionais, APIs de terceiros, message brokers, etc. Como ocorre a comunicação? Aponte para os módulos/classes responsáveis e inclua links. #### 7.1 Documentação da API (se aplicável) - Se o projeto expõe APIs: - Há evidências de ferramentas ou padrões de documentação de API (por exemplo, Swagger/OpenAPI, Javadoc, docstrings específicas de endpoint)? - Onde essa documentação pode ser encontrada ou como pode ser gerada? --- ### 8. Diagramas - Gere diagramas de alto nível para visualizar a arquitetura e o comportamento do sistema: - Diagrama de componentes (destacando os principais módulos e suas interações) - Diagrama de fluxo de dados (mostrando como as informações se movem pelo sistema) - Diagrama de classes (mostrando as principais classes e relacionamentos, se aplicável) - Diagrama de implantação simplificado (onde os componentes são executados, se detectável) - Diagrama de infraestrutura/implantacão simplificado (se os detalhes de infraestrutura forem aparentes) - Crie esses diagramas usando sintaxe Mermaid dentro do arquivo Markdown. - Os diagramas devem ser de alto nível; detalhamento extenso não é necessário. --- ### 9. Testes - Existem testes automatizados? - Testes unitários - Testes de integração - Testes ponta a ponta (E2E) - Onde estão localizados no projeto? - Qual(is) framework(s) de teste são usados? - Como os testes são tipicamente executados? - Como os testes podem ser executados localmente? - Existe alguma estratégia de CI/CD envolvendo testes? --- ### 10. Tratamento de Erros e Logging - Como a aplicação geralmente lida com erros? - Existe um padrão estabelecido (por exemplo, middleware global, exceções personalizadas)? - Qual biblioteca de logging é usada? - Existe um formato de logging padrão? - Há integração visível com ferramentas de monitoramento (por exemplo, Datadog, Sentry)? --- ### 11. Considerações de Segurança - Existem mecanismos de segurança evidentes no código? - Autenticação - Autorização (middleware/filtros) - Validação de entrada - Bibliotecas de segurança específicas são proeminentemente usadas (por exemplo, Spring Security, Passport.js, bibliotecas JWT)? - Existem práticas de segurança notáveis? - Gerenciamento de segredos - Proteção contra ataques comuns --- ### 12. Outras Observações Relevantes (Incluindo Build/Deploy) - Existem arquivos relacionados a build ou deploy? - Dockerfile - docker-compose.yml - Scripts de build/deploy - Arquivos de configuração de CI/CD (por exemplo, .github/workflows/, .gitlab-ci.yml) - O que esses arquivos indicam sobre como a aplicação é construída e implantada? - Há mais algo crucial ou particularmente útil para um novo desenvolvedor? - Dívida técnica conhecida mencionada em comentários - Padrões de design incomuns - Convenções de codificação importantes - Notas de desempenho --- ## Formato de Saída Final - Gere a resposta completa como um documento Markdown (.md) bem formatado. - Use linguagem clara e direta. - Organize o conteúdo com títulos e subtítulos de acordo com as seções numeradas acima. - Inclua trechos de código relevantes (curtos e representativos). - Inclua links clicáveis para arquivos, funções, classes e definições sempre que um elemento de código específico for mencionado. - Estruture o documento usando as seções numeradas acima para legibilidade. Sempre que possível: - Inclua links clicáveis para arquivos, funções e classes. - Mostre trechos de código curtos e representativos. - Use marcadores ou tabelas para listas. --- ### IMPORTANTE A análise deve considerar TODOS os arquivos no projeto. Leia e entenda todos os arquivos necessários para executar completamente esta tarefa e alcançar uma compreensão completa do sistema. --- ### Ação Por favor, analise o código-fonte atualmente disponível no meu ambiente/workspace e gere o documento Markdown conforme solicitado. O nome do arquivo de saída deve seguir este formato: <yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>