From 5b1909f94309bb978b7760bf11fcf41f5d9b3c43 Mon Sep 17 00:00:00 2001 From: Edwin Eames Date: Sat, 17 Jan 2026 15:40:51 -0500 Subject: [PATCH] readme added --- README.md | 365 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 365 insertions(+) diff --git a/README.md b/README.md index e69de29b..87c9c1c0 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,365 @@ +# 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 ` 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 +} /> +``` + +## 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`