SPED Engine Platform
A full-stack fiscal analytics platform that parses Brazilian SPED EFD ICMS/IPI files and surfaces business, tax, and product metrics through an interactive BI dashboard — built end to end with Python and Next.js.
What it does
Upload any SPED EFD ICMS/IPI .txt file and instantly get structured summaries: total revenue, purchases, gross margin, ICMS breakdown by operation type, and top-5 product rankings by revenue and quantity.
Live Demo
Upload flow → automatic parsing → real-time BI dashboard.
Context
The SPED (Sistema Público de Escrituração Digital) is Brazil's mandatory digital bookkeeping system used by companies to report fiscal operations to the government. EFD ICMS/IPI files contain thousands of structured records covering invoices, tax calculations, and product movements.
Extracting meaningful business intelligence from these files typically requires accounting knowledge, custom scripts, or expensive ERP software. The goal of this project was to build an open, fast, and clean alternative.
Architecture
The project follows a clean architecture with a strict separation between domain, application, and infrastructure layers:
- Domain layer — entities, block parsers (Bloco 0, Bloco C), and shared utilities like CFOP filtering and number parsing
- Application layer — use cases for generating business, tax, and product summaries as structured DTOs
- API layer — FastAPI endpoints that receive the uploaded file and return all three summaries concurrently
- Frontend — Next.js 16 + Tailwind CSS dashboard with view routing, gradient charts, donut ICMS chart, and ranked product cards
Key Features
- Parses real SPED EFD ICMS/IPI files — tested on synthetic datasets up to 5,000 records
- Revenue, purchases, and gross margin KPI cards with color-coded accents
- Gradient bar chart (Revenue · Purchases · Margin) and donut chart for ICMS distribution
- Top-5 products ranked by revenue with progress-bar visualization
- Two-view layout (Upload / Dashboard) with automatic navigation after file processing
- Full test suite with Pytest covering all use cases and edge cases
Engineering Decisions
Clean Architecture over quick scripts. Even as a portfolio project, the codebase is structured so that parsers, use cases, and DTOs can be extended independently — adding a new SPED block or a new summary type requires no changes to existing logic.
Three concurrent API calls. The frontend fires Promise.all for business, tax, and product summaries simultaneously, keeping the perceived load time minimal regardless of file size.
Recharts with SVG gradients. All chart fills use inline SVG linearGradient defs instead of solid colors, giving the dashboard a modern BI look without any external chart library dependencies beyond Recharts.