📊 EPIModel Next - Epidemiological Model Visualization System

Web system for visualization and simulation of COVID-19 epidemiological models in Paraguay

Features • Installation • Usage • Architecture • Contributing

📑 Table of Contents

Description
Features
Technologies
Prerequisites
Installation
Production Configuration
Configuration
Usage
Architecture
Project Structure
Available Scripts
Deployment
Contributing
License
Additional Documentation

🎯 Description

EPIModel Next is a modern web application developed to visualize and simulate COVID-19 epidemiological models in Paraguay. The application allows users to:

Visualize projections of reported cases, hospitalizations, intensive care, and deaths
Simulate scenarios with different epidemiological parameters (Rt, UCI threshold, V filtered, lambda I to H)
Analyze data through interactive charts built with D3.js
Export data in CSV format for external analysis

The application is built with Next.js 12, TypeScript, Redux Toolkit for state management, and D3.js for data visualization. It includes multi-language support (Spanish and English) and is optimized for performance and accessibility.

✨ Features

📈 Data Visualization

Interactive Charts: Visualization of epidemiological data with D3.js
Multiple Scenarios: Comparison of different epidemiological scenarios
Filters and Configuration: Customization of visualizations with multiple options
Date Ranges: Selection of time ranges for analysis
Uncertainty: Visualization of uncertainty intervals in projections

🧪 Model Simulation

Customizable Parameters:
- Rt (Reproductive Number): Single value or time series
- UCI Threshold: Intensive care capacity threshold
- V Filtered: Filtration parameter
- Lambda I to H: Transition rate from infected to hospitalized
Real-Time Execution: Simulations executed on the backend
Result Visualization: Multiple simultaneous simulation charts

🌐 Internationalization

Multi-Language Support: Spanish and English
Dynamic Change: Language change without page reload
Localized Formatting: Dates and numbers formatted according to language

🎨 User Interface

Responsive Design: Optimized for desktop, tablet, and mobile
Consistent Theme: Coherent design with Tailwind CSS
Accessibility: WCAG standards compliance
Error Handling: Robust error handling with user-friendly messages

⚡ Performance

Server-Side Rendering: Server-side rendering for better SEO
Code Splitting: On-demand component loading
Image Optimization: Automatic image optimization
Caching: Intelligent API request caching

🛠️ Technologies

Core

Next.js 12.1.5 - React framework for production
React 18.1.0 - UI library
TypeScript 5.0.0 - Typed programming language

State and Data

Redux Toolkit 1.8.3 - State management
Axios 0.27.2 - HTTP client
D3.js 7.4.4 - Data visualization

Styles and UI

Tailwind CSS 3.0.24 - Utility-first CSS framework
Headless UI 1.6.0 - Unstyled UI components
Heroicons 1.0.6 - SVG icons
Font Awesome 6.1.1 - Additional icons

Internationalization

next-i18next 12.0.1 - Internationalization for Next.js

Utilities

Lodash 4.17.21 - JavaScript utilities
file-saver 2.0.5 - File saving
react-csv 2.2.2 - CSV export
js-cookie 3.0.1 - Cookie handling

📋 Prerequisites

Before starting, make sure you have installed:

Node.js 16.x or higher
Yarn 1.x or higher (package manager)
Git for version control

Verify Installation

node --version  # Should be v16.x or higher
yarn --version  # Should be 1.x or higher
git --version   # Any recent version

🚀 Installation

1. Clone the Repository

git clone https://github.com/tu-usuario/epimodel-next.git
cd epimodel-next

2. Install Dependencies

yarn install

3. Configure Environment Variables (Optional)

Note: The API_URL is automatically configured based on NODE_ENV:

Development (yarn dev): http://localhost:3001

Production (yarn build && yarn start): http://epymodel.uaa.edu.py:3001

You only need to create .env.local if you want to customize the configuration.

Create a .env.local file in the project root (optional):

cp .env.example .env.local

Edit .env.local only if you need to customize values:

# API Configuration (Optional - automatically determined by NODE_ENV)
# NEXT_PUBLIC_API_URL=http://localhost:3001  # Only if you need to override
NEXT_PUBLIC_API_TIMEOUT=30000
NEXT_PUBLIC_API_RETRY_ATTEMPTS=3

# Environment (automatic - no need to configure)
# NODE_ENV=development  # Next.js configures this automatically

