🎨 Autonova Frontend - React Application

Modern, responsive frontend for the Autonova automobile service management platform

Features • Tech Stack • Quick Start • Development

---

📋 Table of Contents

• Overview
• Features
• Tech Stack
• Quick Start
• Project Structure
• Development
• Authentication
• State Management
• Styling Guide
• Building
• Testing
• Docker
• Troubleshooting

---

🎯 Overview

The Autonova frontend is a modern single-page application (SPA) built with React 18 and TypeScript. It provides role-based dashboards for customers, employees, and administrators to manage vehicle services, appointments, time tracking, and billing. The application uses Vite for lightning-fast development, Tailwind CSS for styling, and shadcn/ui for beautiful, accessible UI components.

Key Highlights:

• 🎨 Modern UI/UX - Beautiful interface with Tailwind CSS + shadcn/ui
• 🔐 Secure Authentication - JWT + OAuth2 Google login integration
• 📱 Fully Responsive - Mobile-first design that works on all devices
• ⚡ Lightning Fast - Vite HMR for instant feedback during development
• 🎯 Type-Safe - Full TypeScript support with strict mode
• 📊 Real-time Updates - Live data synchronization with TanStack Query
• 🧩 Component Library - 50+ reusable shadcn/ui components
• 🚀 Optimized Build - Production builds with code splitting

---

✨ Features

For All Users:

• 🔐 Authentication - Login, signup, password recovery, Google OAuth2
• 👤 Profile Management - Update personal information and settings
• 🔔 Notifications - Real-time alerts and notifications
• 🌓 Theme Support - Light/dark mode (ready for implementation)

Customer Dashboard:

• 📅 Appointment Booking - Schedule vehicle services with date/time picker
• 🚗 Vehicle Management - Add, edit, and track multiple vehicles
• 📊 Service Tracking - Real-time progress updates on services
• 💳 Billing & Invoices - View, download, and pay invoices
• 📧 Communication - Message service center directly

Employee Dashboard:

• ⏱️ Time Logging - Start/stop timers for tasks with smart tracking
• 📋 Task Management - View and manage assigned tasks
• 📈 Performance Metrics - Weekly summaries, efficiency meters
• 🎯 Smart Suggestions - AI-powered task recommendations
• 📊 Analytics - Personal productivity insights

Admin Dashboard:

• 👥 User Management - CRUD operations for all user types
• 📊 Analytics Dashboard - Revenue, appointments, performance stats
• 🔍 Time Log Review - Monitor and approve employee time entries
• 💰 Billing Operations - Generate and manage invoices
• ⚙️ System Settings - Configure application parameters

---

🛠️ Tech Stack

Core Technologies:

Framework:       React 18.3.1
Language:        TypeScript 5.8.3
Build Tool:      Vite 5.4.19
Package Manager: pnpm (recommended) / npm / yarn

UI & Styling:

CSS Framework:   Tailwind CSS 3.4.17
Component Lib:   shadcn/ui (Radix UI primitives)
Icons:           Lucide React 0.462.0
Animations:      Tailwind CSS animations
Form Controls:   Radix UI primitives

Routing & Navigation:

Router:          React Router DOM 6.30.1
Protected Routes: Custom RequireAuth component
Role-based:      RBAC with Can component

State Management:

Server State:    TanStack Query 5.83.0 (React Query)
Client State:    Zustand 5.0.8
Global State:    React Context API (AuthContext)

Forms & Validation:

Form Library:    React Hook Form 7.61.1
Schema Validation: Zod 3.25.76
Type Generation: Automatic TypeScript types from Zod

HTTP & API:

HTTP Client:     Axios 1.13.2
Interceptors:    Request/response interceptors
Base URL:        Configured via environment variables

Data Visualization:

Charts:          Recharts 2.15.4
Tables:          Custom DataTable components
Analytics:       Custom dashboard components

UI/UX Libraries:

Notifications:   Sonner 1.7.4 (toast notifications)
Date Handling:   date-fns 3.6.0
Calendar:        Radix UI + date-fns integration
Dialogs:         Radix UI Dialog
Dropdowns:       Radix UI Dropdown Menu
Tooltips:        Radix UI Tooltip

Development Tools:

Linting:         ESLint 9.17.0
Type Checking:   TypeScript strict mode
Hot Reload:      Vite HMR
Dev Server:      Vite dev server

Testing:

E2E Testing:     Playwright 1.48.2
Test Runner:     Playwright Test
UI Mode:         Interactive test debugging

---

🚀 Quick Start

Prerequisites

Ensure you have the following installed:

# Node.js 18 or later
node -v    # Should be v18.0.0 or higher

# pnpm (recommended) or npm
pnpm -v    # Install: npm install -g pnpm
# OR
npm -v     # v9.0.0 or higher

