The goal of this project is to develop an Android application that allows users to record their daily activities. The app will feature a main page for real-time activity tracking, logging the various activities performed throughout the day. On the same page, the user will also be able to view activity logs from the previous two days. The design supports both real-time and retrospective logging, enabling users to choose the frequency of notifications based on their daily routines. This flexibility makes the app suitable for both personal use and for researchers or organizations conducting time-use studies.

---

🚀 Features

• Secure user registration and login
• Password hashing
• MySQL database integration
• Client-server communication
• Basic frontend form validation
• Protection against common vulnerabilities (e.g., SQL injection, password theft)

---

🛠️ Tech Stack

Layer	Technology
Backend	MySQL + Struts 2 + Apache Tomcat (v9.0.71) + Nginx + Ngrok(to expose https endpoint)
Frontend	HTML, SCSS, TypeScript, Vue, Ionic, Capacitor(Andorid)

---

🖥️ Recommended Development Environment

To ensure smooth setup and compatibility, the project is intended to be run as follows:

The recommended development setup is:

• Windows as the host OS (running the frontend)
• A Ubuntu Linux virtual machine (e.g., via VMware) as the backend environment

⚠️ The backend has not been tested on WSL2 (Windows Subsystem for Linux). Its compatibility is currently unknown, so it is not recommended to use WSL2 for backend development.

---

Clone the repository into a shared folder (Linux VM <-> Windows)

To ensure seamless collaboration between the frontend (Windows) and backend (Linux VM), it's recommended to clone the repository into a shared folder that both systems can access (e.g., VMWare shared folder or a mounted network drive).

This allows the Windows-hosted frontend and the Linux-hosted backend to work with the same source code base.

# From inside your Linux virtual machine:
cd /path/to/shared/folder
git clone https://github.com/bonoboprog/Chronogram.git

---

🔐 Environment Variables (.env)

⚠️ Make sure all .env files are saved with LF (Unix-style) line endings — especially after each edit.
On Windows, you can switch from CRLF to LF in the bottom-right corner of editors like VS Code.
This prevents parsing issues in Docker, Node, and other tools.

The project uses two environment configuration files that look like these:

1. Root .env (Backend Configuration)

Located in the project root folder:

# Database
MYSQL_ROOT_PASSWORD=your_root_password
MYSQL_DATABASE=chronogram
MYSQL_USER=chronouser
MYSQL_PASSWORD=your_db_password
# API Keys
LLM_API_KEY=your_openrouter_api_key
# Email
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USER=your_email@gmail.com
MAIL_PASSWORD=your_app_password
# Security
JWT_SECRET_KEY=your_jwt_secret_key
APP_CANONICAL_URL=http://localhost:8100

2. Front .env (Frontend Configuration)

Located in /frontend folder

VITE_API_BASE_URL=https://your-ngrok-subdomain.ngrok-free.app/chronogram

🔁 This value must match the public URL generated by ngrok.
👉 See Install ngrok on Linux and start a tunnel for details on how to obtain it.

---

📁 Secrets Directory and Firebase Service Account

This project uses Firebase Admin SDK for authentication. A service account key file is required and should be placed in the following location:

/secrets/firebase-service-account.json

🔒 Example (redacted for security):

  "type": "service_account",
  "project_id": "chronogram-xxxxxx",
  "private_key_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "private_key": "-----BEGIN PRIVATE KEY-----\\n...REDACTED...\\n-----END PRIVATE KEY-----\\n",
  "client_email": "firebase-adminsdk-xxxxx@chronogram-xxxxxx.iam.gserviceaccount.com",
  "client_id": "xxxxxxxxxxxxxxxxxxxxx",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-xxxxx%40chronogram-xxxxxx.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"

⚠️ This file is required for Firebase Admin SDK functionality on the backend. You can generate your own service account key from your Firebase Console under: Project Settings → Service accounts → Generate new private key.

---

⚙️ Setting Up a Development Environment

0. Backend Environment Setup (on Ubuntu)

These are required globally on your Ubuntu system before launching the app in the frontend on Windows.

☕ Java 11+

sudo apt update
sudo apt install openjdk-11-jdk

# Verify Java version
java -version

---

📦 Maven

sudo apt install maven

# Verify Maven version
mvn -v

---

