KTUSA-PS/README.md

KTUSA Problemų Sistema (KTUSA-PS)

Status: Archived (development discontinued mid–2022)

1. Historical Note

Development began around 2020 as an initiative of the InfoSA academic committee. Due to a lack of continued institutional interest in deploying the platform, active work ceased around mid‑2022.

The creator (Karolis K.) previously collaborated with other InfoSA members on an earlier iteration of the system implemented with the Symfony PHP framework. This second iteration (the one in this repository) was a full rewrite using ASP.NET Core + Vue 3 and was developed solely by Karolis.

The information system (IS) was submitted in January 2022 as coursework for the university module: T120B165 "Saityno taikomųjų programų projektavimas"
(https://uais.cr.ktu.lt/ktuis/stp_report_ects.mdl_ml?p_kodas=T120B165&p_year=2021&p_lang=LT&p_stp_id=8058)

No further functional evolution, security hardening, or production deployment steps were performed after the academic submission phase.

2. Overview

KTUSA-PS (KTU Student Association Problem System) is a web platform for registering, classifying, moderating, and publishing student issues and feedback. It was designed as a Single Page Application (SPA) with a REST API backend, emphasizing transparency in problem resolution workflows within the student community.

The original detailed Lithuanian system description remains in SISTEMA.md.

3. Technology Stack

Backend (.NET)

• Framework: ASP.NET Core (C#)
• Data Access: Entity Framework Core (Code First)
• Database: MySQL
• Authentication & Authorization: Azure Active Directory (MSAL) + JWT Bearer
• API Documentation: Swagger / OpenAPI
• Pattern: MVC + separated data layer project (KTUSAPS.Data)

Frontend (Vue.js)

• Framework: Vue.js 3 (Composition API)
• Router: Vue Router 4
• State Management: Vuex 4
• UI: Bootstrap 5 + Bootstrap Icons
• Build Tool: Vite
• HTTP Client: Axios
• Authentication: MSAL Browser library (Azure AD integration)

4. Core Functional Domains

For Students

1. Submit issues / problems
2. Choose issue types (categorization)
3. Provide feedback / comments and votes

For Administrators

1. Manage issues (review, update status, resolve)
2. Maintain issue types (create / edit bilingual categories)
3. Control publication of problems & solutions
4. Moderate published feedback

5. Data Model (Key Entities)

• Issue – core submitted problem (type, description, resolution state)
• IssueType – bilingual (LT/EN) classification metadata
• PublishedProblem – publicly visible version of an issue
• PublishedFeedback – publicly visible feedback / commentary
• Admin – administrator role assignments
• Vote – rating / voting entity for feedback or solutions

6. Security Features (As Implemented)

1. Azure AD authentication (institutional accounts)
2. Role / claim-based authorization for admin-only areas
3. JWT validation for API access control
4. HTTPS-first assumptions (no explicit production reverse-proxy hardening done)
5. Localized security warnings (e.g., unsafe context notices)

Note: Since the system was never hardened for production, additional measures (rate limiting, auditing, CSP, advanced logging, backup strategy) were not finalized.

7. Architecture Highlights

• SPA frontend served alongside ASP.NET Core backend
• RESTful API boundaries; clear separation of concerns
• Separate data project (KTUSAPS.Data) to isolate Entity Framework models & migrations
• Bilingual support (Lithuanian / English) for selected entities
• Responsive UI leveraging Bootstrap 5

8. Project Structure (Simplified)

KTUSA PS.sln
├── KTUSAPS/                 # Web application (API + SPA host)
│   ├── Controllers/         # API endpoints
│   ├── Auth/                # Authorization handlers & policies
│   ├── Services/            # (Planned/initial) business services
│   ├── ClientApp/           # Vue 3 application (Vite)
│   │   ├── src/
│   │   │   ├── components/
│   │   │   ├── pages/
│   │   │   ├── router/
│   │   │   └── store/
│   │   ├── package.json
│   │   └── vite.config.js
│   ├── Startup.cs / Program.cs
│   └── appsettings*.json
└── KTUSAPS.Data/            # Data layer (DbContext + EF models + migrations)
    ├── Model/
    ├── Migrations/
    └── SAPSDataContext.cs

9. Getting Started (Historical Dev Setup)

Prerequisites:

• .NET 6 SDK
• Node.js 16+ (with npm)
• MySQL Server (local or remote)

Backend

cd KTUSAPS
dotnet restore
dotnet run

The API will start on the configured Kestrel port (see launchSettings.json).

Frontend

cd KTUSAPS/ClientApp
npm install
npm run dev

Vite dev server will proxy or call the API directly (adjust base URLs in Axios / config if needed).

Database

1. Create a MySQL database (e.g., ktusaps_db).
2. Update the connection string in KTUSAPS/appsettings.Development.json (or appsettings.json).
3. Apply migrations:

cd KTUSAPS
dotnet ef database update

If dotnet ef is not available, install tools: dotnet tool install --global dotnet-ef.

10. Authentication Configuration (Azure AD)

The project expects Azure AD application credentials (Tenant ID, Client ID, etc.) in configuration. Since the environment is no longer active, placeholders may exist. For reenabling:

• Register an app in Azure AD
• Configure redirect URIs for SPA & API
• Populate settings (e.g., AzureAd section) in appsettings.Development.json

11. Usage Flow (Conceptual)

1. User authenticates via Azure AD popup (MSAL in browser).
2. Access token is obtained and attached to API calls (Bearer token).
3. Student submits an issue (Issue stored; optionally flagged for publication later).
4. Admin reviews issues, assigns type, updates status.
5. Issue may be published (becomes PublishedProblem).
6. Feedback & votes are optionally published (PublishedFeedback).

12. Limitations / Incomplete Areas

• No production-grade logging & monitoring strategy
• Limited error handling / validation messages
• No automated CI/CD pipeline included
• Security hardening (headers, rate limiting, input sanitation depth) incomplete
• i18n only partial beyond data fields (UI translations not fully finalized)
• Testing (unit/integration) minimal to none in repository

13. Academic Context

This codebase primarily served as an academic / portfolio artifact rather than a deployed organizational system. It demonstrates full-stack integration (Azure AD auth, EF Core, SPA frontend) rather than polished end-user production readiness.

14. Contribution & Maintenance

This repository is unmaintained. Pull requests are unlikely to be reviewed. Fork if you wish to build upon it. Consider upgrading dependencies (ASP.NET Core version, Vue tooling, MSAL libraries) before any reuse.

15. License

Released under the MIT License. See the LICENSE file for the complete text and copyright notice.

16. Credits

Author: Karolis K.
Initial concept support: InfoSA academic committee (earlier iteration collaboration).

---

For the original Lithuanian descriptive document, see SISTEMA.md.