fibdash/README.md

FibDash

A modern React Material-UI dashboard application with Google SSO authentication and MSSQL database integration.

Features

• 🚀 React 18 with class components
• 🎨 Material-UI (MUI) for beautiful, modern UI
• 🔐 Google SSO Authentication
• 🗄️ MSSQL Database integration
• ⚡ Webpack Dev Server with Hot Module Reload
• 🔄 Express API with hot reload via nodemon
• 🛡️ JWT Authentication for API security
• 📱 Responsive Design
• 🎯 Production Ready build configuration

Architecture

fibdash/
├── client/                 # Frontend React application
│   ├── src/
│   │   ├── components/     # React class components
│   │   ├── services/       # API service classes
│   │   ├── App.js          # Main application component
│   │   └── index.js        # React entry point
│   └── public/
│       └── index.html      # HTML template
├── src/                    # Backend Express API
│   ├── config/             # Database configuration
│   ├── middleware/         # Authentication middleware
│   ├── routes/             # API routes
│   ├── database/           # Database schema
│   └── index.js            # Express server entry point
├── webpack.config.js       # Webpack configuration
└── package.json            # Dependencies and scripts

Prerequisites

• Node.js (v16 or higher)
• MSSQL Server instance
• Google Cloud Platform account for OAuth setup

Setup Instructions

1. Clone and Install Dependencies

git clone <your-repo-url>
cd fibdash
npm install

2. Environment Configuration

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env with your actual configuration:

# Google OAuth Configuration
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here

# Frontend Environment Variables (REACT_APP_ prefix required)
REACT_APP_GOOGLE_CLIENT_ID=your_google_client_id_here

# JWT Secret (generate a secure random string)
JWT_SECRET=your_jwt_secret_here

# MSSQL Database Configuration
DB_SERVER=your_mssql_server_here
DB_DATABASE=your_database_name_here
DB_USERNAME=your_db_username_here
DB_PASSWORD=your_db_password_here
DB_PORT=1433

# Server Configuration
PORT=5000
NODE_ENV=development

3. Google OAuth Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google+ API
4. Create OAuth 2.0 credentials:
   • Application type: Web application
   • Authorized JavaScript origins: http://localhost:3000
   • Authorized redirect URIs: http://localhost:3000
5. Copy the Client ID and Client Secret to your .env file

4. Database Setup

1. Create a new MSSQL database
2. Run the schema creation script:

# Connect to your MSSQL server and run:
sqlcmd -S your_server -d your_database -i src/database/schema.sql

Or manually execute the SQL commands in src/database/schema.sql

5. Start Development Servers

Run both frontend and backend development servers:

npm run dev

This will start:

• Frontend dev server on http://localhost:5001 (with hot reload)
• Backend API server on http://localhost:5000 (with nodemon auto-restart)

Or run them separately:

# Frontend only
npm run dev:frontend

# Backend only  
npm run dev:backend

6. Optional: Nginx Setup for Development

For a more production-like development environment, you can set up nginx as a reverse proxy:

Automatic Setup (Linux/macOS)

npm run setup:nginx

Manual Setup

1. Install nginx on your system
2. Copy the nginx configuration:

sudo cp nginx.simple.conf /etc/nginx/sites-available/fibdash-dev
sudo ln -s /etc/nginx/sites-available/fibdash-dev /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

3. Add to your hosts file (optional):

echo "127.0.0.1 fibdash.local" | sudo tee -a /etc/hosts

With nginx setup, you can access:

• Main app: http://localhost/ or http://fibdash.local/
• API: http://localhost/api/ or http://fibdash.local/api/
• Direct Frontend: http://localhost:5001/
• Direct Backend: http://localhost:5000/

Production Nginx Setup

For production deployment, use the production nginx configuration:

# Copy production nginx config
sudo cp nginx.prod.conf /etc/nginx/sites-available/fibdash-prod
sudo ln -s /etc/nginx/sites-available/fibdash-prod /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

The production config includes:

• Security headers (CSP, XSS protection, etc.)
• Static asset caching (1 year for JS/CSS/images)
• Gzip compression for better performance
• SSL/HTTPS support (commented out, ready to enable)

Email Authorization

FibDash includes built-in email authorization to restrict access to specific users.

Setup Authorization

1. Add authorized emails to your .env file:

AUTHORIZED_EMAILS=admin@yourcompany.com,user1@yourcompany.com,user2@yourcompany.com

2. First email is admin: The first email in the list automatically gets admin privileges

3. No authorization: If AUTHORIZED_EMAILS is not set or empty, NO USERS can access the app

Admin Features

Admins (first email in the authorized list) can:

• View all authorized emails: GET /api/admin/authorized-emails
• Add new authorized email: POST /api/admin/authorized-emails
• Remove authorized email: DELETE /api/admin/authorized-emails/:email
• View system info: GET /api/admin/system-info

