A full-stack fiscal analytics platform that parses Brazilian SPED EFD ICMS/IPI files and surfaces business, tax, and product intelligence through a real-time BI dashboard.
Upload any SPED EFD ICMS/IPI .txt file and instantly get a structured analytics dashboard:
- Revenue, purchases & gross margin — KPI cards with period totals
- ICMS tax breakdown — donut chart split by sales vs. purchase operations
- Top-5 products by revenue — gradient horizontal bar chart with ranked highlights
- Business insights — average ticket, cancelled invoices, operation counts
The backend is built with a strict Clean Architecture — domain parsers, application use cases, and DTO layer are fully decoupled. The frontend fires three concurrent API requests and auto-navigates to the dashboard the moment the file is processed.
▶ Watch the live demo on the project page
Upload flow → automatic parsing → real-time BI dashboard
sped-engine-platform/
├── app/
│ └── api.py # FastAPI application + CORS
├── package/
│ └── sped/
│ ├── domain/
│ │ ├── blocos/
│ │ │ ├── bloco_0/ # Registro 0001, 0005, 0100, 0150, 0190, 0200
│ │ │ └── bloco_c/ # Registro C100, C170, C190
│ │ ├── entities/
│ │ │ └── sped_file.py # SpedFile domain entity
│ │ └── shared/
│ │ ├── cfop_filter.py # CFOP-based operation classification
│ │ └── number_parser.py
│ └── application/
│ ├── dto/ # BusinessSummary, TaxSummary, ProductSummary
│ └── use_cases/ # GenerateBusinessSummary, GenerateTaxSummary,
│ # GenerateProductSummary, ParseSpedFile
├── frontend-dashboard/ # Next.js 16 + Tailwind CSS + Recharts
├── tests/ # 211 tests · 99% coverage
├── data/fake/ # Synthetic SPED files for testing
└── scripts/
└── generate_fake_sped.py # Synthetic data generator
| Layer | Responsibility |
|---|---|
| Domain | SPED block parsers, entities, CFOP classification rules |
| Application | Use cases that orchestrate parsing and produce structured DTOs |
| API | FastAPI endpoints — receive file upload, return summaries |
| Frontend | Next.js dashboard — upload view, BI charts, view routing |
Backend
- Python 3.10+
- FastAPI + Uvicorn
- Pytest + pytest-cov (211 tests, 99% coverage)
- Clean Architecture (domain / application / infrastructure separation)
Frontend
- Next.js 16 · React 19 · TypeScript 5
- Tailwind CSS v4
- Recharts (gradient bar charts, donut PieChart, horizontal bar rankings)
- Python 3.10+
- Node.js 18+
# Clone the repository
git clone https://github.com/diogoheck6/sped-engine-platform.git
cd sped-engine-platform
# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies
pip install fastapi uvicorn python-multipart
# Start the API
uvicorn app.api:app --reloadThe API will be available at http://localhost:8000.
Interactive docs at http://localhost:8000/docs.
cd frontend-dashboard
npm install
npm run devThe dashboard will be available at http://localhost:3000.
| Method | Endpoint | Description |
|---|---|---|
POST |
/business-summary |
Revenue, purchases, invoice counts, top products |
POST |
/tax-summary |
ICMS totals, tax bases, operation counts |
POST |
/product-summary |
Average tickets, top-5 by revenue and quantity |
All endpoints accept a multipart/form-data request with a file field containing the SPED .txt file.
Example response — /business-summary:
{
"empresa_nome": "EMPRESA DEMO LTDA",
"contador_nome": "CONTADOR DEMO",
"competencia_inicio": "01012024",
"competencia_fim": "31012024",
"total_notas": 1200,
"total_notas_canceladas": 14,
"total_vendas": 4823910.5,
"total_compras": 3201445.2,
"produto_mais_vendido": "PRODUTO A",
"produto_maior_faturamento": "PRODUTO B"
}# Activate virtual environment first
source .venv/bin/activate
# Run full test suite with coverage
PYTHONPATH=. pytest --cov=package --cov-report=term-missing211 passed in 0.56s
Coverage: 99%
The data/fake/ directory contains ready-to-use synthetic SPED files for testing and demo purposes:
| File | Size | Notes |
|---|---|---|
sped_fake_small.txt |
Small | Minimal dataset for quick tests |
sped_fake_demo.txt |
Medium | Realistic demo dataset |
sped_fake_large_5000.txt |
~5 000 records | Performance and stress testing |
To generate new synthetic files:
python scripts/generate_fake_sped.pyClean Architecture over quick scripts. Even as a portfolio project, the codebase is structured so 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.
Concurrent API calls. The frontend fires Promise.all for all three summaries simultaneously, keeping the perceived load time minimal regardless of file size.
SVG gradients in Recharts. All chart fills use inline linearGradient defs, giving the dashboard a modern BI look without any additional dependencies beyond Recharts.
Synthetic data generator. The generate_fake_sped.py script produces structurally valid SPED files at any scale — useful for testing edge cases and benchmarking parse performance.
MIT — see LICENSE for details.