Electric Cars DataGrid Application

A full-stack TypeScript application featuring a comprehensive electric cars database with advanced search, filtering, and data management capabilities. Built with React, Material-UI, AG Grid, and Express with MySQL.

Quick Links

• Frontend Documentation - React components, API integration, and UI details
• Backend Documentation - API endpoints, database schema, and server setup

Project Structure

electric_cars_datagrid/
├── frontend/              # React + Vite + TypeScript + Material-UI
│   ├── README.md                       # 📖 Frontend documentation
│   ├── src/
│   │   ├── components/
│   │   │   ├── DataGrid/
│   │   │   │   ├── DataGrid.tsx        # Generic AG Grid wrapper with server-side pagination
│   │   │   │   ├── SearchBar.tsx       # Debounced search component
│   │   │   │   ├── FilterPanel.tsx     # Dynamic filter builder
│   │   │   │   └── ActionCell.tsx      # Action buttons (View/Delete)
│   │   │   ├── common/
│   │   │   │   ├── LoadingSpinner.tsx  # Loading state component
│   │   │   │   └── ErrorMessage.tsx    # Error handling component
│   │   │   └── Footer.tsx              # App footer
│   │   ├── pages/
│   │   │   ├── CarsPage.tsx            # Main cars listing page
│   │   │   └── CarDetailPage.tsx       # Individual car detail page
│   │   ├── services/
│   │   │   └── api.ts                  # Axios API client with interceptors
│   │   ├── types/
│   │   │   └── index.ts                # TypeScript type definitions
│   │   ├── App.tsx                     # Main app with routing
│   │   ├── main.tsx                    # Entry point
│   │   └── theme.ts                    # Material-UI theme configuration
│   ├── .env                            # Environment variables (gitignored)
│   ├── .env.example                    # Environment template
│   ├── tsconfig.json
│   └── package.json
│
└── backend/               # Express + TypeScript + MySQL
    ├── README.md                       # 📖 Backend API documentation
    ├── src/
    │   ├── database/
    │   │   ├── connection.ts           # MySQL connection pool
    │   │   ├── setup.ts                # Database initialization
    │   │   ├── migrations/             # Database migrations
    │   │   └── seeds/                  # Seed data scripts
    │   ├── routes/
    │   │   └── cars.ts                 # Car API routes
    │   ├── controllers/
    │   │   └── carController.ts        # Business logic
    │   ├── types.ts                    # TypeScript types
    │   └── server.ts                   # Express server
    ├── tsconfig.json
    └── package.json

Features

Frontend

• TypeScript: Full type safety across the application
• Material-UI v7: Modern, responsive UI with custom theme
• AG Grid Community v34: Advanced data grid with sorting, filtering, and pagination
• Server-Side Pagination: Custom Material-UI pagination for large datasets
• Debounced Search: Real-time search across all car fields with 500ms debounce
• Advanced Filtering: Dynamic filter builder with operators (equals, contains, greater than, less than)
• React Router: Client-side routing with car detail pages
• Axios Integration: API client with request/response interceptors and error handling
• Environment Variables: Vite-based configuration for different environments
• Loading States: Smooth loading indicators and error boundaries
• Delete Confirmation: Material-UI dialogs with optimistic UI updates
• Notifications: Snackbar alerts for user actions
• Responsive Design: Mobile-first approach with Material-UI Grid system

Backend

• TypeScript: Type-safe Express server
• MySQL Database: Relational database with proper schema design
• RESTful API: Clean API design with proper HTTP methods
• CORS Enabled: Cross-origin requests supported
• Pagination: Server-side pagination with configurable page sizes
• Full-Text Search: Search across multiple car fields simultaneously
• Complex Filtering: Support for AND/OR conditions with various operators
• Database Migrations: Version-controlled schema changes
• Seed Scripts: CSV import for initial data
• Error Handling: Comprehensive error responses with proper status codes

Installation

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• MySQL (v8.0 or higher)
• Docker and Docker Compose

Backend Setup

1. Install dependencies:

   cd backend
   npm install

2. Set up database:

   npm run setup    # Create database and tables
   npm run seed     # Import electric cars data from CSV

3. Start server:

   npm run dev      # Development mode with auto-reload

The backend will start on http://localhost:3001

Frontend Setup

1. Install dependencies:

   cd frontend
   npm install

2. Configure environment:

   cp .env.example .env
   # Edit .env with your API URL (default: http://localhost:3001/api)

3. Start development server:

   npm run dev

The frontend will start on http://localhost:5173

Docker Setup

The easiest way to run the entire application stack is using Docker Compose. This will automatically set up MySQL, backend, and frontend services with proper networking and dependencies.

Quick Start with Docker

1. Clone the repository:

   git clone <repository-url>
   cd electric_cars_datagrid

2. Create environment file:

   cp .env.example .env
   # Edit .env if you want to customize ports or credentials