# Feature Flags
NEXT_PUBLIC_DEBUG_LOGS=false
NEXT_PUBLIC_ERROR_REPORTING=false

4. Start Development Server

yarn dev

The application will be available at http://localhost:3000

🚀 Production Configuration

Create Production Environment File

For production, you can create a .env.production file or configure environment variables on your deployment platform.

Option 1: `.env.production` File (Local)

Create a .env.production file in the project root:

cp .env.example .env.production

Edit .env.production with production values:

# API Configuration
# API_URL is automatically configured as http://epymodel.uaa.edu.py:3001
# when NODE_ENV=production, but you can override if necessary
# NEXT_PUBLIC_API_URL=http://epymodel.uaa.edu.py:3001

# API request timeout (ms)
NEXT_PUBLIC_API_TIMEOUT=30000

# Retry attempts
NEXT_PUBLIC_API_RETRY_ATTEMPTS=3

# Production Feature Flags
NEXT_PUBLIC_DEBUG_LOGS=false
NEXT_PUBLIC_ERROR_REPORTING=true

# NODE_ENV is automatically set when running yarn build
# No need to define it manually

Option 2: Environment Variables on Deployment Platform

Vercel:

Go to your project in Vercel
Settings → Environment Variables
Add the variables:
- NEXT_PUBLIC_API_URL (optional, automatically configured)
- NEXT_PUBLIC_API_TIMEOUT (optional)
- NEXT_PUBLIC_API_RETRY_ATTEMPTS (optional)
- NEXT_PUBLIC_DEBUG_LOGS=false
- NEXT_PUBLIC_ERROR_REPORTING=true
- NODE_ENV=production (automatic)

Netlify:

Go to Site settings → Build & deploy → Environment
Add environment variables (same as Vercel)

Docker:

# Use environment variables when running the container
docker run -p 3000:3000 \
  -e NODE_ENV=production \
  -e NEXT_PUBLIC_DEBUG_LOGS=false \
  -e NEXT_PUBLIC_ERROR_REPORTING=true \
  epimodel-next

VPS/Cloud Server:

# Create .env.production file
nano .env.production

# Or export variables before running
export NODE_ENV=production
export NEXT_PUBLIC_DEBUG_LOGS=false
export NEXT_PUBLIC_ERROR_REPORTING=true

# Then run
yarn build
yarn start

Build and Deploy for Production

# 1. Build the application (NODE_ENV is automatically set to 'production')
yarn build

# 2. Start production server
yarn start

# The application will automatically use:
# - API_URL: http://epymodel.uaa.edu.py:3001
# - NODE_ENV: production

Verify Production Configuration

To verify that the configuration is correct:

# In development, you will see in the logs:
# API_URL: http://localhost:3001

# In production, you will see in the logs:
# Production mode: Using API URL: http://epymodel.uaa.edu.py:3001

Configuration Summary by Environment

Environment	NODE_ENV	API_URL	Debug Logs	Error Reporting
Development	`development`	`http://localhost:3001`	`false` (optional)	`false` (optional)
Production	`production`	`http://epymodel.uaa.edu.py:3001`	`false`	`true` (recommended)
Test	`test`	`http://localhost:3001`	`false`	`false`

Important note: The API_URL is automatically configured based on NODE_ENV. You don't need to define it manually unless you need to use a different URL.

⚙️ Configuration

Environment Variables

Variable	Description	Default Value	Required
`NEXT_PUBLIC_API_URL`	Backend API URL	Automatic based on NODE_ENV - Development: `http://localhost:3001` - Production: `http://epymodel.uaa.edu.py:3001`	No
`NEXT_PUBLIC_API_TIMEOUT`	API request timeout (ms)	`30000`	No
`NEXT_PUBLIC_API_RETRY_ATTEMPTS`	Retry attempts for failed requests	`3`	No
`NEXT_PUBLIC_DEBUG_LOGS`	Enable debug logs	`false`	No
`NEXT_PUBLIC_ERROR_REPORTING`	Enable error reporting	`false`	No
`NODE_ENV`	Execution mode	Automatic (Next.js configures it) - `development` (yarn dev) - `production` (yarn build)	No

Important note: The API_URL is automatically configured based on the environment. You only need to define NEXT_PUBLIC_API_URL if you want to use a different URL than the default.

Next.js Configuration

The next.config.js file contains the Next.js configuration:

const { i18n } = require("./next-i18next.config");

