README.md

---
title: Web Project Structure Viewer
emoji: 🔍
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
---

# 🔍 Web Project Structure Analyzer

![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
![Gradio](https://img.shields.io/badge/gradio-5.49.1-orange.svg)
![Python](https://img.shields.io/badge/python-3.10+-green.svg)
![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)

**Analise a estrutura completa de projetos web de forma automática e inteligente!**

Ferramenta desenvolvida para desenvolvedores que precisam visualizar rapidamente a organização de projetos web, seja para documentação, code review, ou simplesmente entender a arquitetura de um projeto.

---

## 🎯 O Que Faz?

Esta aplicação analisa a estrutura de projetos web e gera:

- 🌳 **Árvore Visual** em formato ASCII art (fácil de copiar/colar)
- 📊 **Estatísticas Detalhadas** (arquivos, tamanho, taxa de relevância)
- 📄 **Relatório em Markdown** pronto para documentação
- 🎯 **Filtragem Inteligente** (ignora arquivos desnecessários automaticamente)
- ⚡ **Análise Instantânea** (basta fazer upload do ZIP)

---

## ✨ Características Principais

### 🚀 Simplicidade Total
- Upload de arquivo ZIP
- Análise automática ao enviar
- Interface limpa e intuitiva
- Sem configurações complexas

### 🧹 Filtragem Inteligente

**O que é INCLUÍDO:**
- ✅ Código fonte (`.py`, `.js`, `.jsx`, `.ts`, `.tsx`, `.vue`, `.php`, etc)
- ✅ Estilos (`.css`, `.scss`, `.sass`, `.less`)
- ✅ Markup (`.html`, `.htm`)
- ✅ Configurações críticas (`package.json`, `requirements.txt`, `Dockerfile`)
- ✅ Documentação (`README.md`, `LICENSE`)
- ✅ Arquivos SQL (`.sql`)
- ✅ Configs de ambiente (`.env.example`, `.gitignore`)

**O que é IGNORADO automaticamente:**
- 🚫 **node_modules/** (dependências Node.js)
- 🚫 **.git/** (histórico Git)
- 🚫 **venv/** (ambientes virtuais Python)
- 🚫 **__pycache__/** (cache Python)
- 🚫 **dist/**, **build/** (arquivos compilados)
- 🚫 **cache/**, **logs/**, **tmp/** (arquivos temporários)
- 🚫 **.vscode/**, **.idea/** (configs de IDEs)
- 🚫 Arquivos minificados (`.min.js`, `.min.css`)
- 🚫 Source maps (`.map`)
- 🚫 Binários compilados (`.pyc`, `.class`, `.so`)
- 🚫 Arquivos grandes (>10MB)

### 📊 Estatísticas Geradas

```markdown
| Métrica | Descrição |
|---------|-----------|
| 📁 Total de arquivos | Todos os arquivos escaneados |
| ✅ Arquivos relevantes | Apenas código/config importantes |
| 💾 Tamanho total | Tamanho do projeto em MB |
| 🎯 Taxa de relevância | % de arquivos úteis vs total |
```

### 🌳 Formato de Árvore

Visualização em ASCII art com ícones:

```
📁 meu-projeto-react/
├── 📦 package.json
├── 📖 README.md
├── 📁 src/
│   ├── ⚛️ App.jsx
│   ├── 📜 index.js
│   ├── 📁 components/
│   │   ├── ⚛️ Header.jsx
│   │   └── ⚛️ Footer.jsx
│   └── 📁 styles/
│       └── 🎨 main.css
└── 📁 public/
    └── 🌐 index.html
```

---

## 🛠️ Tecnologias e Métodos Utilizados

### 🐍 Backend (Python)

**Framework:** Gradio 5.49.1
- Interface web moderna e responsiva
- Upload de arquivos ZIP
- Processamento assíncrono
- Componentes interativos

**Bibliotecas Padrão:**
- `os` - Navegação no sistema de arquivos
- `pathlib` - Manipulação de caminhos
- `zipfile` - Extração de arquivos ZIP
- `tempfile` - Gestão de arquivos temporários
- `shutil` - Operações de arquivos (limpeza)
- `typing` - Type hints para código robusto

### 🏗️ Arquitetura do Código

#### 1. **Classe `WebProjectAnalyzer`**
Núcleo da aplicação que implementa toda a lógica de análise.

**Atributos principais:**
```python
- ignored_dirs: Set[str]          # 40+ pastas a ignorar
- relevant_extensions: Set[str]   # 20+ extensões relevantes
- critical_files: Set[str]        # 50+ arquivos importantes
- ignored_file_patterns: Set[str] # Padrões de arquivos a ignorar
```

#### 2. **Métodos Principais**

##### `should_ignore(name, path, is_dir) -> bool`
**Propósito:** Determina se um arquivo/diretório deve ser ignorado.

**Lógica:**
1. Verifica se o diretório está na lista de ignorados
2. Sempre mantém arquivos críticos (package.json, etc)
3. Ignora arquivos ocultos (exceto importantes como .gitignore)
4. Ignora arquivos temporários (~, #)
5. Ignora arquivos com padrões indesejados (.min.js, .map)
6. Ignora arquivos >10MB

##### `is_relevant_file(name) -> bool`
**Propósito:** Determina se um arquivo é relevante para exibição.

**Critérios:**
1. Arquivos críticos → sempre relevante
2. Padrões ignorados → não relevante
3. Extensão na lista de relevantes → relevante

##### `get_file_icon(filename) -> str`
**Propósito:** Retorna emoji apropriado para o arquivo.

**Mapeamento:**
- Arquivos específicos (package.json → 📦)
- Por extensão (.py → 🐍, .js → 📜)
- Padrão (📄)

##### `extract_zip(zip_path) -> str`
**Propósito:** Extrai ZIP e retorna diretório raiz.

**Lógica:**
1. Cria diretório temporário
2. Extrai todo o conteúdo do ZIP
3. Detecta se há pasta raiz única (comum em ZIPs do GitHub)
4. Retorna caminho correto

##### `analyze_structure(root_path, max_depth) -> Tuple`
**Propósito:** Analisa recursivamente a estrutura do projeto.

**Algoritmo:**
1. **Inicialização:** Cria estruturas de dados (output, stats, files)
2. **Função recursiva `analyze_directory`:**
   - Lista todos os itens do diretório
   - Separa diretórios de arquivos
   - Filtra usando `should_ignore()`
   - Atualiza estatísticas
   - Renderiza arquivos com ícones
   - Renderiza diretórios e recursão
   - Controla profundidade máxima
3. **Formatação:** Usa caracteres ASCII (├──, └──, │) para árvore
4. **Retorno:** (estrutura_texto, estatísticas, lista_arquivos)

##### `create_structure_report(folder_name, structure, stats) -> str`
**Propósito:** Gera relatório completo em Markdown.

**Conteúdo:**
- Cabeçalho com nome do projeto
- Informações (data, projeto)
- Tabela de estatísticas
- Estrutura em bloco de código
- Legenda de ícones
- Rodapé

##### `process_zip(zip_file, max_depth) -> Tuple`
**Propósito:** Pipeline completo de processamento.

**Fluxo:**
1. Valida arquivo ZIP
2. Extrai para diretório temporário
3. Analisa estrutura
4. Gera relatório
5. Salva relatório em arquivo temp
6. Limpa recursos (finally block)
7. Retorna (relatório, estrutura, arquivo)

#### 3. **Função `create_interface()`**
Cria a interface Gradio com todos os componentes.

**Componentes:**
- `gr.File()` - Upload de ZIP
- `gr.Slider()` - Profundidade de análise
- `gr.Markdown()` - Relatório formatado
- `gr.Textbox()` - Estrutura em texto puro
- `gr.File()` - Download do relatório
- `gr.Button()` - Re-análise manual

**Eventos:**
- `zip_input.change()` - Análise automática ao upload
- `analyze_btn.click()` - Re-análise manual
- `max_depth.change()` - Re-análise ao mudar profundidade

### 🎨 Design Patterns Utilizados

1. **Singleton Pattern:** Classe analyzer instanciada uma vez
2. **Strategy Pattern:** Diferentes estratégias de filtragem (extensão, padrão, tamanho)
3. **Template Method:** Pipeline consistente em `process_zip()`
4. **Factory Pattern:** `get_file_icon()` cria ícones baseado em tipo
5. **Observer Pattern:** Eventos Gradio reagem a mudanças

### ⚡ Otimizações

1. **Sets para Lookup:** O(1) para verificações de ignorar/relevância
2. **Lazy Evaluation:** Apenas calcula tamanho se arquivo é relevante
3. **Early Exit:** Para recursão em profundidade máxima
4. **Limpeza de Recursos:** `finally` block garante remoção de temp files
5. **Ordenação:** `sorted()` para output consistente

### 🔒 Tratamento de Erros

```python
try:
    # Operação principal
except zipfile.BadZipFile:
    # ZIP inválido
except PermissionError:
    # Sem permissão
except Exception as e:
    # Erro genérico com traceback
finally:
    # Limpeza de recursos
```

---

## 🚀 Como Usar

### 1️⃣ **Preparar o Projeto**

**Opção A: Download do GitHub**
1. Vá no repositório do GitHub
2. Clique em **"Code"** → **"Download ZIP"**
3. Pronto para upload!

**Opção B: Comprimir Localmente**

**Windows:**
```
Clique direito na pasta → "Enviar para" → "Pasta compactada"
```

**Mac:**
```
Clique direito na pasta → "Comprimir [nome-da-pasta]"
```

**Linux:**
```bash
zip -r meu-projeto.zip meu-projeto/
```

**Ignorando lixo (recomendado):**
```bash
# Node.js
zip -r projeto.zip . -x "node_modules/*" ".git/*"

# Python
zip -r projeto.zip . -x "venv/*" ".git/*" "*.pyc"

# Geral
zip -r projeto.zip . -x "node_modules/*" ".git/*" "venv/*" "__pycache__/*"
```

### 2️⃣ **Upload e Análise**

1. **Arraste** o arquivo ZIP para a área de upload
2. **OU** clique e selecione o arquivo
3. **Aguarde** alguns segundos (automático!)
4. **Pronto!** Visualize a estrutura

### 3️⃣ **Usar os Resultados**

- 📋 **Copiar estrutura:** Botão de copiar no campo de texto
- 💾 **Download relatório:** Arquivo Markdown completo
- 🔄 **Re-analisar:** Ajuste profundidade e clique "Re-Analisar"

---

## 📖 Exemplos de Uso

### Projeto React

**Entrada:** `meu-app-react.zip`

**Saída:**
```
📁 meu-app-react/
├── 📦 package.json
├── 📦 package-lock.json
├── 📖 README.md
├── 🚫 .gitignore
├── 📁 src/
│   ├── ⚛️ App.jsx
│   ├── 📜 index.js
│   ├── 🎨 App.css
│   ├── 📁 components/
│   │   ├── ⚛️ Header.jsx
│   │   ├── ⚛️ Footer.jsx
│   │   └── ⚛️ Button.jsx
│   └── 📁 hooks/
│       └── 📜 useAuth.js
├── 📁 public/
│   ├── 🌐 index.html
│   └── 📄 manifest.json
└── 📁 tests/
    └── 📜 App.test.js

Estatísticas:
- Total: 45 arquivos
- Relevantes: 15 arquivos
- Tamanho: 2.3 MB
- Taxa: 33.3%
```

### Projeto Django/Python

**Entrada:** `meu-projeto-django.zip`

**Saída:**
```
📁 meu-projeto-django/
├── 🐍 manage.py
├── 🐍 requirements.txt
├── 📖 README.md
├── 🔐 .env.example
├── 📁 myproject/
│   ├── 🐍 settings.py
│   ├── 🐍 urls.py
│   ├── 🐍 wsgi.py
│   └── 🐍 asgi.py
├── 📁 apps/
│   ├── 📁 users/
│   │   ├── 🐍 models.py
│   │   ├── 🐍 views.py
│   │   ├── 🐍 admin.py
│   │   └── 🐍 urls.py
│   └── 📁 blog/
│       ├── 🐍 models.py
│       └── 🐍 views.py
├── 📁 templates/
│   └── 🌐 base.html
└── 📁 static/
    ├── 📁 css/
    │   └── 🎨 style.css
    └── 📁 js/
        └── 📜 main.js

Estatísticas:
- Total: 52 arquivos
- Relevantes: 18 arquivos
- Tamanho: 1.8 MB
- Taxa: 34.6%
```

---

## 🎯 Casos de Uso

### 1. **Documentação de Projetos**
Adicione a estrutura ao README.md para facilitar navegação.

### 2. **Code Review**
Entenda rapidamente a organização antes de revisar código.

### 3. **Onboarding de Desenvolvedores**
Ajude novos membros a entenderem a arquitetura.

### 4. **Planejamento de Refatoração**
Visualize áreas que precisam reorganização.

### 5. **Auditoria de Projetos**
Identifique arquivos desnecessários ou mal organizados.

### 6. **Apresentações Técnicas**
Mostre a estrutura em reuniões ou documentações.

---

## 🔧 Configurações

### Profundidade de Análise

**1-2 níveis:** Visão geral superficial
```
📁 projeto/
├── 📦 package.json
├── 📁 src/
└── 📁 public/
```

**3-4 níveis (padrão):** Balanceado
```
📁 projeto/
├── 📦 package.json
├── 📁 src/
│   ├── 📜 index.js
│   └── 📁 components/
│       ├── ⚛️ Header.jsx
│       └── ⚛️ Footer.jsx
└── 📁 public/
    └── 🌐 index.html
```

**5-8 níveis:** Análise profunda
```
📁 projeto/
├── 📦 package.json
├── 📁 src/
│   ├── 📜 index.js
│   └── 📁 components/
│       ├── 📁 layout/
│       │   ├── 📁 header/
│       │   │   ├── ⚛️ Header.jsx
│       │   │   └── 🎨 Header.css
│       │   └── 📁 footer/
│       │       └── ⚛️ Footer.jsx
...
```

---

## 💡 Dicas e Boas Práticas

### ✅ Faça

- ✅ Comprima apenas a pasta do projeto (não múltiplas pastas)
- ✅ Use profundidade 4-5 para projetos médios
- ✅ Use profundidade 6-8 para projetos grandes
- ✅ Baixe o relatório Markdown para documentação
- ✅ Copie a estrutura para README.md do projeto

### ❌ Evite

- ❌ Incluir node_modules, venv no ZIP (são ignorados de qualquer forma)
- ❌ ZIPs muito grandes (>500MB) - remova pastas pesadas antes
- ❌ Profundidade muito alta em projetos gigantes (lento)

---

## 📊 Limitações Conhecidas

- ⚠️ Arquivos >10MB são automaticamente ignorados
- ⚠️ Máximo de 8 níveis de profundidade
- ⚠️ Processamento pode levar tempo em projetos muito grandes
- ⚠️ Requer arquivo ZIP (não aceita pastas diretas)

---

## 🤝 Contribuindo

Este é um projeto open source! Contribuições são bem-vindas:

1. 🐛 Reporte bugs abrindo uma issue
2. 💡 Sugira novos recursos
3. 🔧 Envie pull requests com melhorias
4. 📖 Melhore a documentação

---

## 📜 Licença

MIT License - Sinta-se livre para usar em projetos pessoais ou comerciais.

---

## 🙋 FAQ

**Q: Funciona com qualquer tipo de projeto?**
A: Sim! React, Vue, Angular, Django, Flask, Node.js, PHP, Ruby, etc.

**Q: Os arquivos são armazenados?**
A: Não! Tudo é processado temporariamente e deletado após a análise.

**Q: Posso usar offline?**
A: Sim! Clone o repositório e rode localmente com `gradio app.py`.

**Q: Quanto tempo demora?**
A: Projetos pequenos (<100 arquivos): ~2s  
Projetos médios (<1000 arquivos): ~10s  
Projetos grandes: ~30-60s

**Q: Tem limite de tamanho do ZIP?**
A: Recomendado <100MB. Remova node_modules/venv antes de comprimir.

---

## 🔗 Links Úteis

- 🏠 [Hugging Face Space](https://huggingface.co/spaces/seu-usuario/project-analyzer)
- 📚 [Gradio Documentation](https://gradio.app/docs)
- 🐍 [Python zipfile](https://docs.python.org/3/library/zipfile.html)

---

## 👨‍💻 Desenvolvido com

- Python 3.10+
- Gradio 5.49.1
- ❤️ e ☕

---

**⭐ Se este projeto foi útil, considere dar uma estrela!**

*Última atualização: Outubro 2025*