3. Build and start all services:

   docker-compose up --build

   This command will:

   • Pull MySQL 8.0 image
   • Build the backend Docker image
   • Build the frontend Docker image
   • Start all three services with proper health checks
   • Set up networking between services
   • Initialize the database with migrations

4. Access the application:

   • Frontend: http://localhost (port 80)
   • Backend API: http://localhost:3001
   • MySQL: localhost:3306

5. Stop the services:

   docker-compose down

6. Stop and remove volumes (including database data):

   docker-compose down -v

Docker Services

The docker-compose.yml file defines three services:

MySQL Service

• Image: mysql:8.0
• Port: 3306
• Database: electric_cars_db
• Persistent storage: Named volume mysql_data
• Health check: Automatic with 10s interval
• Migrations: Auto-loaded from backend/src/database/migrations/

Backend Service

• Image: Built from backend/Dockerfile
• Port: 3001
• Dependencies: Waits for MySQL to be healthy
• Health check: HTTP check on /health endpoint
• Environment: Production mode with MySQL connection

Frontend Service

• Image: Built from frontend/Dockerfile (multi-stage with nginx)
• Port: 80
• Dependencies: Waits for backend to be ready
• Health check: HTTP check on /health endpoint
• Features: SPA routing, static asset caching, gzip compression

Docker Environment Variables

All Docker-related environment variables are defined in the root .env file:

# MySQL Configuration
MYSQL_ROOT_PASSWORD=root_password
MYSQL_DATABASE=electric_cars_db
MYSQL_USER=bmw_user
MYSQL_PASSWORD=bmw_password
MYSQL_PORT=3306

# Backend Configuration
NODE_ENV=production
BACKEND_PORT=3001
CORS_ORIGIN=http://localhost

# Frontend Configuration
FRONTEND_PORT=80
VITE_API_BASE_URL=http://localhost:3001/api

Docker Commands

# Build and start in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f backend

# Restart a service
docker-compose restart backend

# Rebuild a specific service
docker-compose build backend
docker-compose up -d backend

# Execute commands inside containers
docker-compose exec backend npm run seed
docker-compose exec mysql mysql -u root -p

# Check service status
docker-compose ps

# Stop all services
docker-compose stop

# Remove all containers and networks
docker-compose down

# Remove containers, networks, and volumes
docker-compose down -v

Docker Development

For development with hot-reload:

1. Use volume mounts for code changes:

   # Add to backend service in docker-compose.yml
   volumes:
     - ./backend/src:/app/src

2. Override command for dev mode:

   # Add to backend service in docker-compose.yml
   command: npm run dev

3. Rebuild after dependency changes:

   docker-compose up --build

Troubleshooting Docker

Container won't start

# Check logs
docker-compose logs backend

# Check health status
docker-compose ps

Database connection issues

# Verify MySQL is healthy
docker-compose ps mysql

# Check backend can reach MySQL
docker-compose exec backend ping mysql

Port already in use

# Change ports in .env file
FRONTEND_PORT=8080
BACKEND_PORT=3002
MYSQL_PORT=3307

Clear everything and start fresh

docker-compose down -v
docker-compose up --build

Environment Variables

Frontend (.env)

VITE_API_BASE_URL=http://localhost:3001/api
VITE_API_TIMEOUT=10000

Note: All Vite environment variables must be prefixed with VITE_ to be exposed to the client.

Backend

Configure MySQL connection in src/database/connection.ts or use environment variables.

Usage

1. Start the backend server:

   cd backend
   npm run dev

2. In a new terminal, start the frontend:

   cd frontend
   npm run dev

3. Open your browser and navigate to http://localhost:5173

4. Features to explore:

   • Browse paginated car listings
   • Use the search bar to find cars by any field
   • Apply complex filters with multiple conditions
   • Click "View" to see detailed car information
   • Delete cars with confirmation dialog
   • Navigate between pages with custom pagination

Technologies Used

Frontend

• React 19 - UI library with latest features
• TypeScript 5.9 - Type-safe JavaScript
• Vite 7 - Fast build tool and dev server
• Material-UI 7 - Comprehensive React component library
• AG Grid Community 34 - Advanced data grid
• React Router 7 - Client-side routing
• Axios 1.12 - Promise-based HTTP client
• Emotion - CSS-in-JS styling

Backend

• Express 5 - Web framework
• TypeScript 5.9 - Type-safe JavaScript
• MySQL 2 - MySQL client for Node.js
• ts-node - TypeScript execution for Node.js
• CORS - Cross-origin resource sharing
• Nodemon - Development auto-reload
• dotenv - Environment variable management
• csv-parser - CSV file parsing for seed data

Development Scripts

Frontend

npm run dev      # Start development server (http://localhost:5173)
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint

Backend

npm run dev      # Start with nodemon + ts-node (auto-reload)
npm run build    # Compile TypeScript to JavaScript
npm start        # Start compiled JavaScript
npm run setup    # Initialize database
npm run seed     # Import CSV data
npm run migrate  # Run database migrations

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - feel free to use this project for learning or commercial purposes.