Technical prototype of a full-stack reporting system.
Built for experimentation, architecture validation, and portfolio demonstration.

Disclaimer
This repository represents a technical prototype.
Product name, branding, licensing, and commercial availability are subject to change.
This project may serve as the foundation for a future proprietary product.

• Overview
• Features
• Tech Stack
• Getting Started
• Project Structure
• Environment Variables
• Development
• Deployment
• Contributing
• License

This project is a self-hosted reporting platform prototype inspired by enterprise reporting tools. It allows teams to execute SQL-based reports and export them as PDF documents.

The main goal of this repository is to explore:

• Reporting system architecture
• Secure SQL execution
• PDF generation pipelines
• Modern full-stack development practices

• SQL query execution with validation
• PDF export (Puppeteer)
• Query results display
• Docker Compose setup
• TypeScript throughout
• Rate limiting and security

• Pagination and performance optimization
• JWT authentication
• Saved query templates
• Excel export
• Interactive charts
• Scheduled reports

• Runtime: Node.js 20+
• Framework: Express.js
• Language: TypeScript 5.3
• Database: MySQL 8.0
• PDF: Puppeteer 21
• ORM: mysql2 (native driver)

• Framework: Next.js 16 (App Router)
• UI Library: React 19
• Styling: Tailwind CSS 4
• State: React Hooks
• HTTP: Axios
• Icons: Lucide React

• Containerization: Docker + Docker Compose
• Reverse Proxy: Nginx (planned)
• CI/CD: GitHub Actions (planned)
• Monitoring: Planned

• Node.js 20+ (Download)
• Docker & Docker Compose (Download)
• Git (Download)

# 1. Clone the repository
git clone https://github.com/YOUR-USERNAME/reporting-platform-prototype.git
cd reporting-platform-prototype

# 2. Setup environment variables
cp .env.example .env
# Edit .env with your credentials (see Environment Variables section)

# 3. Start all services
docker-compose up -d

# 4. Access the application
# Frontend: http://localhost:5173
# Backend:  http://localhost:3000
# MySQL:    localhost:3306

cd backend

# Install dependencies
npm install

# Setup environment
cp ../.env.example .env

# Run migrations (if applicable)
# npm run migrate

# Start development server
npm run dev

# Backend available at http://localhost:3000

cd frontend

# Install dependencies
npm install

# Setup environment
cp .env.example .env

# Start development server
npm run dev

# Frontend available at http://localhost:5173

# Start MySQL locally or use Docker
docker run -d \
  --name reporting-platform-prototype-mysql \
  -e MYSQL_ROOT_PASSWORD=your_password \
  -e MYSQL_DATABASE=relatorios \
  -p 3306:3306 \
  mysql:8.0

# Import schema (if exists)
# mysql -u root -p relatorios < schema.sql

reporting-platform-prototype/
├── backend/                 # Backend API (Express + TypeScript)
│   ├── src/
│   │   ├── config/         # Configuration files
│   │   ├── controllers/    # Route controllers
│   │   ├── middlewares/    # Express middlewares
│   │   ├── routes/         # API routes
│   │   ├── services/       # Business logic
│   │   ├── types/          # TypeScript types
│   │   └── server.ts       # Entry point
│   ├── Dockerfile
│   ├── package.json
│   └── tsconfig.json
│
├── frontend/                # Frontend UI (Next.js)
│   ├── app/                # App Router (pages & layouts)
│   ├── components/         # React components
│   ├── features/           # Feature-sliced modules
│   ├── hooks/              # Custom hooks
│   ├── services/           # API services
│   ├── utils/              # Utilities
│   ├── Dockerfile
│   ├── package.json
│   └── next.config.ts      # Configuration
│
├── .github/                 # GitHub Actions (planned)
│   └── workflows/
│
├── docker-compose.yml       # Docker orchestration
├── .env.example            # Environment template
├── .gitignore              # Git ignore rules
└── README.md               # This file

Create a .env file in the project root:

# Database
MYSQL_ROOT_PASSWORD=your-super-secret-password
DB_USER=app
DB_PASSWORD=your-app-password
DB_HOST=mysql
DB_NAME=relatorios