module.exports = {
  reactStrictMode: false,
  i18n,
};

TypeScript Configuration

The tsconfig.json file contains the TypeScript configuration. It is recommended to enable strict mode for better type safety.

Tailwind CSS Configuration

The tailwind.config.js file contains the Tailwind CSS configuration with custom themes.

💻 Usage

Main Page (Charts)

The main page displays epidemiological projection charts:

Reported Cases: Projection of reported COVID-19 cases
Hospitalized: Projection of hospitalized cases
Intensive Care (UCI): Projection of UCI cases
Deaths: Projection of deaths

Chart Features

Line Selection: Show/hide different data lines
Visualization Configuration:
- Line smoothing
- Show/hide uncertainty
- Show/hide data points
Date Range: Select date range to visualize
Export: Download data in CSV format

Simulator Page

The simulator page allows executing simulations with custom parameters:

Simulation Parameters

Rt (Reproductive Number)
- Single value: Decimal number
- Time series: Comma-separated list of values
UCI Threshold
- Intensive care capacity threshold
V Filtered
- Filtration parameter
Lambda I to H
- Transition rate from infected to hospitalized

Execute Simulation

Enter parameters in the form
Click "Execute Simulation"
Wait for the simulation to complete
View results in the charts

Simulation Charts

The following charts are automatically generated:

Cumulative: Cumulative cases
Cumulative Deaths: Cumulative deaths
Exposed: Exposed cases
Hospitalized: Hospitalized cases
Immune: Immune cases
Infectious: Infectious cases
Susceptible: Susceptible cases
UCI: Intensive care cases

🏗️ Architecture

For detailed information about the project architecture, see the ARCHITECTURE.md document.

Architecture Summary

The project follows a layered architecture:

Presentation Layer: React components
Business Logic Layer: Hooks and Reducers
Service Layer: API client
Data Layer: Types and State

Data Flow

API Service → Redux Action → Reducer → Selector → Component

Design Patterns

Container/Presentational Pattern: Separation of logic and presentation
Custom Hooks Pattern: Reusable logic
Service Layer Pattern: Centralized API client
Redux Toolkit Slice Pattern: State management

📂 Project Structure

epimodel-next/
├── components/          # React components
│   ├── ErrorBoundary/  # Error handling
│   ├── Layout/         # Layout components
│   ├── MainGraph/      # Main charts
│   ├── SimulationGraph/# Simulation charts
│   └── utils/          # Utility components
│
├── pages/              # Next.js pages
│   ├── _app.tsx       # Global configuration
│   ├── index.tsx      # Main page
│   └── Simulador.tsx  # Simulator page
│
├── store/              # Redux store
│   ├── store.ts       # Store configuration
│   └── reducers/      # Reducers
│
├── services/           # API services
│   └── api.ts         # HTTP client
│
├── hooks/              # Custom hooks
│   ├── useApi.ts      # API hook
│   └── ...            # Other hooks
│
├── types/              # TypeScript types
│   └── api.ts         # API types
│
├── utils/              # Utilities
│   ├── constants.ts   # Constants
│   └── ...            # Other utilities
│
├── config/             # Configuration
│   └── environment.ts # Environment variables
│
├── docs/               # Documentation
│   ├── ARCHITECTURE.md            # Project architecture
│   ├── CODE_QUALITY.md            # Code quality report
│   └── IMPLEMENTATION_SUMMARY.md  # Implementation summary
│
├── styles/             # Styles
│   └── globals.css    # Global styles
│
├── public/             # Static files
│   ├── assets/        # Images and icons
│   └── locales/       # Translations
│
└── nginx/              # Nginx configuration

📜 Available Scripts

Development

# Start development server
yarn dev

# Build for production
yarn build

# Start production server
yarn start

# Run linter
yarn lint

Production

# Build application
yarn build

# Start production server
yarn start

🐳 Deployment

Docker

The project includes Docker configuration for container deployment.

Build Image

docker build -t epimodel-next .

Run Container

Without environment variables (uses automatic configuration):

docker run -p 3000:3000 epimodel-next

With custom environment variables:

docker run -p 3000:3000 \
  -e NODE_ENV=production \
  -e NEXT_PUBLIC_DEBUG_LOGS=false \
  -e NEXT_PUBLIC_ERROR_REPORTING=true \
  -e NEXT_PUBLIC_API_TIMEOUT=30000 \
  epimodel-next

