Reporting Platform Prototype

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

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

Features

Current (v0.1.0)

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

Planned (v0.2.0+)

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

Tech Stack

Backend

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

Frontend

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

Infrastructure

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

Getting Started

Prerequisites

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

Quick Start

# 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

Manual Setup (Alternative)

Click to expand

Backend Setup

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

Frontend Setup

cd frontend

# Install dependencies
npm install

# Setup environment
cp .env.example .env

# Start development server
npm run dev

# Frontend available at http://localhost:5173

Database Setup

# 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

Project Structure

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

Environment Variables

Required Variables

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

Optional Variables

# 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.

Development

Available Scripts

Backend

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)

Frontend

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

Code Style

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

Branching Strategy

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

Making Changes

# 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

Docker

Build Images

# Build all services
docker-compose build

# Build specific service
docker-compose build backend

Manage Containers

# 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

Data Persistence

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

Deployment

Production Checklist

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

Deployment Options

AWS (Recommended)

Compute: ECS Fargate or EC2
Database: RDS MySQL
Storage: S3 for PDFs
CDN: CloudFront
Monitoring: CloudWatch

Google Cloud Platform

Compute: Cloud Run or GKE
Database: Cloud SQL
Storage: Cloud Storage
CDN: Cloud CDN

DigitalOcean

Compute: Droplet or App Platform
Database: Managed MySQL
Storage: Spaces

Contributing

Please follow these guidelines:

Commit Messages

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

Pull Request Process

Fork the repository
Create your feature branch
Make your changes with tests
Ensure CI passes
Update documentation
Submit PR with clear description

Code Review

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

Technical Roadmap & Priority Planning

Phase 1: Critical Security & Reliability (Immediate)

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

Phase 2: Performance & Scalability (High Priority)

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

Phase 3: Testing & Maintainability (Medium Priority)

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)

Phase 4: Production Readiness & Observability (Medium Term)

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)

License

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.

Team

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

Support

Issues and Bugs

Report bugs via GitHub Issues

Questions

Email: alexandre.cavalari@doqr.com.br

Documentation

Wiki (planned)
API Docs (planned)

Acknowledgments

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

Stats

Made by Alexandre Cavalari - DoQR

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.agents/rules		.agents/rules
.github/workflows		.github/workflows
.vscode		.vscode
backend		backend
docker/mysql		docker/mysql
docs		docs
frontend		frontend
frontend_old		frontend_old
shared/types		shared/types
.czrc		.czrc
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmessage		.gitmessage
.prettierrc		.prettierrc
README.md		README.md
REFACTORING_LOG.md		REFACTORING_LOG.md
TECHNICAL_ANALYSIS.md		TECHNICAL_ANALYSIS.md
TESTING.md		TESTING.md
commitlint.config.js		commitlint.config.js
docker-compose.yml		docker-compose.yml
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Reporting Platform Prototype

Table of Contents

Overview

Features

Current (v0.1.0)

Planned (v0.2.0+)

Tech Stack

Backend

Frontend

Infrastructure

Getting Started

Prerequisites

Quick Start

Manual Setup (Alternative)

Backend Setup

Frontend Setup

Database Setup

Project Structure

Environment Variables

Required Variables

Optional Variables

Development

Available Scripts

Backend

Frontend

Code Style

Branching Strategy

Making Changes

Docker

Build Images

Manage Containers

Data Persistence

Deployment

Production Checklist

Deployment Options

Contributing

Commit Messages

Pull Request Process

Code Review

Technical Roadmap & Priority Planning

Phase 1: Critical Security & Reliability (Immediate)

Phase 2: Performance & Scalability (High Priority)

Phase 3: Testing & Maintainability (Medium Priority)

Phase 4: Production Readiness & Observability (Medium Term)

License

Team

Support

Issues and Bugs

Questions

Documentation

Acknowledgments

Stats

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages