Backend API Endpoints

Relevant source files

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

• backend/main.py
• frontend/src/services/api.ts
• SUMMARY.md
• README.md
• frontend/src/components/DocumentationView.tsx
• backend/topsis_service.py

The backend for the SPK Kajek project is a RESTful API built with Python and the FastAPI framework. It serves as the core engine for the Decision Support System (DSS), handling user authentication, data management for cloud VPS alternatives, and executing the TOPSIS (Technique for Order Preference by Similarity to Ideal Solution) algorithm. The API interacts with a React-based frontend, providing all necessary data and calculation results.

The system's architecture is file-based, meaning it does not use a traditional database. Instead, it relies on local files for data persistence: TOPSIS_Input_Level.xlsx for vendor data, users.json for user accounts, and calculation_history.json for storing past analysis results. All business logic, from CRUD operations on the Excel file to the complex multi-step TOPSIS calculations, is encapsulated within the API endpoints.

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

System Architecture

The backend consists of a single FastAPI application that exposes several endpoints under the /api/ prefix. It is configured with CORS middleware to allow requests from the frontend, which runs on a different port.

Sources: backend/main.py:12-21

This diagram illustrates the high-level architecture of the backend and its interaction with the client and data files.

Core Components

Component	Description	File
FastAPI App	The main application instance that routes requests to endpoint functions.	backend/main.py:12
CORS Middleware	Allows cross-origin requests from the frontend (e.g., http://localhost:5173).	backend/main.py:15-21
Pydantic Models	Used for request/response validation and data serialization. Models include WeightRequest, VendorData, LoginRequest, etc.	backend/main.py:33-60
Data Files	The system uses local files for storage: TOPSIS_Input_Level.xlsx, users.json, and calculation_history.json.	backend/main.py:23-26
JWT Security	Implements JWT-based authentication using python-jose and HTTPBearer.	backend/main.py:29-31, 64-152

Authentication Endpoints

Authentication is managed using JSON Web Tokens (JWT). The API provides endpoints for logging in, retrieving user profiles, and changing passwords. User data is stored in users.json.

Sources: backend/main.py:101-224, frontend/src/services/api.ts:4-16, 68-99

Security Scheme

• Token Type: Bearer Token
• Algorithm: HS256
• Secret Key: A hardcoded secret key.
• Token Expiration: 24 hours.
• Password Hashing: PBKDF2-HMAC-SHA256 with 100,000 iterations and a random salt.

Sources: backend/main.py:29-31, 66-85, frontend/src/components/DocumentationView.tsx:80-84

Login Flow

The following sequence diagram shows the user login process.

Authentication API Summary

Endpoint	Method	Description	Request Body	Response
/api/login	POST	Authenticates a user and returns a JWT.	LoginRequest	Token
/api/profile	GET	Retrieves the profile of the authenticated user.	-	UserProfile
/api/profile	PUT	Updates the authenticated user's profile.	UpdateProfile	Success message
/api/change-password	POST	Changes the authenticated user's password.	ChangePassword	Success message

Sources: backend/main.py:155-224, frontend/src/services/api.ts:68-99

Data Management Endpoints (CRUD)

These endpoints manage the list of VPS vendors (alternatives) stored in the TOPSIS_Input_Level.xlsx file. They provide full Create, Read, Update, and Delete functionality.

Sources: backend/main.py:229-354, frontend/src/services/api.ts:102-125

Data Flow for Adding a Vendor

This flowchart shows how a new vendor is added to the system via the API.

Data Management API Summary

Endpoint	Method	Description	Request Body	Response
/api/data	GET	Retrieves all vendor data from the Excel file.	-	List[DataItem]
/api/data	POST	Adds a new vendor to the Excel file.	VendorData	Success message
/api/data/{vendor_no}	PUT	Updates an existing vendor by its No.	VendorData	Success message
/api/data/{vendor_no}	DELETE	Deletes a vendor by its No.	-	Success message

Sources: backend/main.py:229-354, frontend/src/services/api.ts:102-125

TOPSIS Calculation Endpoints

These are the core endpoints of the application, responsible for executing the TOPSIS algorithm based on user-defined weights.

Sources: backend/main.py:356-547

Calculation Process (/api/calculate)

The /api/calculate endpoint performs the full TOPSIS analysis.

Criteria and Level Conversion

The system uses a level-based system (1-5) for input, which is converted to standard numerical values before calculation.

Criteria	Type	Level 1	Level 2	Level 3	Level 4	Level 5
CPU	Benefit	2 cores	4 cores	6 cores	8 cores	10 cores
RAM	Benefit	2 GB	4 GB	8 GB	16 GB	32 GB
Disk I/O	Benefit	150 MB/s	300 MB/s	500 MB/s	700 MB/s	1000 MB/s
Harga	Cost	$15	$35	$75	$150	$250

Sources: backend/main.py:363-366, README.md

Calculation API Summary

Endpoint	Method	Description	Request Body	Response
/api/calculate	POST	Runs the TOPSIS calculation and returns the final rankings and top recommendation.	WeightRequest	JSON with rankings and top_recommendation.
/api/calculate-detail	POST	Returns a detailed, step-by-step breakdown of the TOPSIS calculation, including all intermediate matrices.	WeightRequest	JSON with step1_input, step2_normalized, etc.

Sources: backend/main.py:356-547, frontend/src/services/api.ts:127-131

History Endpoints

The API supports saving and retrieving past calculation results to and from calculation_history.json.

Sources: backend/main.py:551-667, frontend/src/services/api.ts:133-154

History API Summary

Endpoint	Method	Description	Request Body	Response
/api/history	GET	Retrieves all saved calculation history entries.	-	List[HistoryEntry]
/api/history	POST	Runs a new calculation and saves the result to history.	HistoryEntry	Success message
/api/history/{history_id}	DELETE	Deletes a specific history entry by its ID.	-	Success message
/api/history	DELETE	Clears all calculation history.	-	Success message

Sources: backend/main.py:566-667

Data Models (Pydantic)

The API uses Pydantic models to define and validate the structure of incoming and outgoing data.

This class diagram shows the main Pydantic models used in the API.