🏗️ Estrutura do Projeto - Bubble Detector

📁 Estrutura de Arquivos

bubble-detector/
├── backend/
│   ├── main.py              # FastAPI app (entry point)
│   ├── requirements.txt     # Dependencies
│   └── Dockerfile          # Container config
│
├── frontend/
│   └── index.html          # UI simples
│
├── docker-compose.yml       # Orquestração
├── setup.sh                # Gera estrutura
├── start.sh                # Inicia sistema
├── stop.sh                 # Para sistema
└── README.md               # Docs

Opcional (expansão futura):
├── backend/
│   ├── fetchers.py         # Data collection
│   ├── calculators.py      # Metrics logic
│   ├── models.py           # DB models
│   └── tasks.py            # Celery jobs
└── docker/
    ├── postgres/
    └── redis/

🔄 Fluxo de Dados

1. USER → Frontend (localhost:3000)
2. Frontend → API (localhost:8000/api/analyze)
3. API → Data Fetchers (CoinGecko, GitHub, Reddit, PyPI)
4. Fetchers → Calculator (6 metrics)
5. Calculator → Bubble Index
6. API → Cache (Redis) [opcional]
7. API → Database (PostgreSQL) [opcional]
8. API → Frontend (JSON response)

🎯 Componentes Core

1. FastAPI (backend/main.py)

• REST endpoints
• CORS habilitado
• Health checks
• Swagger docs automático

2. Data Fetchers

Busca dados de:
PyPI: Downloads de pacotes
GitHub: Stars, forks, commits
Reddit: Sentiment, engagement
HuggingFace: Model downloads
CoinGecko: Market data

3. Calculators (6 métricas)

calculate_adoption()     # Bass Model
calculate_hype()         # Gartner Cycle
calculate_investment()   # Momentum
calculate_network()      # Metcalfe
calculate_feedback()     # Dynamic Systems
calculate_bubble_index() # Composite

4. Frontend (HTML/JS)

• Interface minimal
• Fetch API
• Tailwind CSS

🐳 Docker Compose

Versão Mínima (atual)

services:
  api:          # FastAPI (8000)
  frontend:     # Nginx (3000)

Versão Completa (futuro)

services:
  api:          # FastAPI
  frontend:     # Nginx
  db:           # PostgreSQL
  redis:        # Cache
  worker:       # Celery
  beat:         # Scheduler

🚀 Como Usar

1. Gerar estrutura
chmod +x setup.sh
./setup.sh

2. Iniciar
docker-compose up -d

3. Testar
curl http://localhost:8000/health

4. Acessar UI
open http://localhost:3000

5. Ver docs
open http://localhost:8000/docs

🔧 Troubleshooting

Erro: "worker exited with code 2"

Solução: Worker/Beat são opcionais. Remover do docker-compose.yml ou comentar.

Erro: "CREATE DATABASE"

Solução: PostgreSQL opcional. Versão mínima não usa DB.

Erro: "Port already in use"

Solução: Mudar portas no docker-compose.yml

📊 APIs Disponíveis

GET  /                   # Status
GET  /health            # Health check
POST /api/analyze       # Análise de bolha

Exemplo Request

curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"asset": "ChatGPT"}'

Exemplo Response

{
  "asset": "ChatGPT",
  "bubble_index": 0.35,
  "risk_level": "Moderado",
  "timestamp": "2024-01-15T10:30:00"
}

🎨 Frontend Features

• Input de asset
• Botão de análise
• Display de resultado
• Design responsivo

📈 Expansão (Roadmap)

Phase 1: MVP (atual)

• ✅ API básica
• ✅ Frontend simples
• ✅ Docker setup

Phase 2: Data Integration

• [ ] Fetchers reais (PyPI, GitHub)
• [ ] Cache com Redis
• [ ] DB para histórico

Phase 3: Advanced

• [ ] Celery workers
• [ ] Scheduled jobs
• [ ] Dashboard completo
• [ ] Alertas

🛠️ Tech Stack

| Layer | Tech | Porta | |-------|------|-------| | Frontend | HTML/JS/Tailwind | 3000 | | Backend | FastAPI/Python | 8000 | | Cache | Redis | 6379 | | DB | PostgreSQL | 5432 | | Container | Docker Compose | - |

📝 Notas Importantes

1. Versão mínima funciona SEM PostgreSQL 2. Workers são opcionais (comentar no compose) 3. Frontend é static (pode usar React depois) 4. APIs externas são gratuitas (maioria sem key) ---

Objetivo: Funcionar com docker-compose up -d em <5 minutos.