frontend/README.md

# Auburn Oil Customer Gateway - Frontend

A modern, responsive customer portal for Auburn Oil's heating oil delivery service. Built with React and Ant Design for a professional, user-friendly experience.

```
 ______              _                    _
|  ____|            | |                  | |
| |__ _ __ ___  _ __| |_ ___ _ __   ____ | |
|  __| '__/ _ \| '_ \ __/ _ \ '_ \ / _  || |
| |  | | | (_) | | | | ||  __/ | | | (_| ||_|
|_|  |_|  \___/|_| |_|\__\___|_| |_|\__,_|(_)

      Auburn Oil Customer Portal
```

## What This Does

A self-service portal where Auburn Oil customers can:

| Feature | Description |
|---------|-------------|
| **Place Orders** | Order heating oil delivery with real-time pricing |
| **View Deliveries** | Track delivery history and status |
| **Manage Payments** | Save, update, and remove credit cards securely |
| **Tank Photos** | Upload annual tank inspection images |
| **Account Management** | Update profile, change password |

## Screenshots

### Customer Dashboard
- Current oil pricing at a glance
- Recent delivery history with status indicators
- Tank inspection photo preview
- Quick access to place new orders

### New Customer Registration
- 3-step wizard for easy onboarding
- Tank photo upload with preview
- Automatic account number generation

## Tech Stack

- **Framework**: React 18.2 with Hooks
- **UI Library**: Ant Design 5.12 (enterprise-grade components)
- **Routing**: React Router DOM 6.21
- **HTTP Client**: Axios with interceptors
- **Build Tool**: Vite 5.0 (lightning-fast HMR)
- **Date Handling**: Day.js

## Quick Start

### Prerequisites

- Node.js 18+ (or use Docker)
- API server running (see `/api/README.md`)

### Option 1: Docker (Recommended)

**Development** (with hot-reload):
```bash
cd deploy
docker compose -f docker-compose.dev.yml up frontend_dev --build
```

**Production**:
```bash
cd deploy
docker compose -f docker-compose.prod.yml up frontend_prod --build
```

### Option 2: Local Development

```bash
# Install dependencies
npm install

# Configure API endpoint
cp .env.dev .env.local
# Edit .env.local if needed

# Start dev server
npm run dev
```

### Access the Portal

| Environment | URL | Notes |
|-------------|-----|-------|
| Development | http://localhost:5173 | Vite dev server with HMR |
| Local | http://localhost:80 | Docker nginx |
| Production | https://portal.auburnoil.com | Production build |

## Project Structure

```
frontend/
├── src/
│   ├── main.jsx           # App entry point
│   ├── App.jsx            # Root component with routing
│   ├── pages/
│   │   ├── Index.jsx      # Dashboard (logged in) / Welcome (logged out)
│   │   ├── Login.jsx      # Login form
│   │   ├── Register.jsx   # Existing customer registration
│   │   ├── New.jsx        # New customer wizard (3 steps)
│   │   ├── Order.jsx      # Place delivery order
│   │   ├── Tank.jsx       # Tank photo upload
│   │   ├── Payments.jsx   # Payment method management
│   │   ├── EditCustomer.jsx    # Edit profile
│   │   ├── ChangePassword.jsx  # Change password
│   │   ├── ForgotPassword.jsx  # Request reset
│   │   └── ResetPassword.jsx   # Complete reset
│   ├── components/
│   │   └── Navbar.jsx     # Navigation with auth state
│   └── utils/
│       └── api.js         # Axios instance with auth interceptor
├── public/                # Static assets
├── .env.dev               # Development config
├── .env.local             # Local network config
├── .env.prod              # Production config
├── Dockerfile.dev         # Development container
├── Dockerfile.local       # Local network container
├── Dockerfile.prod        # Production container (nginx)
├── vite.config.js         # Vite configuration
└── package.json           # Dependencies
```

## Pages & Features

### Dashboard (`/`)

**Logged Out:**
- Welcome message
- Links to login and registration

**Logged In:**
- Customer information card
- Current oil price display
- Tank inspection photos (latest 3 images)
- Delivery history table with:
  - Date, gallons, price, status
  - Visual status indicators (green = waiting, gold glow = out for delivery)
- Emergency delivery contact information

### Login (`/login`)
- Email/password authentication
- "Forgot password" link
- Registration link for new users