With .env.production file:

docker run -p 3000:3000 --env-file .env.production epimodel-next

Docker Compose

# Uses environment variables defined in docker-compose.yml
docker-compose up -d

docker-compose.yml example:

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_DEBUG_LOGS=false
      - NEXT_PUBLIC_ERROR_REPORTING=true
    # API_URL is automatically configured

Vercel

The project is configured for deployment on Vercel:

Connect your repository to Vercel
Configure environment variables in Settings → Environment Variables:
```
NEXT_PUBLIC_DEBUG_LOGS=false
NEXT_PUBLIC_ERROR_REPORTING=true
NEXT_PUBLIC_API_TIMEOUT=30000
NEXT_PUBLIC_API_RETRY_ATTEMPTS=3
```
Note: NODE_ENV and NEXT_PUBLIC_API_URL are automatically configured
Deploy automatically

Automatic configuration on Vercel:

NODE_ENV=production is automatically set during build
NEXT_PUBLIC_API_URL is automatically configured as http://epymodel.uaa.edu.py:3001

Other Platforms

The project can be deployed on any platform that supports Next.js:

Netlify

Connect your repository to Netlify
Configure environment variables in Site settings → Build & deploy → Environment:
```
NEXT_PUBLIC_DEBUG_LOGS=false
NEXT_PUBLIC_ERROR_REPORTING=true
```
Build command: yarn build
Publish directory: .next
NODE_ENV and NEXT_PUBLIC_API_URL are automatically configured

AWS Amplify

Connect your repository to AWS Amplify

Add environment variables in the Amplify console:

NEXT_PUBLIC_DEBUG_LOGS=false
NEXT_PUBLIC_ERROR_REPORTING=true

Build settings (automatic for Next.js)
NODE_ENV=production is automatically set

Azure App Service

Create an App Service in Azure
Configure environment variables in Configuration → Application settings:
```
NEXT_PUBLIC_DEBUG_LOGS=false
NEXT_PUBLIC_ERROR_REPORTING=true
```
NODE_ENV=production is automatically set

Heroku

Create an app in Heroku

Configure environment variables:

heroku config:set NEXT_PUBLIC_DEBUG_LOGS=false
heroku config:set NEXT_PUBLIC_ERROR_REPORTING=true
heroku config:set NODE_ENV=production

Deploy:
```
git push heroku main
```

VPS Server (Linux)

Clone the repository on the server
Install dependencies: yarn install
Create .env.production file:
```
nano .env.production
```

Add environment variables:

NEXT_PUBLIC_DEBUG_LOGS=false
NEXT_PUBLIC_ERROR_REPORTING=true
NEXT_PUBLIC_API_TIMEOUT=30000
NEXT_PUBLIC_API_RETRY_ATTEMPTS=3

Build and run:

yarn build
NODE_ENV=production yarn start

Use PM2 for persistent process:

npm install -g pm2
pm2 start npm --name "epimodel-next" -- start
pm2 save
pm2 startup

🧪 Testing

Run Tests

# Run all tests
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage
yarn test:coverage

Test Structure

__tests__/
├── components/    # Component tests
├── hooks/         # Hook tests
├── services/      # Service tests
└── utils/         # Utility tests

🤝 Contributing

Contributions are welcome. Please:

Fork the project
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Contribution Guide

Follow the project's code conventions
Write tests for new features
Update documentation
Keep commits descriptive

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

👥 Authors

Nery Cano - LinkedIn

🙏 Acknowledgments

Universidad Autónoma de Asunción (UAA)
Backend development team
Next.js community
Contributors of the libraries used

📞 Contact

For questions or suggestions, please contact:

Email: tu-email@example.com
Website: http://epymodel.uaa.edu.py

🔗 Useful Links

📚 Additional Documentation

For more information about the project, see the additional documentation in the docs/ folder:

ARCHITECTURE.md - Complete project architecture documentation
CODE_QUALITY.md - Code quality report and metrics
IMPLEMENTATION_SUMMARY.md - Implementation summary and improvements

Note: For API information, see the Architecture section and the services/api.ts file which contains complete API service documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 88 Commits
.vscode		.vscode
components		components
config		config
docs		docs
hooks		hooks
nginx		nginx
pages		pages
public		public
services		services
store		store
styles		styles
types		types
utils		utils
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
next-i18next.config.js		next-i18next.config.js
next.config.js		next.config.js
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation