Todo List Application

A modern, full-stack todo list web application with a Node.js/Express backend and MariaDB database hosted on OSaaS (Open Source Cloud).

Features

• Modern UI: Clean, responsive interface with smooth animations
• Full CRUD Operations: Create, read, update, and delete todos
• Smart Filtering: View all todos, only active, or only completed
• RESTful API: Well-structured backend with proper error handling
• Production Ready: Environment-based configuration and proper database connection pooling
• MariaDB Database: Persistent storage with optimized schema

Tech Stack

Frontend

• HTML5
• CSS3 (Modern design with CSS Grid/Flexbox)
• Vanilla JavaScript (ES6+)

Backend

• Node.js
• Express.js
• MariaDB (via mariadb npm package)
• CORS enabled

Database

• MariaDB hosted on OSaaS
• Optimized table structure with indexes

Prerequisites

• Node.js 16+ and npm
• MariaDB database on OSaaS (see setup instructions below)
• Git (optional)

OSaaS MariaDB Setup

Option 1: Using the OSaaS Web UI

1. Go to the OSaaS web interface
2. Create a service secret for your database root password:
   • Navigate to secrets section
   • Create a new secret with key rootpassword and your desired password
3. Create a new MariaDB instance:
   • Click "Create dbserver"
   • Select the MariaDB service
   • Configure your instance settings
   • Wait for the instance to reach "Running" status
4. Note the IP address and port from the service instance card

Option 2: Using the OSaaS JavaScript SDK

import { Context } from '@osaas/client-core';
import { createLinuxserverDockerMariadbInstance } from '@osaas/client-services';

const ctx = new Context();
const config = {
  name: 'todo-db',
  // additional configuration
};

const instance = await createLinuxserverDockerMariadbInstance(ctx, config);
console.log('Database URL:', instance.url);

For more details, see the OSaaS MariaDB Documentation.

Installation

1. Clone or download this repository:

cd todo-app

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env

4. Edit .env with your MariaDB credentials:

DB_HOST=your-mariadb-host
DB_PORT=your-mariadb-port
DB_USER=root
DB_PASSWORD=your-root-password
DB_NAME=todo_db
PORT=3000
NODE_ENV=development

5. Initialize the database:

npm run init-db

This will:

• Create the todo_db database
• Create the todos table with proper schema
• Insert sample todos

Running the Application

Development Mode (with auto-restart)

npm run dev

Production Mode

npm start

The application will be available at:

• Frontend: http://localhost:3000
• API: http://localhost:3000/api/todos
• Health Check: http://localhost:3000/api/health

API Documentation

Base URL

http://localhost:3000/api

Endpoints

Get All Todos

GET /todos

Response:

[
  {
    "id": 1,
    "title": "Buy groceries",
    "completed": false,
    "created_at": "2025-12-03T10:30:00.000Z"
  }
]

Get Todo by ID

GET /todos/:id

Response:

{
  "id": 1,
  "title": "Buy groceries",
  "completed": false,
  "created_at": "2025-12-03T10:30:00.000Z"
}

Create Todo

POST /todos
Content-Type: application/json

{
  "title": "New todo item"
}

Response:

{
  "id": 2,
  "title": "New todo item",
  "completed": false,
  "created_at": "2025-12-03T10:35:00.000Z"
}

Update Todo

PUT /todos/:id
Content-Type: application/json

{
  "title": "Updated title",
  "completed": true
}

Response:

{
  "id": 1,
  "title": "Updated title",
  "completed": true,
  "created_at": "2025-12-03T10:30:00.000Z"
}

Delete Todo

DELETE /todos/:id

Response:

204 No Content

Health Check

GET /health

Response:

{
  "status": "ok",
  "database": "connected",
  "timestamp": "2025-12-03T10:40:00.000Z"
}

Database Schema

CREATE TABLE todos (
  id INT AUTO_INCREMENT PRIMARY KEY,
  title VARCHAR(255) NOT NULL,
  completed BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_completed (completed),
  INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Project Structure

todo-app/
├── backend/
│   ├── config/
│   │   └── database.js       # Database connection and pool
│   ├── routes/
│   │   └── todos.js          # Todo API routes
│   ├── server.js             # Express server setup
│   └── init-db.js            # Database initialization script
├── frontend/
│   ├── index.html            # Main HTML file
│   ├── styles.css            # Styles and responsive design
│   └── app.js                # Frontend JavaScript logic
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore rules
├── package.json              # Dependencies and scripts
└── README.md                 # This file

Development Notes

Error Handling

• All API endpoints include comprehensive error handling
• Frontend displays user-friendly error messages
• Database connection failures are gracefully handled

Security Features

• Input validation on both frontend and backend
• SQL injection prevention via parameterized queries
• XSS prevention with HTML escaping
• CORS configuration for development

Performance Optimizations

• Database connection pooling
• Indexed database queries
• Efficient frontend rendering
• Minimal dependencies

Deployment to OSaaS

To deploy this application to OSaaS:

1. Ensure your MariaDB instance is provisioned on OSaaS
2. Update your .env file with the production database credentials
3. Set NODE_ENV=production in your environment
4. Follow OSaaS deployment documentation for Node.js applications
5. Run npm run init-db once to initialize the database
6. Start the server with npm start

Troubleshooting

Database Connection Issues

# Test database connection
npm run init-db

If you see connection errors:

• Verify your database credentials in .env
• Ensure MariaDB instance is running on OSaaS
• Check firewall/network settings
• Verify the host and port are correct

Port Already in Use

# Change PORT in .env file or:
PORT=3001 npm start

Dependencies Issues

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Resources

• OSaaS Documentation
• OSaaS MariaDB Service
• OSaaS JavaScript SDK
• Express.js Documentation
• MariaDB Node.js Connector

License

ISC

Support

For issues related to:

• Application: Check the troubleshooting section above
• OSaaS Platform: Visit OSaaS Documentation
• Database: Review MariaDB logs and connection settings