# Backend
PORT=3000
NODE_ENV=development

# Frontend (prefix with NEXT_PUBLIC_)
NEXT_PUBLIC_API_URL=http://localhost:3000/api
NEXT_PUBLIC_API_TIMEOUT=30000

# Puppeteer
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

# Feature Flags
NEXT_PUBLIC_ENABLE_EXPORT_PDF=true
NEXT_PUBLIC_ENABLE_SAVE_QUERIES=false

Security Note: Never commit .env to version control.

npm run dev      # Start with hot-reload (ts-node-dev)
npm run build    # Compile TypeScript
npm run start    # Start production build
npm test         # Run tests (planned)

npm run dev      # Start Next.js dev server
npm run build    # Build for production
npm start        # Start production server
npm run lint     # Run ESLint

• Linting: ESLint with TypeScript rules
• Formatting: Prettier (planned)
• Commits: Conventional Commits (enforced)

main           → Production-ready code
develop        → Integration branch
feature/*      → New features
fix/*          → Bug fixes
hotfix/*       → Urgent production fixes

# 1. Create feature branch
git checkout develop
git checkout -b feature/your-feature-name

# 2. Make changes and commit
git add .
git commit -m "feat(scope): description"

# 3. Push and create PR
git push -u origin feature/your-feature-name

# Build all services
docker-compose build

# Build specific service
docker-compose build backend

# Start services
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f backend

# Restart service
docker-compose restart backend

# Execute commands in container
docker-compose exec backend sh
docker-compose exec mysql mysql -u root -p

MySQL data is persisted in a Docker volume:

# View volumes
docker volume ls

# Backup database
docker-compose exec mysql mysqldump -u root -p relatorios > backup.sql

# Restore database
docker-compose exec -T mysql mysql -u root -p relatorios < backup.sql

• Set NODE_ENV=production
• Use strong passwords (16+ chars)
• Enable HTTPS (Nginx + Let's Encrypt)
• Configure firewall rules
• Setup monitoring (Sentry, DataDog)
• Configure backups
• Review security best practices

Please follow these guidelines:

Follow Conventional Commits:

feat(scope): add new feature
fix(scope): fix bug
docs: update documentation
style: format code
refactor: restructure code
test: add tests
chore: maintenance tasks

1. Fork the repository
2. Create your feature branch
3. Make your changes with tests
4. Ensure CI passes
5. Update documentation
6. Submit PR with clear description

• All PRs require 1 approval
• Address review comments
• Keep PRs focused and small

• SEC-05-15: Implement AST-based SQL parsing for query validation
• SEC-05-19: Move JWT storage from localStorage to httpOnly cookies
• SEC-05-18: Enforce strict request payload size limits per endpoint
• SEC-05-16: Implement CSRF protection
• INFRA-04-19: Implement proper secrets management

• SCALE-06-20: Implement Puppeteer browser pooling
• SCALE-06-16: Extract in-memory caches to Redis
• SCALE-06-03: Refactor PDF rendering to background workers
• SCALE-06-06: Implement pagination for query results

• DEBT-07-10: Add unit tests for business logic
• DEBT-07-11: Add integration tests for API endpoints
• DEBT-07-07: Standardize API response envelopes
• INFRA-04-15: Setup CI/CD pipelines (GitHub Actions)

• INFRA-04-11: Setup Nginx reverse proxy with TLS
• INFRA-04-20: Automate database backups
• DEBT-07-15: Implement structured JSON logging (Pino)
• DEBT-07-17: Export APM metrics (latency, pool utilization)

This repository contains proprietary source code and is shared publicly for demonstration and portfolio purposes only.

Unauthorized copying, distribution, or modification is prohibited.

Future licensing terms may change upon product officialization.

• Developer: Alexandre Cavalari (@github)
• Contributors: See CONTRIBUTORS.md

Report bugs via GitHub Issues

• Email: alexandre.cavalari@doqr.com.br

• Wiki (planned)
• API Docs (planned)

• Inspired by Bold Reports
• Built with Express
• UI powered by React
• PDF generation by Puppeteer

Made by Alexandre Cavalari - DoQR