Skip to content
This repository was archived by the owner on Dec 2, 2025. It is now read-only.

USER_MANUAL.md

Latest commit

 

History

History
432 lines (272 loc) · 9.95 KB

USER_MANUAL.md

File metadata and controls

432 lines (272 loc) · 9.95 KB
Raw

Ruggine: Secure Real-Time Chat Platform - User Manual

Technical Documentation

Detailed documentation for backend modules is available in /docs/backend/ and /docs/api/.

Table of Contents

  1. Project Description
  2. System Requirements
  3. Installation
  4. First Launch
  5. Registration and Login
  6. Main Interface
  7. Private Chats
  8. Groups
  9. Advanced Features
  10. User Profile
  11. Troubleshooting
  12. FAQ
  13. License
  14. Authors and Acknowledgments
  15. Document Version

1. Project Description

Ruggine is a real-time messaging platform designed to ensure security, privacy, and performance through end-to-end (E2E) encryption and advanced session management. The project represents a concrete example of a scalable application, developed entirely in Rust.

Main Features

  • End-to-End Encryption: Completely private and encrypted messages
  • Private Chats and Groups: Communicate with individual users or groups
  • Typing Indicators: Know when someone is typing
  • Responsive Interface: Works on desktop and mobile
  • Modern Design: Intuitive interface

2. System Requirements

To Use the Web Application

  • Browser: Chrome, Firefox, Safari or Edge
  • Connection: Stable internet
  • Operating System: Windows, macOS, Linux, Android and iOS

To Install Locally (Developers)

  • Node.js: version 16.x or higher
  • Rust: version 1.70 or higher
  • SQLite: included automatically
  • Docker (optional): for containerization

Key Technologies:

  • Language: Rust (recommended: rustc 1.70.0 or higher)
  • Main Frameworks/Libraries: Axum, Tokio, SQLx, Serde, Redis, Scrypt, AES-GCM, uuid, chrono
  • Database: SQLite (relational, embedded)
  • Tooling: Cargo, Redis, PlantUML

3. Local Installation

Step 1: Clone the Repository

git clone https://github.com/PdS2425-C2/G38.git
cd G38

Step 2: Install Frontend Dependencies

cd frontend
npm install
cd ..

Step 3: Start the Application

./start.sh

Startup options:

  • ./start.sh - Start with clean database (default)
  • ./start.sh --maintaindb - Maintain existing data
  • ./start.sh --help - Show all available options

Step 4: Access the Application

Once started, access it at:

http://localhost:3002

4. First Launch

Test Accounts (Development Environments)

If you start locally, 10 test accounts are available:

  • Users: user1 - user10
  • Password: demo123456

Log in with one of these accounts to test the features.

5. Registration and Login

Login

To log in, enter your Username and your Password. Your password also serves as the decryption key for your messages, so it is essential not to forget it.

Login Screen The login screen allows you to log in or switch to registration.

Registration

If you don't have an account, click on "Sign up" on the login page. You will need to provide:

  • Username (minimum 3 characters)
  • Password (minimum 8 characters)
  • Confirm Password

Important: Since we use E2E encryption based on your password, it is not possible to recover the password if you forget it. Your messages would be lost forever.

Demo Accounts

To try the application quickly, buttons are available on the login page to access with preconfigured demo accounts (user1, user2, etc.). The password for all is demo123456.

  1. Active Session
    • The session remains active until you log out
    • If you close the browser, you remain logged in when you return

Logout

  1. Click on the menu icon (hamburger ☰) at the top left
  2. Select "Exit"
  3. You will be redirected to the login page

6. Main Interface

After logging in, you will be redirected to the main Chat screen.

Desktop

On desktop, the interface is divided into two columns:

  • Left (Sidebar): List of recent conversations and user status.
  • Right (Chat View): The currently selected conversation.

Chat Interface Example of the chat interface with the list on the left and messages on the right.

Mobile

On mobile devices, the interface is optimized:

  • Chat List: You view the list of conversations.
  • Chat View: Tapping a conversation opens it full screen.
  • Navigation: Use the "Back" arrow in the chat header to return to the list.

Main Elements

Navbar (at the top)

  • Logo/Application Name
  • Profile menu

Sidebar/Chat List (left)

  • List of all active conversations
  • Online status indicator (green = online, gray = offline)
  • Unread indicator (blue number)
  • Typing indicator (gray)