Optional: Use nvm to manage Node.js versions:

nvm install 18
nvm use 18

Installation

1. Clone the Repository

git clone https://github.com/void-squad/autonova-frontend-v1.git
cd autonova-frontend-v1

2. Install Dependencies

# Using pnpm (recommended)
pnpm install

# OR using npm
npm install

# OR using yarn
yarn install

3. Configure Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit .env with your configuration
nano .env

Required Environment Variables:

# Backend API URL
VITE_API_BASE_URL=http://localhost:8080

# OAuth2 Configuration
VITE_GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com

# Optional: Environment
VITE_APP_ENV=development

4. Start Development Server

# Using pnpm
pnpm dev

# OR using npm
npm run dev

The application will start at: http://localhost:5173

Vite offers hot-module reloading for rapid iteration - changes appear instantly!

---

📁 Project Structure

autonova-frontend-v1/
│
├── public/                        # Static assets
│   └── robots.txt                # SEO configuration
│
├── src/
│   ├── pages/                    # Route-level components
│   │   ├── admin/               # Admin dashboard pages
│   │   │   ├── Dashboard.tsx
│   │   │   ├── UserManagement.tsx
│   │   │   └── Analytics.tsx
│   │   ├── employee/            # Employee dashboard pages
│   │   │   ├── Dashboard.tsx
│   │   │   ├── TimeLogging.tsx
│   │   │   └── Tasks.tsx
│   │   ├── customer/            # Customer dashboard pages
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Appointments.tsx
│   │   │   └── Vehicles.tsx
│   │   ├── Login.tsx            # Login page
│   │   ├── Signup.tsx           # Registration page
│   │   ├── ForgotPassword.tsx   # Password recovery
│   │   ├── ResetPassword.tsx    # Password reset
│   │   ├── OAuth2Callback.tsx   # OAuth2 callback handler
│   │   ├── Profile.tsx          # User profile
│   │   └── Landing.tsx          # Landing page
│   │
│   ├── components/              # Reusable UI components
│   │   ├── ui/                 # shadcn/ui components
│   │   │   ├── button.tsx
│   │   │   ├── dialog.tsx
│   │   │   ├── input.tsx
│   │   │   ├── select.tsx
│   │   │   └── ... (50+ components)
│   │   ├── layout/             # Layout components
│   │   │   ├── DashboardLayout.tsx
│   │   │   ├── AdminSidebar.tsx
│   │   │   ├── EmployeeSidebar.tsx
│   │   │   └── CustomerSidebar.tsx
│   │   ├── auth/               # Authentication components
│   │   │   ├── RequireAuth.tsx  # Protected route wrapper
│   │   │   └── Can.tsx          # Permission-based rendering
│   │   ├── timelogging/        # Time logging feature
│   │   │   ├── ActiveTimer.tsx
│   │   │   ├── TimeLogHistory.tsx
│   │   │   ├── TimeLogStats.tsx
│   │   │   └── README.md
│   │   ├── billing/            # Billing components
│   │   │   ├── InvoiceTable.tsx
│   │   │   ├── InvoiceFilters.tsx
│   │   │   └── PayInvoiceDialog.tsx
│   │   └── projects/           # Project management
│   │       ├── DataTable.tsx
│   │       └── StatusBadge.tsx
│   │
│   ├── services/               # API service clients
│   │   ├── authService.ts      # Authentication API
│   │   ├── userService.ts      # User management API
│   │   ├── billingService.ts   # Billing API
│   │   ├── employeeDashboardService.ts
│   │   └── projectService.ts
│   │
│   ├── contexts/               # React contexts
│   │   └── AuthContext.tsx     # Global auth state
│   │
│   ├── hooks/                  # Custom React hooks
│   │   ├── use-toast.ts        # Toast notifications
│   │   ├── use-invoices.ts     # Invoice data fetching
│   │   ├── use-debounce.ts     # Input debouncing
│   │   └── use-mobile.tsx      # Mobile detection
│   │
│   ├── lib/                    # Utility functions
│   │   ├── utils.ts            # Helper functions
│   │   ├── auth.ts             # Auth utilities
│   │   ├── routes.ts           # Route definitions
│   │   └── api/                # API client setup
│   │       ├── client.ts       # Axios instance
│   │       └── interceptors.ts # Request/response interceptors
│   │
│   ├── types/                  # TypeScript type definitions
│   │   ├── auth.ts             # Authentication types
│   │   ├── employee.ts         # Employee types
│   │   ├── billing.ts          # Billing types
│   │   ├── appointment.ts      # Appointment types
│   │   ├── project.ts          # Project types
│   │   └── index.ts            # Exported types
│   │
│   ├── Api/                    # Additional API clients
│   │   ├── notificationsApi.ts
│   │   └── timeLoggingApi.ts
│   │
│   ├── App.tsx                 # Main app component (routing)
│   ├── App.css                 # App-specific styles
│   ├── main.tsx                # Application entry point
│   ├── index.css               # Global styles (Tailwind)
│   └── vite-env.d.ts           # Vite type declarations
│
├── .github/
│   └── workflows/
│       └── docker-publish.yml  # CI/CD pipeline
│
├── components.json             # shadcn/ui configuration
├── tailwind.config.ts          # Tailwind CSS configuration
├── tsconfig.json               # TypeScript configuration
├── vite.config.ts              # Vite configuration
├── postcss.config.js           # PostCSS configuration
├── eslint.config.js            # ESLint configuration
├── package.json                # Dependencies and scripts
├── pnpm-lock.yaml              # pnpm lock file
├── .env.example                # Environment variables template
├── .gitignore                  # Git ignore rules
├── Dockerfile                  # Docker image definition
├── docker-compose.yml          # Docker Compose configuration
└── README.md                   # This file