Note: Admin changes via API are temporary. For permanent changes, update the .env file.

Authorization Flow

1. User signs in with Google
2. Backend checks if email is in AUTHORIZED_EMAILS list
3. If authorized → login succeeds
4. If not authorized → "Access denied" error
5. All API endpoints check authorization via middleware

Development

Frontend Development

• Frontend code is in the client/ directory
• Uses Webpack dev server with hot module reload
• All components are class components (no function components)
• Material-UI for styling and components
• Authentication handled via Google SSO

Backend Development

• Backend code is in the src/ directory
• Express.js API server with CORS enabled
• JWT authentication middleware
• MSSQL database integration
• Auto-restart on file changes via nodemon

API Endpoints

• POST /api/auth/google - Google OAuth login
• GET /api/auth/verify - Verify JWT token
• POST /api/auth/logout - Logout user
• GET /api/dashboard - Get dashboard data
• GET /api/dashboard/user - Get user-specific data
• GET /api/health - Health check

Available Scripts

Script	Description
npm run dev	Start both frontend and backend in development mode
npm run dev:frontend	Start only the frontend webpack dev server
npm run dev:backend	Start only the backend API server with nodemon
npm run build	Create production build of frontend
npm run build:prod	Build and start production server
npm start	Build frontend and start production server
npm run start:prod	Start production server (assumes build exists)
npm run setup:nginx	Automatically setup nginx for development
npm run nginx:test	Test nginx configuration
npm run nginx:reload	Reload nginx configuration
npm run nginx:start	Start nginx service
npm run nginx:stop	Stop nginx service
npm run nginx:status	Check nginx service status

Production Deployment

Single-Process Production Setup

In production, the Express backend builds the React frontend and serves it as static files. No separate frontend server is needed.

Build and Start Production Server

# Build frontend and start server in one command
npm start

# Or build and start separately
npm run build
npm run start:prod

Production Architecture

Production Setup:
┌─────────────────────────────────────┐
│ Single Express Server (Port 5000)  │
├─────────────────────────────────────┤
│ • Serves static React files        │
│ • Handles API routes (/api/*)      │
│ • Manages authentication           │
│ • Connects to MSSQL database       │
└─────────────────────────────────────┘

Production Features

• Single Process: One Node.js server handles everything
• Static File Serving: Built React app served with caching headers
• Optimized Build: Minified JS/CSS with content hashing
• Code Splitting: Vendor libraries separated for better caching
• Production Security: CSP headers and security optimizations

Project Structure Details

Frontend (client/)

• Components: All React components using class-based architecture
• Services: API communication classes
• Material-UI: Modern UI components with custom theming
• Hot Reload: Webpack dev server with HMR enabled

Backend (src/)

• Express Server: RESTful API with middleware
• Authentication: Google OAuth + JWT tokens
• Database: MSSQL with connection pooling
• Hot Reload: Nodemon for automatic server restart

Environment Variables

Variable	Description	Required
GOOGLE_CLIENT_ID	Google OAuth Client ID (backend)	Yes
GOOGLE_CLIENT_SECRET	Google OAuth Client Secret (backend)	Yes
REACT_APP_GOOGLE_CLIENT_ID	Google OAuth Client ID (frontend)	Yes
JWT_SECRET	Secret for JWT token signing	Yes
AUTHORIZED_EMAILS	Comma-separated list of authorized email addresses	No*
DB_SERVER	MSSQL server address	Yes
DB_DATABASE	Database name	Yes
DB_USERNAME	Database username	Yes
DB_PASSWORD	Database password	Yes
DB_PORT	Database port (default: 1433)	No
PORT	API server port (default: 5000)	No
NODE_ENV	Environment mode	No

*If AUTHORIZED_EMAILS is not set or empty, NO USERS can access the application. Only email addresses listed in AUTHORIZED_EMAILS can log in.

Troubleshooting

Database Connection Issues

1. Verify your MSSQL server is running and accessible
2. Check firewall settings allow connections on port 1433
3. Ensure your database credentials are correct
4. Check the server logs for detailed error messages

Google OAuth Issues

1. Verify your Google Client ID is correctly set
2. Check that your domain is authorized in Google Cloud Console
3. Ensure the OAuth consent screen is configured
4. Make sure you're testing on the correct domain/port

For detailed Google OAuth troubleshooting, see: docs/GOOGLE_OAUTH_SETUP.md

Common fixes for CORS/GSI errors:

• Add your domain to Google Cloud Console authorized origins
• Ensure both GOOGLE_CLIENT_ID and REACT_APP_GOOGLE_CLIENT_ID are set
• Use the "Alternative Google Sign-In" button as fallback
• Consider enabling HTTPS for better OAuth compatibility

Hot Reload Not Working

1. Check that both dev servers are running
2. Verify webpack proxy configuration
3. Clear browser cache and restart dev servers

License

ISC