Backend Architecture

Relevant source files

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

• backend/main.py
• backend/topsis_service.py
• SUMMARY.md
• topsis_spk.py
• generate_excel_level.py
• frontend/src/components/DocumentationView.tsx
• README.md

The backend for the SPK Kajek project is a Python-based REST API built with the FastAPI framework. Its primary role is to serve as the engine for the Decision Support System (DSS), providing data management, user authentication, and the core TOPSIS (Technique for Order Preference by Similarity to Ideal Solution) calculation logic. It interacts with a React frontend, processing requests and delivering structured JSON responses.

The architecture is designed to be stateless, with data persistence handled through local files, primarily an Excel spreadsheet for vendor data and JSON files for user accounts and calculation history. This makes the backend self-contained and easy to deploy.

Sources: SUMMARY.md, backend/main.py, README.md

System Architecture

The backend is a central component that communicates with the frontend via a REST API and reads/writes data from the local file system.

Sources: SUMMARY.md, frontend/src/components/DocumentationView.tsx:132-146

This diagram illustrates the high-level system architecture.

Core Technologies

The backend leverages several key Python libraries to function.

Technology	Purpose	Source File
FastAPI	High-performance REST API framework.	backend/main.py:9
Pydantic	Data validation and settings management using Python type annotations.	backend/main.py:15
Pandas	Data processing and manipulation, primarily for handling Excel data.	backend/main.py:11
NumPy	Numerical computation for the TOPSIS algorithm.	backend/main.py:12
OpenPyXL	Engine for reading from and writing to .xlsx files.	README.md
python-jose	JWT implementation for authentication tokens.	backend/main.py:16, README.md

API Endpoints

The API is structured into logical groups for authentication, data management, calculation, and history.

Sources: backend/main.py, SUMMARY.md

Authentication Endpoints

Method	Endpoint	Description	Source Lines (main.py)
POST	/api/login	Authenticates a user and returns a JWT token.	184-213
GET	/api/profile	Retrieves the profile of the currently authenticated user.	215-222
PUT	/api/profile	Updates the profile of the currently authenticated user.	224-242
POST	/api/change-password	Changes the password for the authenticated user.	244-266

Data Management Endpoints

Method	Endpoint	Description	Source Lines (main.py)
GET	/api/data	Retrieves all vendor data from TOPSIS_Input_Level.xlsx.	270-278
POST	/api/data	Adds a new vendor to the Excel file.	280-307
PUT	/api/data/{vendor_no}	Updates an existing vendor's data by its number.	327-355
DELETE	/api/data/{vendor_no}	Deletes a vendor from the Excel file by its number.	309-325

TOPSIS Calculation Endpoints

Method	Endpoint	Description	Source Lines (main.py)
POST	/api/calculate	Runs the TOPSIS calculation with given weights and returns the ranked results.	357-428
POST	/api/calculate-detail	Returns a step-by-step breakdown of the TOPSIS calculation matrices.	431-540

History Endpoints

Method	Endpoint	Description	Source Lines (main.py)
GET	/api/history	Retrieves all saved calculation history entries.	559-564
POST	/api/history	Saves a new calculation result to the history file.	566-640
DELETE	/api/history/{history_id}	Deletes a specific history entry by its ID.	642-648
DELETE	/api/history	Clears all entries from the calculation history.	650-655

Data Layer

The backend does not use a traditional database. Instead, it relies on a set of files for data persistence.

This ER diagram shows the entities managed by the backend and their storage.

Data Sources

• TOPSIS_Input_Level.xlsx: The primary data source containing vendor information. The backend reads the '1. Input Level' sheet, skipping the first two rows, to get the list of alternatives and their criteria levels.
  Sources: backend/main.py:272-273, generate_excel_level.py:112-132
• users.json: Stores user account information, including hashed passwords. A default admin user is created if the file does not exist.
  Sources: backend/main.py:25, 122-132
• calculation_history.json: A JSON array that stores the results of past TOPSIS calculations for trend analysis and review.
  Sources: backend/main.py:24, 545-550

Authentication and Security

User authentication is managed via JSON Web Tokens (JWT). The system uses a bearer token scheme for authenticating API requests to protected endpoints.

Sources: backend/main.py:100-182

Authentication Flow

The following sequence diagram shows the login process.

Key Security Components

• JWT Generation: The create_access_token function generates a JWT signed with the HS256 algorithm. The token has an expiration time of 24 hours.
  Sources: backend/main.py:32, 134-143
• Password Hashing: Passwords are not stored in plain text. The hash_password function uses PBKDF2-HMAC-SHA256 with a 16-byte salt and 100,000 iterations to create a secure hash. The verify_password function validates a given password against the stored hash.
  Sources: backend/main.py:102-118
• Protected Endpoints: Endpoints requiring authentication use Depends(get_current_user), which decodes the bearer token from the request header and validates it.
  Sources: backend/main.py:145-167

TOPSIS Calculation Logic

The core of the backend is its ability to perform TOPSIS calculations. This process is encapsulated in the /api/calculate and /api/calculate-detail endpoints.

This flowchart outlines the step-by-step TOPSIS calculation process performed by the backend.

Calculation Steps

1. Load and Convert Data: The system reads the vendor data from TOPSIS_Input_Level.xlsx. It then converts the discrete _Level columns (e.g., CPU_Level) into their corresponding numerical values (e.g., CPU_val) based on predefined mapping dictionaries.
   Sources: backend/main.py:363-368, generate_excel_level.py:147-158
2. Normalization: The decision matrix X is normalized using vector normalization to create matrix R. The formula used is rij = xij / √(Σxij²).
   Sources: backend/main.py:373-374, topsis_spk.py:68-69
3. Weighting: The normalized matrix R is multiplied by the user-provided weights w to form the weighted normalized matrix Y.
   Sources: backend/main.py:377, topsis_spk.py:72-73
4. Ideal Solutions: The positive ideal solution A+ (best performance) and negative ideal solution A- (worst performance) are determined from the weighted matrix Y. For "benefit" criteria (CPU, RAM, Disk I/O), A+ is the max value and A- is the min. For the "cost" criterion (Price), this is inverted.
   Sources: backend/main.py:380-383, topsis_spk.py:76-79
5. Distance Calculation: The Euclidean distance of each alternative from the positive ideal solution (D+) and the negative ideal solution (D-) is calculated.
   Sources: backend/main.py:386-387, topsis_spk.py:82-83
6. TOPSIS Score and Ranking: The final preference score for each alternative is calculated using the formula Score = D- / (D+ + D-). The alternatives are then ranked based on this score in descending order.
   Sources: backend/main.py:390-391, topsis_spk.py:86-87

Pydantic Data Models

Pydantic models are used extensively for data validation in API requests and for defining response structures.

This class diagram shows the main Pydantic models used for API communication.