Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• backend/requirements.txt
• frontend/package.json
• start.sh
• QUICKSTART.md
• README.md
• backend/main.py
• SUMMARY.md
• frontend/src/components/DocumentationView.tsx

This document outlines the necessary steps to set up and run the SPK Kajek project on a local machine. The project consists of a React frontend and a FastAPI backend, which must be run concurrently for full application functionality. The setup involves installing dependencies for both services and starting their respective development servers.

The overall architecture consists of a client-side application built with React that communicates via a REST API with a Python-based backend. The backend handles business logic, including the TOPSIS algorithm, and data persistence through local files.

Sources: SUMMARY.md, README.md, QUICKSTART.md

System Architecture

The local development environment runs two main services: a Vite-powered frontend server and a Uvicorn-powered backend server. They interact with each other and with a local file-based data layer.

The following diagram illustrates the high-level architecture of the application running locally.

Prerequisites

Before proceeding with the installation, ensure the following software is installed on your system.

Software	Minimum Version	Purpose
Node.js	18+	JavaScript runtime for the frontend
npm	(comes with Node.js)	Package manager for the frontend
Python	3.8+	Runtime for the backend API
pip	(comes with Python)	Package manager for the backend

Sources: QUICKSTART.md, README.md

Installation

The installation process is divided into two parts: setting up the backend and setting up the frontend.

Sources: QUICKSTART.md, README.md

Backend Setup

The backend is a Python application using the FastAPI framework. Setup involves creating a virtual environment and installing dependencies from requirements.txt.

1. Navigate to the backend directory.
2. Create a Python virtual environment.
3. Activate the virtual environment.
4. Install the required packages using pip.

# Navigate to the backend directory
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment (Linux/Mac)
source venv/bin/activate
# Or for Windows:
# venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Sources: QUICKSTART.md, README.md

Backend Dependencies

The key backend dependencies are listed in backend/requirements.txt.

Package	Purpose
fastapi	Core web framework for building the API.
uvicorn	ASGI server to run the FastAPI application.
pandas	Data manipulation and analysis, primarily for Excel file interaction.
openpyxl	Reading from and writing to .xlsx files.
python-jose	JWT implementation for user authentication.
numpy	Numerical operations for the TOPSIS calculation.

Sources: backend/requirements.txt, backend/main.py

Frontend Setup

The frontend is a single-page application built with React and TypeScript, using Vite as the build tool.

1. Navigate to the frontend directory.
2. Install the required Node.js packages using npm.

# Navigate to the frontend directory
cd frontend

# Install dependencies
npm install

Sources: QUICKSTART.md, README.md

Frontend Dependencies

The key frontend dependencies are defined in frontend/package.json.

Package	Purpose
react	The core UI library.
vite	Build tool and development server.
typescript	Language for type safety.
tailwindcss	Utility-first CSS framework for styling.
axios	HTTP client for making API requests to the backend.
recharts	Library for creating interactive charts.
framer-motion	Animation library for UI effects.
three	3D graphics library for Chart3D.tsx.

Sources: frontend/package.json, UI_UX_UPGRADE.md

Running the Application

The application can be started using an automated script or by running the backend and frontend servers manually in separate terminals.

Option 1: Automated Start Script (Recommended)

The repository includes a shell script, start.sh, which automates the process of launching both the backend and frontend servers.

./start.sh

The script performs the following actions:

1. Starts the backend FastAPI server using uvicorn on port 8000.
2. Starts the frontend Vite development server using npm run dev on port 5173.

The following diagram shows the flow of the start.sh script.

Option 2: Manual Start

For more control, you can start the backend and frontend servers manually in two separate terminal sessions.

Terminal 1: Start Backend

cd backend
source venv/bin/activate
uvicorn main:app --reload --port 8000

Terminal 2: Start Frontend

cd frontend
npm run dev

Sources: QUICKSTART.md, README.md

Accessing the Application

Once both servers are running, the application can be accessed at the following URLs:

Service	URL
Frontend Application	http://localhost:5173
Backend API	http://localhost:8000
API Documentation (Swagger)	http://localhost:8000/docs
API Documentation (ReDoc)	http://localhost:8000/redoc

Sources: QUICKSTART.md, frontend/index.html:6

Data and Configuration

The local development setup relies on several files for data and configuration. These files are located in the backend directory and are essential for the application to function correctly.

File	Purpose
TOPSIS_Input_Level.xlsx	The primary data source containing vendor information and criteria levels.
users.json	Stores user account information, including hashed passwords.
calculation_history.json	Stores the results of past TOPSIS calculations.

If users.json does not exist, the backend will create it with a default administrator account.

Sources: backend/main.py:20-22, backend/main.py:100-111

Default Credentials

The application is secured with JWT-based authentication. For local development, a default administrator account is provided.

• Username: admin
• Password: admin123

The password for the default user is hashed using PBKDF2-HMAC-SHA256.

Sources: frontend/src/components/DocumentationView.tsx:90-97, backend/main.py:103-104, backend/main.py:77-87