---

💻 Development

Available Scripts

# Start development server with hot reload
pnpm dev
# or: npm run dev

# Build for production
pnpm build
# or: npm run build

# Preview production build locally
pnpm preview
# or: npm run preview

# Run ESLint
pnpm lint
# or: npm run lint

# Build for development (includes source maps)
pnpm build:dev
# or: npm run build:dev

Development Server Features:

• ⚡ Hot Module Replacement (HMR) - Instant updates without full reload
• 🔍 Error Overlay - Beautiful error messages in browser
• 📦 Pre-bundling - Fast dependency loading with esbuild
• 🚀 Optimized Imports - Automatic code splitting

Code Style Guidelines

File Naming Conventions:

Components:  PascalCase.tsx    (Button.tsx, UserCard.tsx)
Hooks:       use-kebab-case.ts (use-auth.ts, use-debounce.ts)
Services:    camelCase.ts      (authService.ts, userService.ts)
Types:       camelCase.ts      (auth.ts, employee.ts)
Utilities:   camelCase.ts      (utils.ts, helpers.ts)

Component Structure:

// 1. Imports
import { useState } from 'react'
import { useNavigate } from 'react-router-dom'
import { Button } from '@/components/ui/button'

// 2. Types
interface MyComponentProps {
  title: string
  onSubmit: () => void
}

// 3. Component
export default function MyComponent({ title, onSubmit }: MyComponentProps) {
  // 4. State and hooks
  const [isLoading, setIsLoading] = useState(false)
  const navigate = useNavigate()
  
  // 5. Event handlers
  const handleClick = () => {
    setIsLoading(true)
    onSubmit()
  }
  
  // 6. Render
  return (
    <div className="flex flex-col gap-4">
      <h1>{title}</h1>
      <Button onClick={handleClick} disabled={isLoading}>
        Submit
      </Button>
    </div>
  )
}

Adding New Features

1. Add shadcn/ui Component:

npx shadcn-ui@latest add button
npx shadcn-ui@latest add dialog
npx shadcn-ui@latest add select

2. Create New Page:

# Create file: src/pages/NewPage.tsx
# Add route in: src/App.tsx

3. Add API Service:

// src/services/newService.ts
import { api } from '@/lib/api/client'

export const newService = {
  async getData() {
    const response = await api.get('/api/endpoint')
    return response.data
  }
}

---

🔐 Authentication

Auth Context Usage

import { useAuth } from '@/contexts/AuthContext'

function MyComponent() {
  const { user, isAuthenticated, login, logout } = useAuth()
  
  const handleLogin = async () => {
    await login({ email: 'user@example.com', password: 'pass123' })
  }
  
  return (
    <div>
      {isAuthenticated ? (
        <p>Welcome, {user?.userName}!</p>
      ) : (
        <button onClick={handleLogin}>Login</button>
      )}
    </div>
  )
}

Protected Routes

import { RequireAuth } from '@/components/auth/RequireAuth'

// In App.tsx
<Route 
  path="/admin" 
  element={
    <RequireAuth allowedRoles={['ADMIN']}>
      <AdminDashboard />
    </RequireAuth>
  } 
/>

Permission-Based Rendering

import { Can } from '@/components/auth/Can'

<Can roles={['ADMIN', 'EMPLOYEE']}>
  <Button>Admin/Employee Only</Button>
</Can>

Auth Flow Documentation:

• 📄 Login Flow
• 📄 Signup Flow
• 📄 OAuth2 Callback
• 📄 Password Recovery

---

📊 State Management

Server State (TanStack Query)

import { useQuery, useMutation } from '@tanstack/react-query'
import { billingService } from '@/services/billingService'

