Calendula

<sub>ucode connect chronos "Calendula" is the project of ucode connect the Track FullStack programming bootcamp
lasting 4 weeks (March 3, 2025 - March 28, 2025),
where the Node.js with JavaScript and React with TypeScript and FullCalendar were used to develop the event planner web-application.

The purpose: build a simple and powerful time planner
using the whole cycle of Challenge Based Learning framework with a team.</sub>

📑 Table of Contents

• 🗓️ About "Calendula" Calendar Application
• 🧑‍💻 Team
• 🌼 About "Calendula" Backend
• 🎯 Features and Functionality
  • 🔐 Authentication & Authorization
  • 👥 User Management
  • 📅 Calendar Management
  • 📝 Event Management
  • 🔔 Notification System
  • 👤 Event Participation
  • 🎨 User Interface & Experience
  • 📧 Email System
  • 🛡️ Security Features
  • 🎯 Calendar Types
  • 🔍 Search & Filtering
  • 🌐 Holiday Integration
  • 🎂 Birthday Management
  • 🔧 API Documentation
  • 🧪 Testing Infrastructure
  • ⏰ Background Services
• 👤 Use case diagram
• 🧲 Activity diagram
• 🚚 Deployment Diagram
• 📦 Database Diagram
• ⚙️ Requirements and Dependencies
• 🚀 How to Run the Solution
• 🐋 Docker
• 📦 Database Migration
• ⏰ Task Scheduler
• 📫 Mailing Service
  • Gmail API Configuration
  • Development Testing with Ethereal
  • Email Templates
• 🔁 REST API documentation
  • API Features
• 🪲 API Testing
• 👤 Fake Data

🗓️ About "Calendula" Calendar Application

Calendula is an enterprise application that transforms time management with flexible calendars, interactive events, and team sync.

Organise your day, share ideas, and streamline your workflow with easy search, notifications, and a personalised design.

Here is a link to the presentation file.

🧑‍💻 Team

• 🧑🏼‍💻 Andrew Laskevych

• 👩🏼‍💻 Inessa Repeshko

• 🧑🏻‍💻 Vadym Zharyi

🌼 About "Calendula" Backend

The Calendula backend is built with Node.js and Express.js, providing a robust RESTful API for calendar and event management.

It features secure JWT-based authentication, MySQL database integration with comprehensive migration support, and automated email notifications through Nodemailer.

The architecture includes role-based access control, background task scheduling for event reminders, and comprehensive API documentation with Swagger integration.

🎯 Features and Functionality

This is a comprehensive calendar and task management platform that provides the following features:

🔐 Authentication & Authorization

• User registration with email verification and confirmation
• JWT-based authentication with secure session management
• Password reset functionality with secure token validation
• Role-based access control for calendar and event management
• Account settings and profile management

👥 User Management

• User profile management with personal information
• Account dashboard with personalized calendar view
• Multiple profile picture options for customization
• User search functionality for calendar and event invitations
• Country-based user settings for holiday calendars

📅 Calendar Management

• Personal calendar creation and management
• Default "Main" calendar for each user
• Automatic "National Holidays" calendar based on user's country
• Automatic "Birthdays" calendar for company employees
• Calendar sharing and collaboration features
• Calendar color customization for visual organization
• Calendar visibility controls (show/hide)
• Calendar grouping into team and system categories

👤 Calendar Access Control

• Owner: Full CRUD operations and participant management
• Member: View calendar, manage own events, invite participants
• Viewer: Read-only access to calendar and events

📝 Event Management

• Comprehensive event creation with detailed metadata
• Multiple event types: meetings, reminders, tasks
• Event scheduling with start and end times
• All-day event support with flexible duration
• Event color customization (inherits from calendar by default)
• Event categories: work, home, hobby
• Event description and detailed information
• Drag-and-drop event rescheduling
• Event duration resizing functionality

🔔 Notification System

• Pre-event notifications with customizable timing
• Notification options: 10 min, 30 min, 1 hour, 1 day before
• Email notifications for upcoming events
• Background task scheduler for automated notifications
• Event invitation and update notifications

👤 Event Participation

• Event participant invitation system
• Attendance status tracking: yes, no, maybe
• Visual event design changes based on attendance status
• Participant search by full name or email
• Searchable dropdown for user selection
• Event ownership indicators

🎨 User Interface & Experience

• Modern and responsive calendar interface
• Multiple calendar views: month, week, day
• Mini calendar sidebar with main view synchronization
• "Today" button for quick navigation
• Current day and time indicators
• Event search by title and description
• Interactive event creation by clicking on calendar
• Pop-up windows for quick event creation
• Detailed event creation pages

📧 Email System

• Smart Provider Selection: Automatically chooses between Ethereal and Gmail based on available credentials
• Priority System: Ethereal (testing) → Gmail (production) → Skip (no credentials)
• Automated Notifications: Email notifications for various events and user actions
• Account Management: Email confirmation for account verification and password reset
• Event Communications: Invitation emails and reminder notifications for events and calendars
• Flexible Configuration: Easy switching between email providers for different environments
• Development-Friendly: Ethereal integration for safe testing without sending real emails
• Production-Ready: Gmail OAuth2 integration for reliable email delivery

