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

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

### 2. Environment Configuration

Copy the example environment file and configure your settings:

```bash
cp .env.example .env
```

Edit `.env` with your actual configuration:

```env
# 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](https://console.cloud.google.com/)
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:

```bash
# 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:

```bash
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:

```bash
# 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)
```bash
npm run setup:nginx
```

#### Manual Setup
1. Install nginx on your system
2. Copy the nginx configuration:
```bash
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):
```bash
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:

```bash
# 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:**
```env
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

```bash
# 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](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