https://github.com/luandro/brazil-inequality-visualized
Understanding poverty, wealth, and social policy through interactive data visualization
https://github.com/luandro/brazil-inequality-visualized
Last synced: 5 months ago
JSON representation
Understanding poverty, wealth, and social policy through interactive data visualization
- Host: GitHub
- URL: https://github.com/luandro/brazil-inequality-visualized
- Owner: luandro
- Created: 2025-12-31T13:13:02.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-04T14:44:09.000Z (5 months ago)
- Last Synced: 2026-01-04T23:37:35.294Z (5 months ago)
- Language: TypeScript
- Homepage: https://luandro.github.io/brazil-inequality-visualized/
- Size: 826 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Brazil Inequality Visualized
**Understanding poverty, wealth, and social policy through interactive data visualization**
[](https://luandro.github.io/brazil-inequality-visualized/)
[](LICENSE)
[](https://react.dev/)
[](https://www.typescriptlang.org/)
[](https://vite.dev/)
**[English](#) • [Português](#)**
---
## 📖 Overview
**Brazil Inequality Visualized** is an interactive web application that explores Brazil's socioeconomic landscape through validated, official data. Every statistic is sourced from Brazilian government statistics and international organizations, providing a comprehensive view of poverty, wealth concentration, labor markets, and social policy impacts.
## 🖼️ Screenshots
### 🎯 Key Features
- **📊 Reality Dashboard** - Comprehensive inequality metrics with official data validation
- **💰 Wealth Concentration Analysis** - Multi-millionaire and billionaire population estimates
- **👥 Labor Market Insights** - Employment, informality, and working poor statistics
- **🎮 Policy Simulator** - Model hypothetical wealth tax scenarios (educational)
- **🌍 Regional & Racial Breakdowns** - Poverty distribution across Brazil's regions and racial groups
- **🔍 Data Explorer** - Full dataset transparency with source verification
- **🌐 Bilingual Support** - English and Portuguese (Brazil) localization
### 🎨 Built With
---
## 🚀 Quick Start
### Prerequisites
- **Node.js** 18+ and **npm** (install with [nvm](https://github.com/nvm-sh/nvm#installing-and-updating))
- Git
### Installation
```bash
# Clone the repository
git clone https://github.com/luandro/brazil-inequality-visualized.git
cd brazil-inequality-visualized
# Install dependencies
npm install
# Start the development server
npm run dev
```
Open [http://localhost:5173](http://localhost:5173) to view the application.
### Build for Production
```bash
# Create production build
npm run build
# Preview production build locally
npm run preview
```
---
## 📂 Project Structure
```
brazil-inequality-visualized/
├── public/ # Static assets
├── src/
│ ├── components/ # Reusable UI components
│ │ └── ui/ # shadcn/ui primitives
│ ├── context/ # React context providers
│ ├── data/ # Datasets and data utilities
│ ├── hooks/ # Custom React hooks
│ ├── i18n/ # Internationalization (en, pt-BR)
│ ├── lib/ # Utility functions
│ ├── pages/ # Page-level components
│ ├── App.tsx # Main app with routes
│ └── main.tsx # Application entry point
├── docs/ # Project documentation
├── .github/ # GitHub Actions workflows
└── package.json # Dependencies and scripts
```
---
## 🛠️ Available Scripts
| Script | Description |
|--------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Create optimized production build |
| `npm run build:dev` | Build in development mode for debugging |
| `npm run preview` | Preview production build locally |
| `npm run lint` | Run ESLint across the repository |
| `npm run generate-logos` | Generate logo assets |
| `npm run optimize-images` | Optimize images in public/ |
---
## 🌐 Deployment
### GitHub Pages
This project is configured for automatic deployment to GitHub Pages via GitHub Actions.
**Setup:**
1. Enable GitHub Pages: Settings → Pages → Source: GitHub Actions
2. Configure permissions: Settings → Actions → General → Read and write permissions
3. Push to `main` branch - deployment happens automatically
**Custom Domain:**
See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed instructions.
### Alternative Hosting
The app works with any static hosting provider:
- **Netlify** - Automatic Vite detection
- **Vercel** - Zero configuration
- **AWS S3 + CloudFront** - Custom error responses for SPA routing
---
## 📊 Data Sources
All statistics are validated against official sources:
- **IBGE** (Brazilian Institute of Geography and Statistics) - Census, PNAD
- **World Bank** - International poverty lines, Gini coefficients
- **IPEA** - Institute of Applied Economic Research
- **Brazilian Government** - Official social program statistics
For complete source catalog and methodology, see the [Methodology](/methodology) section in the app.
---
## 🧪 Development
### Code Style
- **TypeScript** with strict mode enabled
- **ESLint** with React hooks and React Refresh rules
- **2-space indentation** (Prettier compatible)
- **Absolute imports** using `@/` alias
### Localization
Adding new translations:
1. Edit `src/i18n/en.json` and `src/i18n/pt-BR.json`
2. Use `useTranslation()` hook in components
3. Follow existing key structure
See [docs/i18n-guide.md](docs/i18n-guide.md) for detailed conventions.
### Adding New Pages
1. Create component in `src/pages/YourPage.tsx`
2. Add route in `src/App.tsx`
3. Add navigation entries in both language files
4. Update `src/i18n/en.json` and `src/i18n/pt-BR.json`
---
## 🤝 Contributing
Contributions are welcome! Here's how you can help:
1. **Report Issues** - Use GitHub Issues with clear descriptions and reproduction steps
2. **Suggest Features** - Share your ideas for new visualizations or data sources
3. **Submit Pull Requests** - Fork the repo, create a feature branch, and submit a PR
4. **Improve Documentation** - Enhance guides, fix typos, add examples
### Development Workflow
```bash
# Create feature branch
git checkout -b feature/your-feature
# Make changes and test
npm run dev
npm run lint
# Commit and push
git add .
git commit -m "feat: add your feature"
git push origin feature/your-feature
# Open pull request on GitHub
```
---
## 📝 License
This project is open source and available under the [MIT License](LICENSE).
---
## 🙏 Acknowledgments
- **Brazilian Government** - For making official statistics publicly available
- **IBGE** - For comprehensive demographic and economic data
- **World Bank** - For international poverty metrics and methodology
- **shadcn/ui** - For beautiful, accessible UI components
- **Vite & React Teams** - For amazing developer tooling
---
## 📞 Contact & Support
- 🐛 **Found a bug?** [Open an issue](https://github.com/luandro/brazil-inequality-visualized/issues)
- 💡 **Have an idea?** [Start a discussion](https://github.com/luandro/brazil-inequality-visualized/discussions)
- 📧 **Questions?** Open a GitHub Discussion with the `question` label
---
## 🗺️ Roadmap
- [ ] Add more historical time-series data
- [ ] Implement export functionality for charts
- [ ] Add more social policy simulators
- [ ] Expand regional breakdowns
- [ ] Mobile app version (React Native)
---
**Built with ❤️ to promote data-driven understanding of inequality**
[⬆ Back to Top](#brazil-inequality-visualized)