AttendEx

A comprehensive event attendance tracking platform consisting of a Spring Boot backend, Next.js web dashboard, and an Android capture application.

🛠 Prerequisites

Ensure you have the following installed:

• Container Engine: Docker Desktop (Mac/Windows) or Docker Engine + Docker Compose (Linux).
• Java: JDK 21 (Temurin or OpenJDK).
• Node.js: Version 24+ (via nvm or mise).
• Android: Android Studio (for the Capture app).

🚀 Getting Started

1. Environment Configuration

The project relies on environment variables for database connections and API configurations.

1. Copy the example environment file to .env:

   cp .env.example .env

2. Open .env and ensure the DB_URL is set correctly for JDBC:

   DB_PORT=5432
   DB_NAME=attendex
   DB_USERNAME=attendex
   DB_PASSWORD=attendex
   # Ensure this line exists for Spring Boot:
   DB_URL=jdbc:postgresql://localhost:5432/attendex

2. Infrastructure (PostgreSQL)

We use Docker Compose to run the database.

Start the Database:

docker compose up -d

Stop the Database:

docker compose down

Note: The compose.yaml includes volume mounts for data persistence. If you need to wipe the database completely, run docker compose down -v.

---

3. Backend (Platform)

Located in the /platform directory. Built with Spring Boot and Maven.

Important: You must load the environment variables into your shell before running the app, or Flyway/Database connections will fail.

Running from Terminal:

cd platform

# 1. Export variables from .env (run this once per session)
set -a; source ../.env; set +a

# 2. Run the application
./mvnw spring-boot:run

Running from IntelliJ IDEA:

1. Install the EnvFile plugin.
2. Edit your Run Configuration for PlatformApplication.
3. In the "EnvFile" tab, enable it and add the .env file from the project root.

---

4. Frontend (Web)

Located in the /web directory. Built with Next.js.

cd web

# 1. Install dependencies
npm install

# 2. Setup Environment
# Copy the root env file. 
# IMPORTANT: Ensure NEXT_PUBLIC_API_URL=http://localhost:8080 is present in .env.local
cp ../.env .env.local

# 3. Run the development server
npm run dev

Access the dashboard at: http://localhost:3000

---

5. Mobile App (Capture)

Located in the /capture directory. Built with Kotlin and Jetpack Compose.

1. Open the /capture folder in Android Studio.
2. Sync Gradle project.
3. Network Configuration:
   • The Android Emulator cannot access localhost.
   • Open capture/app/build.gradle.kts.
   • Update API_BASE_URL to your computer's local network IP (e.g., 192.168.1.x:8080) or use 10.0.2.2:8080 if using the standard Android Emulator.
4. Run on an emulator or physical device.

---

🔧 Troubleshooting

"Driver claims to not accept jdbcUrl, ${DB_URL}"

This means the DB_URL variable was not expanded before Java started. Fix: Run set -a; source ../.env; set +a in your terminal before running ./mvnw.

Linux Permission Denied (SELinux)

If you are on Linux (Fedora/RHEL/CentOS) and the database logs permission errors regarding /var/lib/postgresql/data. Fix: Ensure your compose.yaml volume mount ends with :Z (e.g., /var/lib/postgresql/data:Z). This flag is generally ignored by Docker on Mac/Windows but required on SELinux systems.

Port 5432 already in use

Check if an old container is running (orphaned) or if you have a local Postgres service installed. Fix:

docker ps -a
docker stop attendex
docker rm attendex