Quick Start Guide

Relevant source files

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

• QUICKSTART.md
• README.md
• SUMMARY.md
• backend/main.py
• frontend/package.json
• frontend/index.html
• DASHBOARD_README.md

This guide provides instructions for setting up and running the SPK Kajek project, a Decision Support System (DSS) for selecting the best Cloud VPS server using the TOPSIS method. The application features a modern, interactive dashboard built with React for the frontend and a FastAPI backend to perform calculations.

The system is composed of a Single Page Application (SPA) for a fast, reload-free user experience, and a REST API backend that handles data processing, TOPSIS calculations, and user authentication. For more detailed documentation on specific components, refer to the Dashboard Documentation or the System Summary.

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

Architecture Overview

The project follows a modern client-server architecture. The frontend is a React application built with Vite, and the backend is a Python-based API using the FastAPI framework. Data for vendors, users, and calculation history is stored in local files (.xlsx, .json).

Sources: SUMMARY.md, backend/main.py:20-23

The following diagram illustrates the high-level system architecture.

Prerequisites

Before you begin, ensure you have the following software installed on your system.

Software	Required Version
Node.js	18+
Python	3.8+
npm	(comes with Node.js)
pip	(comes with Python)

Sources: QUICKSTART.md:6-9, README.md:120-122

Installation

Follow these steps to set up the development environment for both the frontend and backend.

Sources: QUICKSTART.md:13-39

1. Clone the Repository

First, clone the project from GitHub and navigate into the directory.

git clone https://github.com/Fahri-Hilm/DSS-SPK_KAJEK.git
cd DSS-SPK_KAJEK

Sources: QUICKSTART.md:16-18

2. Backend Setup (FastAPI)

The backend requires a Python virtual environment and installation of dependencies from requirements.txt.

# Navigate to the backend directory
cd backend

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

Sources: QUICKSTART.md:22-31, README.md:126-131

3. Frontend Setup (React)

The frontend uses npm to manage its dependencies, which are listed in package.json.

# Navigate to the frontend directory (from the root)
cd frontend

# Install Node.js dependencies
npm install

Sources: QUICKSTART.md:35-38, README.md:135-137

Running the Application

You can run the application using a single script or by starting the backend and frontend services manually in separate terminals.

Option 1: Using the Start Script (Recommended)

The repository includes a shell script start.sh that launches both the backend and frontend servers concurrently.

./start.sh

Sources: QUICKSTART.md:43-44, README.md:142-143

The startup process initiated by the script is visualized below.

Option 2: Manual Start

If you prefer to run the services separately, use two terminal windows.

Terminal 1 - Backend:

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

Sources: QUICKSTART.md:48-51, SUMMARY.md:110-111

Terminal 2 - Frontend:

cd frontend
npm run dev

Sources: QUICKSTART.md:55-57, SUMMARY.md:113-114, frontend/package.json:7

Accessing the Application

Once the services are running, you can access them at the following default URLs.

Service	URL
Frontend UI	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:61-67, frontend/index.html:6

Default Credentials

The system is pre-configured with a default administrator account for initial access.

• Username: admin
• Password: admin123

It is highly recommended to change the default password after the first login via the "Settings" page.

Sources: QUICKSTART.md:71-73, backend/main.py:102-108, frontend/src/components/DocumentationView.tsx:103-107

Troubleshooting

Here are solutions to common issues you might encounter during setup.

• Port Already in Use: If you see an error that port 8000 or 5173 is in use, you can either stop the process using that port or run the application on a different one.

  • Backend: uvicorn main:app --reload --port 9000
  • Frontend: npm run dev -- --port 3000

• Module Not Found / Dependencies Error: This usually means dependencies were not installed correctly.

  • For the backend, ensure your virtual environment is active and run pip install -r requirements.txt.
  • For the frontend, run npm install in the frontend directory.

• CORS Error: This error occurs if the frontend cannot communicate with the backend. Ensure the backend is running on http://localhost:8000 as expected by the frontend configuration. The FastAPI backend is configured to allow all origins for development.

Sources: QUICKSTART.md:162-181, backend/main.py:10-16