Gezen Web Panel

Gezen Web Panel is a modern, high-performance web-based administration panel built for managing manufacturing ecosystems, factory details, machines, quotes, installations, and digital competency assessments.

---

Project Architecture

The project is structured as a modern Single Page Application (SPA) using React, TypeScript, and Vite. The design philosophy focuses on modular components, unidirectional data flow, robust API integration, and strong separation of concerns.

Tech Stack

• Core Framework: React 18
• Build Tool & Bundler: Vite 8 (providing near-instantaneous hot module replacement)
• Language: TypeScript 5 (for strict compile-time safety and self-documenting code)
• UI & Component Library: Material UI (MUI) 6 (for beautiful, accessible, and responsive components)
• Routing: React Router DOM 7
• State Management & Data Fetching: TanStack React Query 5 (for declarative server-state synchronization)
• HTTP Client: Axios (configured with automated request/response interception)
• Testing: Vitest (a fast, Vite-native unit testing framework)

Getting Started

Prerequisites

To build and run this application, ensure you have the following installed:

• Node.js (v18.x or higher recommended)
• npm (v10.x or higher)

Setup & Installation

1. Clone or download the repository into your workspace:

   cd gezen-web-panel-frontend
   

2. Install all development and production dependencies:

   npm install
   

3. Configure Environment Variables: The application requires several environment variables to be defined to start or build successfully. Default values are pre-configured in .env.development and .env.production.

   To customize settings for your local environment (e.g., if your local backend runs on a different port or host):

   • Create a .env.development.local file in the root directory.
   • Override the variables you want to change (e.g., VITE_API_HOST=localhost:8080).

   See the Configuration & Environment section below for the list of required variables and details.

4. Start the Vite local development server:

   npm run dev
   

   The local development server will start at http://localhost:3000 (or another available port).

---

Configuration & Environment

The application dynamically configures its backend URLs based on environment variables. These variables are strictly required; if any of them are missing or invalid, the application will throw an error immediately on startup or during the build process.

Environment Files

Vite loads environment variables from files in the project root based on the current mode:

• Development (npm run dev): Loads .env.development and .env.development.local (git-ignored).
• Production Build (npm run build): Loads .env.production and .env.production.local (git-ignored).
• Testing (npm run test): Loads .env.test and .env.test.local (git-ignored).

To override configuration locally without modifying tracked files, create a .env.development.local file in the project root.

Required Variables

The following environment variables must be defined:

Variable	Purpose	Constraints & Validation	Example
VITE_API_PROTOCOL	Backend protocol.	Must be http or https.	http
VITE_API_HOST	Backend domain, IP address, or host with port.	Must not include protocol (e.g., http://) or path.	127.0.0.1:8000
VITE_API_BASE_PATH	Main API endpoint prefix.	Must start with /.	/api
VITE_MEDIA_VIDEO_PATH	Video media endpoint path.	Must start with /.	/api/files/iqvideo
VITE_MEDIA_PRESENTATION_PATH	Presentation media endpoint path.	Must start with /.	/api/files/sunum

Example Configurations

Local Development (.env.development)

VITE_API_PROTOCOL=http
VITE_API_HOST=127.0.0.1:8000
VITE_API_BASE_PATH=/api
VITE_MEDIA_VIDEO_PATH=/api/files/iqvideo
VITE_MEDIA_PRESENTATION_PATH=/api/files/sunum

Production (.env.production)

VITE_API_PROTOCOL=http
VITE_API_HOST=192.168.10.113:8000
VITE_API_BASE_PATH=/api
VITE_MEDIA_VIDEO_PATH=/api/files/iqvideo
VITE_MEDIA_PRESENTATION_PATH=/api/files/sunum

Production Domain with HTTPS

VITE_API_PROTOCOL=https
VITE_API_HOST=panel-api.example.com
VITE_API_BASE_PATH=/api
VITE_MEDIA_VIDEO_PATH=/api/files/iqvideo
VITE_MEDIA_PRESENTATION_PATH=/api/files/sunum

All outbound network requests initiated via the apiClient automatically append the authentication token under the Authorization: Bearer <token> header, verified and retrieved from the secure browser session storage.

---

Testing

This project leverages Vitest to run units and integration/smoke tests.

To execute the test suite in single run mode:

npm run test

To start the Vitest test watcher for active development:

npx vitest

---

Deployment & Production Build

Building the Project

To compile the TypeScript code and compile production assets into optimized static HTML, CSS, and JS files:

npm run build

This output is written to the /dist directory.

Previewing the Production Build

You can verify and test your production build locally by running:

npm run preview