Architecture Overview

Relevant source files

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

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

The SPK Kajek project is a Decision Support System (DSS) designed to help select the best Cloud VPS server using the TOPSIS method. The system is built on a modern, decoupled client-server architecture. The frontend is a Single Page Application (SPA) built with React, which communicates with a Python-based backend via a REST API. This separation allows for independent development, deployment, and scaling of the user interface and the core business logic.

The backend is responsible for the core TOPSIS calculations, data management, and user authentication, while the frontend provides a rich, interactive user experience with data visualizations and real-time analysis capabilities.

Sources: SUMMARY.md, README.md, frontend/src/components/DocumentationView.tsx:23-28

High-Level System Architecture

The system is composed of three primary layers: the Frontend (Client), the Backend (Server), and the Data Layer. The client interacts with the backend through a REST API over HTTP, exchanging data in JSON format. The backend, in turn, interacts with the file-based data layer to read input data and persist user information and calculation history.

Sources: SUMMARY.md, frontend/src/components/DocumentationView.tsx:114-128

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

Frontend Architecture

The frontend is a modern Single Page Application (SPA) built using React, TypeScript, and Vite. It is responsible for all user interface elements, data visualization, and client-side state management.

Sources: README.md:21-33, frontend/package.json

Technology Stack

Technology	Purpose
React 18	UI Framework
TypeScript	Type Safety
Vite	Build Tool & Dev Server
Tailwind CSS	Utility-first CSS Styling
Framer Motion	Animations and transitions
Recharts	Data Visualization (Charts)
Axios	HTTP Client for API communication
Lucide React	Icons
Three.js	3D Visualizations

Sources: SUMMARY.md, DASHBOARD_README.md, frontend/package.json

Key Components

The frontend is structured into several key views and reusable components:

Component	Description
DashboardView.tsx	The main landing page with statistics and an overview.
AnalysisView.tsx	Handles weight configuration and triggers the TOPSIS calculation.
CalculationView.tsx	Displays the step-by-step results of the TOPSIS algorithm.
DataView.tsx	Provides CRUD operations for managing vendor data.
HistoryView.tsx	Shows a log of past calculations.
LoginView.tsx	Manages user authentication.
api.ts	An Axios-based service for all backend communication.

Source: SUMMARY.md

Backend Architecture

The backend is a RESTful API service built with FastAPI, a high-performance Python web framework. Its primary responsibilities include user authentication, processing TOPSIS calculations, and managing data persistence to the file system.

Sources: backend/main.py, SUMMARY.md

Technology Stack

Technology	Purpose
FastAPI	REST API Framework
Python 3.8+	Core programming language
Pydantic	Data validation and settings management
Pandas	Data processing and manipulation
OpenPyXL	Reading from and writing to Excel files
python-jose (JWT)	JWT-based user authentication

Sources: backend/main.py:1-17, README.md:35-43

Core Logic

• TOPSIS Calculation: The /api/calculate and /api/calculate-detail endpoints contain the full TOPSIS algorithm logic. This includes data normalization, weighting, identifying ideal solutions, and calculating the final scores.
• Data Handling: The backend uses Pandas to read vendor data from TOPSIS_Input_Level.xlsx and performs calculations. It also handles CRUD operations by reading, modifying, and saving the Excel file.
• Authentication: Implements JWT-based authentication. It handles user login, password hashing (PBKDF2), token creation, and validation for protected endpoints.

Sources: backend/main.py:414-504, 82-105

Data Layer

The application uses a file-based system for data storage instead of a traditional database. This simplifies setup and deployment.

Sources: backend/main.py:22-25, frontend/src/components/DocumentationView.tsx:124-127

Data Models

The following diagram shows the main data files and their purpose.

• TOPSIS_Input_Level.xlsx: The primary source of truth for vendor data. It contains the list of VPS providers and their specifications, represented as levels (1-5). The backend reads this file for all calculations and CRUD operations.
• users.json: Stores user account information, including usernames and hashed passwords. A default admin user is created if the file doesn't exist.
• calculation_history.json: A JSON array that logs the results of past TOPSIS analyses, including the weights used, top results, and a timestamp.

Sources: backend/main.py:22-25, 110-121, 647-652

API and Data Flow

Communication between the frontend and backend is handled via a REST API. The frontend uses Axios to make HTTP requests to the FastAPI endpoints.

API Endpoints

The backend exposes several endpoints to manage data and perform calculations.

Method	Endpoint	Description
POST	/api/login	Authenticates a user and returns a JWT.
GET	/api/profile	Retrieves the current user's profile.
PUT	/api/profile	Updates the current user's profile.
POST	/api/change-password	Changes the user's password.
GET	/api/data	Retrieves all vendor data from the Excel file.
POST	/api/data	Adds a new vendor to the Excel file.
PUT	/api/data/{vendor_no}	Updates an existing vendor.
DELETE	/api/data/{vendor_no}	Deletes a vendor.
POST	/api/calculate	Runs the TOPSIS calculation with given weights.
POST	/api/calculate-detail	Returns step-by-step matrices for the TOPSIS calculation.
GET	/api/history	Retrieves the calculation history.
POST	/api/history	Saves a new calculation result to the history.

Source: backend/main.py

TOPSIS Calculation Flow

The sequence diagram below shows the interaction when a user performs a TOPSIS analysis.

Authentication and Security

Security is managed through a JWT-based authentication system. Access to most API endpoints is protected and requires a valid Bearer token.

Sources: backend/main.py:79-178, frontend/src/components/DocumentationView.tsx:71-112

Authentication Flow

1. The user submits a username and password via the LoginView.
2. The frontend sends a POST request to /api/login.
3. The backend verifies the credentials against the hashed password stored in users.json.
4. If valid, the backend generates a JWT with a 24-hour expiration and returns it to the frontend.
5. The frontend stores the token (e.g., in localStorage) and includes it in the Authorization header for all subsequent requests to protected endpoints.

Sources: backend/main.py:181-216, frontend/src/services/api.ts

The following diagram illustrates the login process.

Security Measures

• Password Hashing: Passwords are not stored in plaintext. They are hashed using PBKDF2-HMAC-SHA256 with a salt and 100,000 iterations.
• Token Expiration: JWTs are configured to expire after 24 hours, requiring re-authentication.
• CORS: The backend has CORS middleware enabled to control which origins can access the API.

Sources: backend/main.py:15-20, 82-96, 131-135