Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• server.js
• seed.js
• public/index.html
• APP/models/model.model.js
• APP/config/db.config.js
• APP/models/index.js
• model_database.py

The LostData project is a full-stack web application designed to manage a database of models. It features a Node.js backend using the Express framework, a MongoDB database for data persistence, and a dynamic, single-page frontend built with vanilla JavaScript. The system provides role-based access control, allowing regular users to view data while administrators can perform full CRUD (Create, Read, Update, Delete) operations, as well as import and export data in JSON and CSV formats.

This guide provides a technical overview of the project's architecture, setup, and core components, including the backend server, database schema, API endpoints, and frontend interface. It is intended for developers looking to understand, run, and contribute to the project.

Project Architecture

The application is structured as a monolithic service with a clear separation between the backend, frontend, and database configuration.

The diagram below illustrates the high-level architecture of the LostData application.

Key Components

Component	Description	Source Files
Express Server	The core of the backend, handling API requests, session management, and serving static files.	server.js
MongoDB Database	The data store for the application, managed via Mongoose.	APP/config/db.config.js, APP/models/model.model.js
Frontend UI	A single-page interface for interacting with the model database.	public/index.html
Data Seeder	A script to populate the database with initial model data.	seed.js
Python CLI Tool	An alternative, separate command-line interface for managing model data in a JSON file.	model_database.py

Sources: server.js, APP/config/db.config.js, public/index.html, seed.js, model_database.py

Backend

The backend is a Node.js application built with Express.js.

Sources: server.js, package.json

Dependencies

The project relies on several key npm packages for its functionality:

Package	Usage
express	Web server framework.
mongoose	MongoDB object data modeling (ODM).
cors	Enables Cross-Origin Resource Sharing.
express-session	Manages user sessions for authentication.
dotenv	Loads environment variables from a .env file.
multer	Middleware for handling multipart/form-data, used for file uploads.
csv-parser	Parses CSV data for import functionality.
json2csv	Converts JSON data to CSV for export functionality.

Sources: package.json:2-10

Server Initialization

The main server file, server.js, performs the following actions on startup:

1. Loads environment variables using dotenv.
2. Initializes an Express app.
3. Configures middleware: cors, express.json, express.urlencoded, and express-session.
4. Serves static files from the public directory.
5. Connects to the MongoDB database using the connection string from process.env.MONGODB_URI.
6. Defines all API routes for authentication, CRUD, and data management.
7. Starts the server, listening on process.env.PORT or defaulting to port 3000.

Sources: server.js:1-25, 140-141

Database

The application uses MongoDB as its database, with Mongoose as the Object Data Modeling (ODM) library to define schemas and interact with the data.

Database Configuration

The database connection URL is defined in APP/config/db.config.js. It uses the MONGODB_URI environment variable or defaults to a local MongoDB instance.

// APP/config/db.config.js
module.exports = {
  url: process.env.MONGODB_URI || "mongodb://127.0.0.1:27017/model_db"
};

Sources: APP/config/db.config.js:1-3

The Mongoose connection is established in server.js.
Sources: server.js:24-25

Data Schema

The Model schema defines the structure for each model record in the database.

This diagram shows the entity relationship for the Model schema.

The schema includes a pre('save') hook that automatically records changes to a history array whenever a document is updated. This provides a simple audit trail.

// APP/models/model.model.js:19-27
schema.pre('save', function(next) {
  if (this.isModified() && !this.isNew) {
    this.history.push({
      timestamp: new Date(),
      action: 'update',
      changes: this.modifiedPaths()
    });
  }
  next();
});

Sources: APP/models/model.model.js:19-27

Data Seeding

The seed.js script is used to populate the database with an initial set of model data. It connects to the database and uses Model.insertMany() to bulk-insert the data defined in the modelsData array.

Sources: seed.js:1-120

API Endpoints

The server.js file defines a RESTful API for managing the model data. Access to modification endpoints is restricted to admin users.

Authentication

Authentication is session-based. A user logs in by sending their email to POST /api/login. The server creates a session and assigns a role (admin or chatter) based on the email address domain (@admin.com).

This sequence diagram shows the login flow.

An isAdmin middleware function protects administrative routes by checking if req.session.user.role is 'admin'.

Sources: server.js:36-39

API Route Summary

Method	Path	Description	Admin Only
POST	/api/login	Logs in a user and creates a session.	No
POST	/api/logout	Destroys the user session.	No
GET	/api/models	Retrieves a sorted list of all models.	No
GET	/api/models/:id	Retrieves a single model by its ID.	No
POST	/api/models	Creates a new model.	Yes
PUT	/api/models/:id	Updates an existing model by its ID.	Yes
DELETE	/api/models/:id	Deletes a model by its ID.	Yes
GET	/api/export/json	Exports all models as a JSON file.	Yes
GET	/api/export/csv	Exports all models as a CSV file.	Yes
POST	/api/import/csv	Imports models from an uploaded CSV file.	Yes

Sources: server.js:27-138

Frontend

The user interface is a single HTML file, public/index.html, which uses vanilla JavaScript to interact with the backend API and dynamically render content.

UI Features

• Login: An email input to log in and establish a user role.
• Model List: Displays all models in a grid format.
• Search: A real-time search bar to filter models by name or profile content.
• Modal View: Clicking a model opens a modal with detailed information.
• Admin Controls: For admin users, buttons to add, edit, and delete models are visible.
• Data Management: Admin users have access to buttons for exporting data to JSON/CSV and importing from CSV.

Sources: public/index.html:10-40

Client-Side Logic Flow

The following diagram illustrates the sequence of events when a user loads the page and interacts with the model list.

Alternative Python Implementation

The repository also contains model_database.py, a Python-based command-line tool for managing model data. This script operates independently of the Node.js application and persists data to a local models.json file. It provides an interactive mode for adding, viewing, listing, and removing models. This appears to be an alternative or perhaps an earlier version of the data management system.

Sources: model_database.py