Main Chat Area

  • Messages from the selected conversation
  • Received messages on the left, sent on the right
  • Shows who is typing
  • Input field to write messages

7. Private Chats

Starting a Private Chat

Method 1: From the Search Bar

  1. Click on Start chat (🔍) in the navbar
  2. Type the username of the person you want to chat with
  3. Select the user from the results
  4. The chat opens automatically

Status Indicators

  • (green) = User online
  • (gray) = User offline
  • (gray) = User is typing

8. Groups

Group Management

Creating a New Group

  1. Access the Groups section

    • Click on "Groups" in the navbar or sidebar

  2. Click on "Create Group"

    • A creation dialog appears

  3. Fill in the Details

    • Group Name: Name of the group conversation (required)
    • Description: Brief description (optional)
    • Avatar/Image: Group photo (optional)

  4. Select Members

    • Search and add the users you want to invite (minimum 2 members, besides you)

  5. Create the Group

    • Click "Create"
    • The group is created and members receive an invitation

Managing a Group (as Owner/Admin)

Modify Information:

  1. Access the group
  2. Click on the settings icon at the top right
  3. Modify name, description, avatar
  4. Save changes

Add Members:

  1. Click on "Invite Users" in the settings
  2. Search and select users
  3. Send the invitation

Remove Members:

  1. Go to the group settings
  2. Select the member to remove from the members list
  3. Click "Remove"
  4. The member will be removed from the group

Delete the Group:

  1. Go to settings
  2. Click "Delete Group"
  3. Confirm the action
  4. The group is deleted for all members

Managing a Group (as Member)

View Details:

  • Click on the group name at the top

Leave the Group:

  1. Go to settings
  2. Click "Leave Group"
  3. Confirm
  4. You will be removed and will no longer see the group

Sending Messages in a Group

  • The procedure is identical to private chats
  • Type the message and press Enter
  • All group members will receive the message

Group Invitations

Receiving an Invitation:

  1. An invitation appears in the "Invitations" section
  2. Click "Accept" to join the group
  3. Click "Decline" to decline

Accepting an Invitation:

  1. Visit the "Invitations" page from the menu
  2. Select the invitation
  3. Click "Accept"
  4. You will be added to the group

9. Advanced Features

Typing Indicators

When someone is typing in the conversation, you will see:

  • An indication or "someone is typing..."
  • This disappears when the message is sent

10. User Profile

Accessing the Profile

  1. Click on the profile icon in the navbar
  2. Or click on your avatar in the sidebar

Modifying the Profile

Change Avatar/Profile Photo:

  1. Click on the profile photo
  2. Select an image from your device (JPG, PNG, WEBP are supported; max 5MB)
  3. The photo is uploaded automatically
  4. If you don't upload a photo, you will see your initial as avatar

11. Troubleshooting

I Cannot Log In

Possible Causes and Solutions:

  1. Wrong Password

    • Verify that you have typed the correct password (pay attention to uppercase letters)
    • Use the "Forgot Password" function if available

  2. Expired Session

    • Log out and log in again
    • Clear browser cookies if the problem persists

  3. Connection Problems

    • Verify that you have a stable internet connection
    • Try with another browser
    • Restart the browser

Messages Are Not Being Sent

Possible Causes and Solutions:

  1. No Internet Connection

    • Verify the connection
    • If the message shows, the message was not sent
    • Once reconnected, the message will be sent automatically

  2. Recipient Offline

    • If the user is offline, the message will still be delivered when they reconnect
    • This is normal behavior

  3. Expired Session

    • Log out and log in again
    • Try sending the message again

I Cannot Find a User

Possible Causes and Solutions:

  1. Wrong Username

    • Verify the exact spelling of the username
    • Usernames are case-sensitive (uppercase/lowercase matters)

  2. User Not Registered

    • The user might not have signed up yet
    • Ask the person for the exact username

  3. Deleted User

    • If the account was deleted, it will no longer be visible

12. FAQ

(This section is currently under development. For any questions not covered in the Troubleshooting section, please refer to the technical documentation or contact support.)

13. License

This project is distributed under the MIT license.

14. Authors and Acknowledgments

Authors: Alessio Meini, Luca Ostinelli, Simone Ventura, Luca Visconti

Supervisor: Prof. Maurizio Rebaudengo

Completion Date: December 2, 2025

15. Document Version

  • Date: December 2, 2025
  • Version: 1.0
  • Application: Ruggine Chat Platform
  • Status: Production Ready
  • Future Updates: At the discretion of the development team