Data Models

This document describes the data models and database schema used in the Fish Tracker Backend API.

Overview

The API uses MongoDB architecture. Each user has separate collections for fish and crab data per gamemode. Core user and admin data is stored in shared collections. Everything is in one MongoDB database instance.

User (collection: users)

Fields:

• id (String, required, unique) - external user identifier
• name (String, required)
• userPassword (String, required)
• fernetKey (String, required) - per-user encryption key, autogenerated
• createdAt (Date, default: Date.now)

Example document:

{
  "id": "some id",
  "name": "user",
  "userPassword": "super secret password",
  "fernetKey": "super secret fernet-key",
  "createdAt": ""
}

Fish (per-user collections: fish_{username}_{gamemode})

Document fields (stored in each fish_* collection):

• _id (ObjectId)
• fish (String) - fish name
• rarity (Number) - numeric tier stored in DB (1,2,3,4,6,7)
• timestamp (Date) - optional creation timestamp if present

Example document:

{
  "_id": "some id",
  "fish": "Salmon",
  "rarity": 3,
  "timestamp": ""
}

Crabs (per-user collections: crab_{username}_{gamemode})

Document fields:

• _id (ObjectId)
• fish (String) - always crab
• timestamp (Date) - optional

Example document:

{
  "_id": "some id",
  "fish": "crab",
  "timestamp": ""
}

Admin (collection: admins)

Fields:

• username (String, required, unique)
• password (String, required) hashed with bcrypt
• role (String, enum: ['admin','superadmin'], required)
• createdAt (Date, default: Date.now)

Example document:

{
  "username": "admin1",
  "password": "encrypted bcrypt pw",
  "role": "admin",
  "createdAt": ""
}

Deprecated DB Models

warning

The following part explains the previous database schema(s) used in the Fish Tracker that was used before the v2.0.0 version!

User Model

Database: core_users_data

Collection: users

Represents a user account in the system.

Fields:

• id (string): Unique user identifier
• name (string): Username (unique)
• created_at (timestamp): Account creation date
• Additional metadata fields as needed

Example Document:

{
  "id": "12345",
  "name": "player123",
  "created_at": "2024-01-15T10:30:00Z"
}

Fish Model

Database: user_data_fish_{gamemode}

Collection: {username} (one collection per user)

Stores fish data for a specific user and gamemode.

Fields:

• _id (ObjectId): MongoDB document ID
• fish (string): Name of the fish
• rarity (number): Rarity level (1-7)

For rarity levels check the Rarity System section.

Example Document:

{
  "_id": "some id",
  "fish": "Salmon",
  "rarity": 3,
}

Rarity Storage Optimization

Fish rarity tiers are stored as numbers (1-7) in the database to optimize space usage and improve query performance. This numeric representation is used for:

• POST requests: When submitting new fish/crab data to the API
• Database storage: Efficient indexing and storage of rarity information

When retrieving data through GET requests for fish/crab information, the numeric tiers are automatically converted back to their corresponding string rarity names (e.g., "Gold", "Diamond") for better readability in API responses.

Crab Model

Database: user_data_crab_{gamemode}

Collection: {username} (one collection per user)

Stores crab data for a specific user and gamemode. Similar structure to Fish model.

Fields:

• _id (ObjectId): MongoDB document ID
• fish (string): Always crab

Example Document:

{
  "_id": "some id",
  "fish": "crab",
}

Admin Model

Database: core_users_data

Collection: admins

Manages administrative users with role-based access.

Fields:

• username (string): Admin username
• password (string): Bcrypt hashed password
• role (string): Admin role (admin/superadmin)
• created_at (timestamp): Account creation date

Roles:

• admin: Standard administrative privileges
• superadmin: Full system access including user deletion

Example Document:

{
  "username": "admin",
  "password": "$2a$10$...",
  "role": "admin",
  "created_at": "2024-01-01T00:00:00Z"
}

Database Architecture

Multi-Database Design

The system uses separate databases for each gamemode to:

• Isolate data between gamemodes
• Simplify backup and maintenance operations

Database Naming Convention:

• core_users_data: Central user database
• user_data_fish_{gamemode}: Fish data per gamemode
• user_data_crab_{gamemode}: Crab data per gamemode