event-management-frontend/README.md

# Event Management Frontend

The Event Management Frontend is a native Android application developed in
Kotlin. This app provides a comprehensive calendar-based event management
system designed for seamless user interaction.

This project was created as the final assignment for **AP7PD** and **AP7MP** subjects.

It integrates with a custom backend REST API to manage users, events,
attendees, and categories effectively.

## Overview / Key Features

- **Monthly Calendar View:** The default landing page of the app provides a
  neatly organized monthly calendar view. Days are displayed in a grid layout
  with rows representing weeks. Days with events are highlighted. Users can
  navigate between months using arrow buttons.
- **Daily View:** An interface for viewing and managing events for a specific
  day. Events are displayed as easy-to-read cards, ordered by their start times.
  From here, users can create new events, edit or delete their own events, leave
  invited events, or view detailed event information.
- **Event Management:** Fully featured event management allows users to create,
  edit, and delete events. Events support color selection from a color picker,
  detailed descriptions, and attendee invitations. Invited events are integrated
  into the calendar, and invite notifications provide quick actions for managing
  responses.
- **Category Management:** Users can create, edit, and delete event categories.
  These categories can be assigned to events to organize them effectively.
  Categories also support color selection for easy identification.
- **User Authentication:** Secure and robust authentication with automatic
  login for valid session tokens. Tokens are securely stored & persist across app
  restarts, allowing users to access the app without needing to reauthenticate
  every time they open it. Registration and login are straightforward, and access
  tokens are refreshed automatically to maintain session continuity. Once a
  refresh token expires, the user is automatically logged out and redirected to
  the login screen.
- **Invitations and Notifications:** Users can invite others to events, and
  invitations appear as notifications. Invite notifications contain support
  actions like marking as read, previewing the event details, accepting or
  declining the invitation, and deleting the notification. When an invitation
  is accepted or declined, the inviter receives a notification update, letting
  them know about the acceptance/rejection.
- **Error Handling and API Base URL Management:** When the app cannot connect
  to the API server, a dedicated error screen is displayed. From this screen,
  users can modify the API base URL, allowing seamless switching to another
  server if needed. This Base URL setting is also accessible from the login and
  register screens.
- **Settings and Account Management:** The settings screen is accessible to
  logged in users and offers comprehensive account management. Users can update
  their username, email, and password, delete their account, or log out. The API
  base URL can also be adjusted from here.
- **Event Details View:** A detailed view displays complete event information,
  including its creation date, description, attendees, categories, and, if
  applicable, the event owner's details for invited events. This page offers a
  full view of the event, unlike the event cards shown in the day view, which
  only show a summary.
- **Color-Coded Visuals:** Both events and categories support color
  customization via a built-in color picker, making it easy to differentiate and
  organize items visually.
- **Clean and Intuitive UI:** The app's design prioritizes usability and
  clarity, with features like the event-based day highlights in the monthly view
  and a simple card format for daily events. All functionalities are accessible
  through logically organized pages and actions.
- **Notifications System:** The notification page supports the previously
  described invite notifications, but also general message notifications, which
  the administrator can send (currently only possible by directly adding it to
  the database, as the API doesn't support privileged/admin accounts, though
  this would be possible to add in the future). Note that the app doesn't
  support push notifications, so notifications are only visible from the
  notifications screen when the app is open, however, this could be implemented
  in the future as well.

## Backend requirements

The application requires a running backend API for full functionality. The
backend is implemented using FastAPI in Python.

You can find the source code and detailed deployment instructions for the
backend API at: [Event Management Backend
Repository](https://git.itsdrike.com/ap7pd/event-management-backend).

> [!TIP]
> The app supports dynamic configuration of the API base URL, allowing you to
> deploy the backend on any server or cloud provider of your choice. If you
> wish to test the app from android studio, you can deploy the backend locally
> (<http://localhost:8000>) and set the base URL to `http://10.0.2.2:8000`.
> This will allow the Android emulator to access the local backend server. Note
> that this is also the default value.

## Showcase

Below is a showcase of key features and screens in the application:

<table>
  <!-- First Image Row -->
  <tr>
    <th>📶 API Unreachable</th>
    <th>🔒 Login Screen</th>
    <th>🔧 Base URL Change</th>
  </tr>
  <tr>
    <td>
      <img src="showcase/01_api_unreachable.png" alt="API Unreachable" />
    </td>
    <td>
      <img src="showcase/02_login.png" alt="Login Screen" />
    </td>
    <td>
      <img src="showcase/02_login_base_url_change.png" alt="Base URL Change" />
    </td>
  </tr>

  <!-- Second Image Row -->
  <tr>
    <th>📝 Register Screen</th>
    <th>📆 Month View</th>
    <th>📅 Day View</th>
  </tr>
  <tr>
    <td>
      <img src="showcase/03_register.png" alt="Register Screen" />
    </td>
    <td>
      <img src="showcase/04_month_view.png" alt="Month View" />
    </td>
    <td>
      <img src="showcase/05_day_view.png" alt="Day View" />
    </td>
  </tr>

  <!-- Third Image Row -->
  <tr>
    <th>⏳ Edit Duration Event</th>
    <th>⚡ Edit Instant Event</th>
    <th>📨 Invite User to Event</th>
  </tr>
  <tr>
    <td>
      <img src="showcase/06_duration_event_edit.png" alt="Edit Duration Event" />
    </td>
    <td>
      <img src="showcase/07_instant_event_edit.png" alt="Edit Instant Event" />
    </td>
    <td>
      <img src="showcase/08_invite_user_to_event.png" alt="Invite User to Event" />
    </td>
  </tr>

  <!-- Fourth Image Row -->
  <tr>
    <th>⏱️ Duration Event Details</th>
    <th>🔍 Instant Event Details</th>
    <th>📂 Categories Overview</th>
  </tr>
  <tr>
    <td>
      <img src="showcase/09_duration_event_details.png" alt="Duration Event Details" />
    </td>
    <td>
      <img src="showcase/10_instant_event_details.png" alt="Instant Event Details" />
    </td>
    <td>
      <img src="showcase/11_categories.png" alt="Categories Overview" />
    </td>
  </tr>

  <!-- Fifth Image Row -->
  <tr>
    <th>➕ Create New Category</th>
    <th>🆕 Updated Categories Overview</th>
    <th>⚙️ Settings Screen</th>
  </tr>
  <tr>
    <td>
      <img src="showcase/12_new_category.png" alt="Create New Category" />
    </td>
    <td>
      <img src="showcase/13_categories_with_new.png" alt="Updated Categories" />
    </td>
    <td>
      <img src="showcase/14_settings.png" alt="Settings Screen" />
    </td>
  </tr>

  <!-- Sixth Image Row -->
  <tr>
    <th>🔔 Notification: Invite</th>
    <th>👀 Invite Preview</th>
    <th>✅ Notification: Accepted</th>
  </tr>
  <tr>
    <td>
      <img src="showcase/15_notification_invite_bob.png" alt="Notification: Invite" />
    </td>
    <td>
      <img src="showcase/16_invite_event_details_preview.png" alt="Invite Preview" />
    </td>
    <td>
      <img src="showcase/17_notification_invite_accepted_bob.png" alt="Notification: Accepted" />
    </td>
  </tr>

<!-- Final Row -->
  <tr>
    <th colspan="3">🗑️ Notifications Cleared</th>
  </tr>
  <tr>
    <td colspan="3" align="center">
      <img src="showcase/21_notifications_cleared.png" alt="Notifications Cleared" />
    </td>
  </tr>
</table>