### Registration (`/register`)
- For existing Auburn Oil customers
- Requires: Account number + House number (verification)
- Creates portal login credentials

### New Customer (`/new`)
- **Step 1**: Customer information (name, address, contact)
- **Step 2**: Create account (email, password)
- **Step 3**: Upload 3 tank inspection photos
- Auto-generates account number (AO-XXXXXX format)

### Place Order (`/order`)
- Select delivery date
- Enter gallons (minimum 100)
- Real-time price calculation
- Payment method selection
- Order confirmation

### Tank Photos (`/tank`)
- Upload new inspection photos (3 required)
- View photo history by date
- Image preview before upload

### Payments (`/payments`)
- View saved cards (masked numbers)
- Add new payment method
- Edit card details
- Remove cards
- Set default payment method

### Profile Management
- **Edit Customer** (`/edit-customer`): Update address, phone
- **Change Password** (`/change-password`): Update password
- **Forgot Password** (`/forgot-password`): Request reset email
- **Reset Password** (`/reset-password`): Complete reset with token

## Environment Configuration

### Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `VITE_BASE_URL` | API server URL | `http://localhost:8000` |

### Environment Files

```bash
# .env.dev - Development
VITE_BASE_URL=http://localhost:8000

# .env.local - Local network testing
VITE_BASE_URL=http://192.168.1.204:8000

# .env.prod - Production
VITE_BASE_URL=https://api.portal.auburnoil.com
```

## Development Guide

### Available Scripts

```bash
# Start development server (hot-reload)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint
```

### API Integration

The app uses a centralized Axios instance (`/utils/api.js`) that:

1. Sets the base URL from environment
2. Automatically attaches JWT token to requests
3. Handles authentication headers

```javascript
// Example usage in components
import api from '../utils/api';

// GET request
const response = await api.get('/info/deliveries');

// POST request
const response = await api.post('/order/', { gallons: 150, date: '2024-01-15' });
```

### Authentication Flow

1. User logs in via `/auth/login`
2. JWT token stored in `localStorage`
3. Axios interceptor adds `Authorization: Bearer <token>` to all requests
4. Protected routes check for token presence
5. Logout clears token and redirects to login

### Adding New Pages

1. Create component in `/src/pages/`
2. Add route in `App.jsx`
3. Update navbar if needed

```jsx
// App.jsx
<Route path="/new-page" element={<NewPage />} />
```

## Styling

### Ant Design Theme

The app uses Ant Design's default theme with custom overrides:

- Primary color: Auburn Oil brand colors
- Responsive breakpoints for mobile/desktop
- Card-based layout for information sections

### Responsive Design

- Mobile-first approach
- Breakpoint-aware layouts using Ant Design Grid
- Tables convert to cards on mobile
- Touch-friendly form inputs

## Deployment

### Docker Production Build

The production Dockerfile:
1. Builds React app with Vite
2. Serves static files via nginx
3. Configures routing for SPA

```bash
# Build and run production container
docker build -f Dockerfile.prod -t customer-portal .
docker run -p 80:80 customer-portal
```

### Manual Production Build

```bash
# Build static files
npm run build

# Output in /dist folder
# Serve with any static file server (nginx, Apache, etc.)
```

### nginx Configuration

For SPA routing, ensure nginx redirects all routes to `index.html`:

```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

## Troubleshooting

### Common Issues

**API connection failed**
```
- Check VITE_BASE_URL in .env file
- Ensure API server is running
- Check for CORS errors in browser console
- Verify network connectivity
```

**Login not working**
```
- Clear localStorage and try again
- Check browser console for errors
- Verify API is returning valid JWT
```

**Images not loading**
```
- Check API /images endpoint is accessible
- Verify tank images exist in API volume
- Check browser network tab for 404s
```

**Build fails**
```
- Delete node_modules and reinstall: rm -rf node_modules && npm install
- Clear Vite cache: rm -rf .vite
- Check Node.js version (18+ required)
```

### Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## Security Notes

- JWT tokens stored in localStorage (ensure HTTPS in production)
- All API calls go through authenticated endpoints
- Credit card data never stored locally (handled by Authorize.net)
- Image uploads validated on server side

---

**Auburn Oil Customer Gateway** - Empowering customers with self-service convenience.

For API documentation, see `/api/README.md`