Email Provider Configuration

The system automatically selects the appropriate email provider:

1. Ethereal Email (Priority 1): Used when ETHEREAL_MAILER_LOGIN is configured

   • Perfect for development and testing
   • Safe email testing without real delivery
   • Preview emails at https://ethereal.email/

2. Gmail (Priority 2): Used when Ethereal is not configured and Gmail OAuth2 credentials are available

   • Production-ready email delivery
   • Requires Google OAuth2 setup with proper credentials
   • Reliable delivery for real users

3. Skip Mode (Priority 3): When no email credentials are configured

   • Logs email attempts without sending
   • Prevents application crashes in email-free environments

🛡️ Security Features

• Secure password hashing using Argon2
• JWT token-based authentication
• Input validation and sanitization
• Environment-based configuration management
• Access control policies for calendar and event operations

🎯 Calendar Types

• Personal Calendar: User's main calendar for personal events
• Shared Calendars: Collaborative calendars with multiple participants
• System Calendars: Special calendars (holidays, birthdays)
• Team Calendars: Organization-specific calendars

🔍 Search & Filtering

• Event search functionality by title and description

🌐 Holiday Integration

• Automatic national holiday calendar creation
• Country-specific holiday integration
• Holiday notifications and reminders
• One-day advance notifications for holidays

🎂 Birthday Management

• Automatic birthday calendar for company employees
• Birthday event creation and management
• Birthday notifications and reminders

🔧 API Documentation

• Comprehensive Swagger documentation for all endpoints
• Interactive API explorer available at /api-docs
• Detailed request/response schemas
• RESTful API design with proper HTTP methods

🧪 Testing Infrastructure

• Comprehensive API testing using Playwright
• Fake data generation for testing purposes
• Test database setup and teardown
• Automated test reporting and visualization

⏰ Background Services

• Task scheduler for automated event processing
• Email notification scheduler
• Recurring task management
• Background job processing for system maintenance

👤 Use case diagram

🧲 Activity diagram

🚚 Deployment Diagram

📦 Database Diagram

A free database visualiser at dbdiagram.io. Import database.dbml.

⚙️ Requirements and Dependencies

Before starting, ensure the required technologies are installed.

• Node.JS >= v22
• NPM >= v10
• MySQL >= 8.0

🚀 How to Run the Solution

In the examples of all commands in the text <env> is the name of the environment to perform the migration, e.g. development, test or production.

1. Clone this repository and move to the project directory.

   git clone <repository-url>

2. Install the dependencies.

   npm install

3. Configure the database connection by copying .env.development.example to new file .env.development. After that put your MySQL credentials. Example:

   DATABASE_HOST=localhost
   DATABASE_PORT=3306
   DATABASE_USER=root
   DATABASE_PASSWORD=root
   

   For test purposes you need to use test env. For this create .env.test based on the .env.test.example file.
4. Configure the migrations config by copying migration_config.json.example to new file db/migration_config.json. After that put your MySQL credentials to dev part. ☝️ Don't add part about "database".

   {
       "dev": {
          "driver": "mysql",
          "user": "root",
          "password": "root",
          "port": 3306,
          "multipleStatements": true
     }
   }

5. Run migration for create database Calendula.

   ENV=development npm run migrate:db:create:dev -- Calendula

   If you get the error “ifError got unwanted exception: Unknown database 'Calendula'”, then delete the ‘database’ field in the configuration file db/migration_config.json. Then run the command again.

6. Add the “database” field to db/migration_config.json. The devevopment environment configuration may look like this:

   {
       "dev": {
          "driver": "mysql",
          "user": "root",
          "password": "root",
          "port": 3306,
          "multipleStatements": true,
          "database": "Calendula"
     }
   }

7. Run migration for create tables in your database.

   npm run migrate:up:<env>

   If you encounter problems, try the command that will delete all tables and create them again.

   npm run migrate:refresh:<env>

8. Start the server.

   npm run start:<env>

9. Run seeds to fill database with test data.

   npm run seed:all:<env>
   

10. In new console you can run task scheduler. It's not necessary.

npm run scheduler:<env>

🐋 Docker

Environment variables are taken from .env.development file. You can start containers with the command:

docker-compose --env-file .env.development up -d

📦 Database Migration

Migrations are possible on such environments: development, test, and production.

Environment settings are loaded from a ./db/migration_config.json file. Create your ./db/migration_config.json file and add the properties for the environments to it. To do this, copy ./db/migration_config.json.example or to ./db/migration_config.json. Then edit ./db/migration_config.json if necessary (e.g. add a test database).

Note that migrations are only possible on existing databases. Therefore, create your database first. Example of a database creation query to be executed in the database console:

DROP DATABASE IF EXISTS Calendula;
CREATE DATABASE Calendula;
USE Calendula;

or

DROP DATABASE IF EXISTS Calendula_Test;
CREATE DATABASE Calendula_Test;
USE Calendula_Test;

Or use commands:

migrate:db:drop:<env> && migrate:db:create:<env>