🐳 Docker (using Docker's official apt repository)

🔁 Preliminaries – Remove conflicting packages Run the following command to uninstall all conflicting packages with Docker Engine:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

apt-get might report that you have none of these packages installed.

🧷 Add Docker's official GPG key and repository

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

📥 Install the latest version, run:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

✅ Verify that the installation is successful by running the hello-world image:

sudo docker run hello-world

This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

🎉 You have now successfully installed and started Docker Engine.

1. Install ngrok on Linux and start a tunnel

Install ngrok via Apt with the following command:

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
| sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
&& echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
| sudo tee /etc/apt/sources.list.d/ngrok.list \
&& sudo apt update \
&& sudo apt install ngrok

Add your authtoken (If you don’t have an authtoken then Sign up for a free account).

ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>

Start an endpoint:

ngrok http 80

🔗 Copy the URL generated by ngrok (e.g., https://abc123.ngrok-free.app) and paste it into the VITE_API_BASE_URL variable inside the frontend .env file.

2. Start backend environment on Linux

First, move into the cloned Chronogram repository folder, then navigate to the backend scripts directory and run the setup script:

cd ~/path/to/Chronogram/scripts/backend_scripts
./setup_fresh_backend.sh

This script will:

• Stop and remove old containers
• Build the backend (build.sh)
• Start MySQL and Tomcat and Nginx

3. Refresh backend after making code changes

./refresh_tomcat_server.sh

4. Set up the LLM with your API key 🔑

1. Go to https://openrouter.ai

2. Click Sign In in the top-right corner and log in (you can use GitHub, Google, etc.)

3. Go to the API Keys Dashboard

4. Click "Create new key"

5. Copy your newly generated key

6. Paste it into your .env file as follows:

   LLM_API_KEY=your_openrouter_key_here

5. Frontend Environment Setup (on Windows)

This section sets up the frontend development environment on Windows, including Node.js via fnm (Fast Node Manager) and the Ionic CLI.

⚠️ The frontend must be developed on Windows, and Node.js should be installed using fnm, as recommended by the official Node.js documentation for Windows.

# --- Install fnm (Fast Node Manager) ---
# Open PowerShell and run the following

# Download and install fnm:
winget install Schniz.fnm

# Download and install Node.js:
fnm install 22

# Verify the Node.js version:
node -v # Should print "v22.14.0".

# Verify npm version:
npm -v # Should print "10.9.2".

# --- Install Ionic CLI globally ---
npm install -g @ionic/cli

# Verify Ionic version
ionic -v

6. Launch the app frontend in Windows

Open a terminal window — preferably the integrated terminal of your favorite IDE — and navigate to the frontend/ folder located in the project root. Then run:

ionic build
ionic serve

7. Connect to MySQL container from Windows (e.g., using MySQL Workbench)

If you want to inspect or manage the backend MySQL database from Windows, you can connect to the running MySQL container using tools like MySQL Workbench.

The MySQL container exposes the default MySQL port 3306 to the host, making it accessible from Windows as long as the Docker host is reachable (e.g., if running on a local Linux VM with bridged or host networking).

✅ Steps:

1. Open MySQL Workbench on Windows.
2. Create a new connection with the following settings:
   • Hostname: IP address or hostname of the Linux VM (e.g., 192.168.x.x)
   • Port: 3306
   • Username: use the MYSQL_USER defined in the backend .env file
   • Password: use the corresponding MYSQL_PASSWORD (check "Store in Vault…" if desired)
3. Test the connection and save.

💡 You can find the database name in the .env file under MYSQL_DATABASE.

⚠️ Make sure the container is up and that the port 3306 is properly published in docker-compose.yml, e.g.:

ports:
  - "3306:3306"

🔐 Ensure no firewall or network rule is blocking the connection between Windows and the Linux host.

---

🗃️ Explore the Database

1. Access via terminal:

   docker exec -it chronogram-mysql mysql -u chronouser -pchronopass chronogram

2. Verify the tables:

   SHOW TABLES;
   DESCRIBE nome_tabella;

---

📦 Database Schema Management

1. After making EER/Workbench changes → forward engineer into MySQL container

2. Export the schema

   ./export_schema.sh

3. Version the schema

   git add docker/init/schema.sql
   git commit -m "🔄 DB structure updated"
   git push

⚠️ The setup_fresh_backend.sh script automatically loads schema.sql only on the first startup (empty volume).

To force a reset:

docker compose down -v
./setup_fresh_backend.sh

---

🤝 Contributing

Each contributor can:

git clone ...
./dev_setup.sh

Then contribute to:

• Backend (Java)
• Frontend (/mobile)
• Schema DB (export_schema.sh)

⚠️ Note: The schema.sql file is the single source of truth for the database!

---

👥 Contributors

Name	GitHub
Giuseppe Alfieri	@giusalfieri
Violeta Perez	@violetapd
Paolo Simeone	@bonoboprog