168 lines
7.1 KiB
Markdown
168 lines
7.1 KiB
Markdown
# 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
|
||
```bash
|
||
cd KTUSAPS
|
||
dotnet restore
|
||
dotnet run
|
||
```
|
||
The API will start on the configured Kestrel port (see `launchSettings.json`).
|
||
|
||
### Frontend
|
||
```bash
|
||
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:
|
||
```bash
|
||
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`.
|