Semester project - fidransky/kiv-pia-labs GitHub Wiki

We'll implement a naive web app connecting language translators with customers who need their documents translated.

Business Analysis

Actors

  • Customer
  • Translator
  • Administrator

Functional Requirements

  • Customer creates translation projects in the service, submitting source files (any file type) in English
  • Service finds suitable translator for given project based on the target language, assigns the project and notifies the translator via email; if no translator is found, service closes the project and notifies the customer via email
  • Translator completes the project, service notifies the customer via email
  • Customer approves/rejects completed translations and submits feedback to the project
  • Administrator resolves customer feedback, sending messages to customer/translator and ultimately closing the whole project
  • Payments are not handled in any way

Non-Functional Requirements

  • Service provides web UI (server-side or client-side, we'll discuss both during the labs)
  • Service provides API (REST or GraphQL, we'll discuss both during the labs) described by API documentation
  • Web UI is translated to English and one more language, it allows switching languages easily
  • Users can log in using username/password and one more authentication method (passkeys, OAuth2, Kerberos, WebAuthn, OTP, ...)
  • Authentication details must be stored securely (e.g. hashed passwords)
  • Service can be started with one command, preferably using Docker Compose
  • Maximum upload file size must be limited (e.g. 5 MB)
  • Emails are sent to a mocked mail server

Technical Analysis

Entities

User:

  • id: uuid
  • name: alphanumeric string
  • emailAddress: alphanumeric string; unique
  • role: enum<CUSTOMER, TRANSLATOR, ADMINISTRATOR>

TranslatorLanguage:

  • translatorId: uuid
  • languageCode: ISO 639-1 two-letter alpha-2 language code

Project:

  • customerId: uuid
  • translatorId: uuid, nullable
  • languageCode: ISO 639-1 two-letter alpha-2 language code
  • originalFile: blob
  • translatedFile: blob, nullable
  • state: enum<CREATED, ASSIGNED, COMPLETED, APPROVED, CLOSED>
  • createdAt: datetime

Project state transitions:

stateDiagram-v2
    direction LR

    [*] --> Created
    Created --> Assigned
    Assigned --> Completed
    Completed --> Approved
    Approved --> Closed
    Closed --> [*]

    Completed --> Assigned
    Created --> Closed

Feedback:

  • projectId: uuid
  • text: string
  • createdAt: datetime

Data Hierarchy

  • Translator -> TranslatorLanguage (1:N) - One translator can work with several languages.
  • Customer -> Project (1:N) - One customer can create many projects.
  • Translator -> Project (1:N) - One translator can work on many projects at the same time.
  • Project -> Feedback (1:1) - One project can only hold one feedback.

Authorization

Each user role is authorized to do a different set of tasks.

Anonymous:

  • register as a customer
  • register as a translator
  • log in

Customer:

  • create new projects
  • see a list of own projects
  • accept completed projects
  • reject completed projects, providing feedback for the translator

Translator:

  • see a list of assigned projects which are not closed yet, including customer feedback
  • download original project file
  • submit translated file to assigned projects

Administrator:

  • see a list of all projects which have some feedback, optionally filtered by state
  • react to customer feedback by sending a message to customers/translators (in-app or via email)
  • mark project as closed

Allowed Technology

If I've heard of it, it's allowed.

For dynamically typed languages with optional type system, using types is mandatory. That is: Node.js with Typescript, PHP with type declarations etc.

Preferred stack: JDK 21, Maven, Spring Boot 3, MySQL, JavaScript

Implementation Requirements

  • Correct implementation of selected architecture
  • Correct separation of application layers
  • Reasonably long methods (typically 50-100 lines, exceptions allowed)
  • Well-commented methods/functions, data models, attributes
  • Logs written where appropriate and structured (log levels, common format)
  • Project creation module covered with automated tests (unit tests of project creation and assignment business logic, integration tests of project creation storage)
  • Configurations must be read from property files, environment variables etc.

Evaluation

50 points maximum, subtracting points for any violation of requirements. 25 points minimum.

Submission

Submit your semester projects to Courseware, due date is 18 January 2026.