Turtle Tracker

Turtle Tracker is a secure full-stack web application that allows scientists and research teams to document, manage, and monitor turtle populations in the field.

The system is built using a modern Java backend and a React frontend, with security, data integrity, and real-world architecture as core design principles.

By default, the application is secured, ensuring that only authorized users can access or modify conservation data.

---

Project Overview

Turtle Tracker enables research teams to:

• Record and manage turtle specimens
• Organize turtles by species (breed)
• Track habitats and geographic locations
• Manage users with different levels of responsibility
• Securely access data through authenticated sessions

This project simulates a real-world wildlife tracking platform with enterprise-style backend architecture and a modern frontend.

---

Tech Stack

Backend

• Java 25
• Spring Boot 4.0.1
• Gradle
• Spring Security
• Spring Data JPA / Hibernate
• JWT (JSON Web Tokens)

Database

• PostgreSQL

Database Migration

• Flyway

Frontend

• React
• JavaScript (ES6+)
• HTML5
• CSS3
• Tailwind CSS
• Vite

---

Architecture

• The React frontend handles UI and user interaction
• The Spring Boot backend handles business logic, validation, and security
• PostgreSQL stores all persistent data
• Flyway manages database schema versioning

---

Security Features

Security is a foundational part of Turtle Tracker. The system implements both authentication and authorization using modern best practices.

---

Authentication

Users must sign in using their username and password.

• Login is handled through a secure authentication endpoint
• On successful login, the server issues a JWT token
• The token must be included in future requests to access protected resources

---

Authorization (Role-Based Access Control)

The system enforces strict role-based access control to ensure users can only perform actions permitted by their role.

Auditing

Turtle Tracker includes an extensive auditing system to ensure full traceability of data changes across the platform.

For every important entity (such as users, specimens, locations, and breeds), the system records:

• Who made the change
• When the change was made

This is implemented using backend auditing mechanisms that automatically populate audit fields during create and update operations.

Typical audit fields include:

• created_at – Timestamp of when the record was first created
• created_by – User ID of the creator
• updated_at – Timestamp of the most recent update
• updated_by – User ID of the last user who modified the record

This ensures:

• Accountability for all data modifications
• Clear history of changes for research and administrative review
• Production-style data governance similar to real enterprise systems

User Roles

Role	Permissions
ROLE_USER	Can view available data
ROLE_ASSISTANT	Can view data and add new specimens
ROLE_RESEARCHER	Can do everything an assistant can do and manage their assistants (similar to a team lead or department chair)
ROLE_ADMIN	Highest level of privilege; can manage all users and system data

If a user account is deactivated, the user immediately loses the ability to log in and access the system.

---

JWT Token Design

Turtle Tracker uses JWT (JSON Web Tokens) for stateless session management.

Each token contains:

• The user ID
• The user role
• A token version number

Token Versioning

The token version ensures that only the most recent token is valid.

• When a user’s credentials or status change (e.g., deactivation or role update), older tokens become invalid
• This prevents continued access using outdated or compromised tokens

---

Database Migration with Flyway

Flyway is used to manage and version database schema changes.

Migration Design

The database is treated as the source of truth.

Each migration file follows a structured naming convention:

---

API endpoints

Specimen (Turtle) Endpoints

Method	Endpoint	Description
GET	/specimens	Get all turtles
GET	/specimens/{id}	Get turtle by ID
POST	/specimens	Create new turtle
PUT	/specimens/{id}	Update turtle
DELETE	/specimens/{id}	Delete turtle

---

User Endpoints

Method	Endpoint	Description
GET	/users	Get all users
GET	/users/{id}	Get user by ID
POST	/users	Register new user
DELETE	/users/{id}	Delete user

Partial User Updates

Method	Endpoint	Description
PATCH	/users/{id}/username	Update username
PATCH	/users/{id}/email	Update email
PATCH	/users/{id}/phone-number	Update phone number
PATCH	/users/{id}/role	Update role
PATCH	/users/{id}/deactivate	Deactivate user

User Queries

Method	Endpoint	Description
GET	/users/search	Search users
GET	/users/privileged	Get privileged users

---

Location Endpoints

Method	Endpoint	Description
GET	/locations	Get all locations
GET	/locations/{id}	Get location by ID
POST	/locations	Create location
PATCH	/locations/{id}	Update location
DELETE	/locations/{id}	Delete location

---

Breed Endpoints

Method	Endpoint	Description
GET	/breeds	Get all breeds
GET	/breeds/{id}	Get breed by ID
POST	/breeds	Create breed
PATCH	/breeds/{id}	Update breed
DELETE	/breeds/{id}	Delete breed

---

Authentication

Method	Endpoint	Description
POST	/auths/login	Authenticate user and receive JWT

---

API Testing & Documentation

The backend API was thoroughly tested and validated using OpenAPI and Scalar.

OpenAPI

• Automatically generated API documentation
• Provides endpoint definitions and request/response schemas
• Acts as a contract between frontend and backend

Scalar API Client

Scalar was used for interactive API testing, including:

• Authentication and JWT flows
• Role-based authorization checks
• CRUD operations for all major resources
• Validation and error handling

This ensured the backend was stable, secure, and frontend-ready.

---

Local Setup

1. Clone Repository

git clone https://github.com/nsubba24/turtle_tracker.git
cd turtle_tracker

2. Database setup

CREATE DATABASE turtle_tracker_db;

3. Backend Setup

cd backend_restapi
cd src/main/resources/

4. Create dev profile

touch application-dev.properties

5. Add this to the file

DB_URL=jdbc:postgresql://localhost:5432/turtle_tracker_db

DB_USERNAME=YOUR_DB_USERNAME

DB_PASSWORD=YOUR_DB_PASSWORD

JWT_SECRET=YOUR_SECRET_KEY

JWT_EXPIRATION_MS=YOUR_EXPIRATION_TIME

JWT_ISSUER=YOUR_ISSUER_NAME

5. Run the app

For backed: ./gradlew bootRun

For Frontend: npm run dev

Some screenshots