In the examples of all commands in the text <env> is the name of the environment to perform the migration, e.g. development, test or production.

To create tables in the database, execute the command:

npm run migrate:up:<env>

To update the tables in the database, run the following command:

npm run migrate:refresh:<env>

Full list of commands:

1. The create command creates a migration that loads sql file with the name <migration-name> in configured migrations directory ./db/migrations.

   npm run migrate:create:<env> -- <migration-name>

Where <migration-name> is the name of the migration you are creating, e.g., update-events-categories. 2. The up command executes the migrations of your currently configured migrations directory. More specific the up migrations are being called.

npm run migrate:up:<env>

3. The down command executes the migrations of your currently configured migrations directory. More specific the down migrations are being called.

   npm run migrate:down:<env>

4. The reset command is a shortcut to execute all down migrations and literally reset all migrations which where currently done. The reset command also executes by default only the first scope.

   npm run migrate:reset:<env>

5. To perform reset and up, run the following command:

   npm run migrate:refresh:<env>

6. For create database try this command with {DATABASE_NAME}:

   npm run migrate:db:create:<env> -- {DATABASE_NAME}

7. For delete database try this command with {DATABASE_NAME}:

   npm run migrate:db:drop:<env> -- {DATABASE_NAME}

Answers to other questions can be found in the official db-migrate documentation.

⏰ Task Scheduler

Our service can process tasks in the background. Currently, we use it to send email notifications about upcoming events. Scheduler is available on such environments: development, test, and production. To start the service, you need to run the command.

npm run scheduler:<env>

📫 Mailing Service

The application uses Gmail API for production email delivery with OAuth2 authentication, providing reliable and secure email sending capabilities.

Gmail API Configuration

The application is configured to use Gmail API for sending emails in production. To set up Gmail integration:

1. Google Cloud Console Setup:
   • Create a project in Google Cloud Console
   • Enable Gmail API for your project
   • Create OAuth 2.0 credentials (Client ID and Client Secret)
   • Add your redirect URI for OAuth flow
2. Environment Configuration: Configure the following variables in your .env.development file:

   GOOGLE_GMAIL_USER=your-gmail@gmail.com
   GOOGLE_GMAIL_API_REFRESH_TOKEN=your_refresh_token
   GOOGLE_CLIENT_ID=your_client_id
   GOOGLE_CLIENT_SECRET=your_client_secret
   GOOGLE_OAUTH_REDIRECT_URI=your_redirect_uri

3. OAuth2 Flow:
   • Use Google OAuth2 flow to obtain refresh token
   • The application automatically refreshes access tokens as needed

Development Testing with Ethereal

For development and testing purposes, you can use Ethereal Email - a fake SMTP service where messages are captured but never delivered.

Default test credentials you can find in .env.development.example:

• login: ricky43@ethereal.email
• password: 4e1zbM2nxsMu2d823E

Email Templates

Email types supported:

• Account email confirmation
• Password reset notifications
• Event invitation emails
• Event reminder notifications
• Calendar invitation emails

🔁 REST API documentation

The comprehensive API documentation is available at http://localhost:8080/api-docs/ and provides:

• Interactive API Explorer: Built with Swagger UI, allowing you to test endpoints directly in the browser
• Complete Endpoint Coverage: Documentation for all available REST endpoints including authentication, users, calendars, events, notifications, and email services
• Security Documentation: Clear indication of which endpoints require JWT authentication
• Request/Response Schemas: Detailed schema definitions with examples for all data structures
• Error Response Documentation: Comprehensive error codes and response formats
• Automated Documentation: The system automatically generates documentation from code annotations and validation decorators

API Features:

• JWT Authentication: Bearer token authentication for protected endpoints
• Role-based Access Control: Different access levels for calendar and event management (Owner, Member, Viewer)
• Input Validation: Request validation with detailed error messages using Express Validator
• Pagination Support: Pagination for large datasets of events and calendars
• Real-time Validation: Comprehensive input validation and sanitization

The documentation is generated using Swagger and includes interactive testing capabilities for easier development and integration.

🪲 API Testing

Create an .env.test file and add the variables for the test environment to it. To do this, copy .env.test.example or to .env.test. Then edit .env.test if necessary (e.g. add a test database).

In the examples of all commands below in the text <env> is the name of the environment to perform the command, e.g. development, test or production.

Start the server with the command:

npm run start:<env>

Once the dependencies are installed and the backend is running, you can run the tests. To do this, use the command: Running all tests:

npm run test:api:<env>

Run all tests and create a report on the results:

npm run test:api:report:<env>

Run tests for a specific component:

ENV=<env> npx playwright test tests/api/<file_name>.test.js --debug

👤 Fake Data

In the examples of all commands below in the text <env> is the name of the environment to perform the command, e.g. development, test or production.

To fill the database with demo data of users, calendars and events, run the command:

npm run test:seed:<env>

Here is the fake data for presentations.

User data for testing:

• full name:

  Test User
  

• email:

  test.user@calendula.com
  

All users have a password:

Password123!$

---

© Inessa Repeshko. 2025