function InvoiceList() {
  // Fetch data with caching
  const { data, isLoading, error } = useQuery({
    queryKey: ['invoices'],
    queryFn: () => billingService.getInvoices(),
    staleTime: 5 * 60 * 1000, // 5 minutes
  })
  
  // Mutations with optimistic updates
  const mutation = useMutation({
    mutationFn: billingService.payInvoice,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['invoices'] })
    },
  })
  
  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>
  
  return <div>{/* Render invoices */}</div>
}

Client State (Zustand)

import { create } from 'zustand'

interface TimerStore {
  isRunning: boolean
  duration: number
  start: () => void
  stop: () => void
}

const useTimerStore = create<TimerStore>((set) => ({
  isRunning: false,
  duration: 0,
  start: () => set({ isRunning: true }),
  stop: () => set({ isRunning: false }),
}))

// Usage
const { isRunning, start, stop } = useTimerStore()

---

🎨 Styling Guide

Tailwind CSS Classes

// Layout
<div className="flex items-center justify-between gap-4 p-6">

// Typography
<h1 className="text-2xl font-bold text-gray-900 dark:text-white">

// Responsive
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">

// States
<button className="hover:bg-blue-600 active:scale-95 disabled:opacity-50">

shadcn/ui Components

import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { Dialog, DialogContent } from '@/components/ui/dialog'

<Button variant="default" size="lg">Click Me</Button>
<Input type="email" placeholder="Enter email" />

Component Documentation:

• 📖 Component Library
• 🎨 Time Logging Components

---

🔨 Building

Production Build

# Create optimized production build
pnpm build

# Output directory: dist/
# - Minified JavaScript
# - Optimized CSS
# - Code splitting
# - Asset optimization

Build Analysis

# Build with analysis
pnpm build

# Check bundle size
ls -lh dist/assets/

Preview Production Build

pnpm preview

# Opens at: http://localhost:4173

---

🧪 Testing

E2E Tests with Playwright

# Install Playwright browsers (first time only)
npx playwright install

# Run all tests
npx playwright test

# Run in UI mode (interactive)
npx playwright test --ui

# Run specific test file
npx playwright test login.spec.ts

# Debug mode
npx playwright test --debug

Writing Tests

// tests/login.spec.ts
import { test, expect } from '@playwright/test'

test('user can login', async ({ page }) => {
  await page.goto('http://localhost:5173/login')
  await page.fill('input[name="email"]', 'test@example.com')
  await page.fill('input[name="password"]', 'password123')
  await page.click('button[type="submit"]')
  
  await expect(page).toHaveURL(/.*dashboard/)
})

---

🐳 Docker

Build Docker Image

docker build -t autonova-frontend .

Run Container

docker run -p 80:80 autonova-frontend

Docker Compose

# Start with Docker Compose
docker-compose up -d

# Stop
docker-compose down

Multi-Stage Build

The Dockerfile uses multi-stage builds for optimized production images:

1. Builder stage: Builds the application
2. Production stage: Serves with Nginx

---

🐛 Troubleshooting

Common Issues

1. Port Already in Use

# Change port in vite.config.ts
export default defineConfig({
  server: {
    port: 5174
  }
})

2. API Connection Refused

# Verify backend is running
curl http://localhost:8080/actuator/health

# Check .env configuration
cat .env | grep VITE_API_BASE_URL

3. Module Not Found

# Clear node_modules and reinstall
rm -rf node_modules
pnpm install

4. TypeScript Errors

# Restart TypeScript server in VS Code
Cmd+Shift+P → "TypeScript: Restart TS Server"

5. Build Fails

# Clear Vite cache
rm -rf node_modules/.vite

# Rebuild
pnpm build

Debug Mode

Enable verbose logging:

DEBUG=* pnpm dev

---

📚 Additional Documentation

Project Documentation:

• 🏠 Main Project README
• ⚙️ Backend README
• 📊 Employee Dashboard Architecture
• ⏱️ Time Logging Integration
• 📋 Time Logging API Requirements

External Resources:

• React Documentation
• TypeScript Handbook
• Vite Guide
• Tailwind CSS Docs
• shadcn/ui Components
• TanStack Query

---

🤝 Contributing

See main Contributing Guidelines

Frontend Development Guidelines:

1. ✅ Follow TypeScript strict mode
2. ✅ Use Tailwind CSS utilities (avoid custom CSS)
3. ✅ Implement responsive design (mobile-first)
4. ✅ Add loading states for async operations
5. ✅ Handle error states gracefully
6. ✅ Use React Hook Form for all forms
7. ✅ Validate with Zod schemas
8. ✅ Write meaningful component names
9. ✅ Add JSDoc comments for complex logic
10. ✅ Test E2E flows with Playwright

---

📄 License

This project is licensed under the MIT License.

---

Part of the Autonova Platform

⬆ Back to Top | Main README