Skip to main content

​
Quickstart Guide

This guide will help you set up and run the Cognit Backend API on your local machine.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v14 or higher recommended)
  • PostgreSQL (v12 or higher)
  • npm (comes with Node.js)
Make sure PostgreSQL is running and you have access to create databases.

​
Installation

1

Clone the repository

Clone the Cognit Backend repository to your local machine:
git clone <repository-url>
cd backend
2

Install dependencies

Install all required packages using npm:
npm install
This will install Express.js, TypeScript, Sequelize, JWT, and all other dependencies.
3

Configure environment variables

Create a .env file in the root directory with the following variables:
.env
# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/cognit_db

# Server Configuration
PORT=3005

# JWT Secret for Authentication
JWT_SECRET=your-secret-key-here-change-in-production

# Email Configuration (for account verification)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=[email protected]
EMAIL_PASS=your-app-password

# CORS Origins (comma-separated)
FRONTEND_URL=http://localhost:5175
Never commit the .env file to version control. Always use strong, unique values for JWT_SECRET in production.
4

Set up the database

Create a PostgreSQL database for the application:
# Connect to PostgreSQL
psql -U postgres

# Create the database
CREATE DATABASE cognit_db;

# Exit psql
\q
The application will automatically create the required tables on first run using Sequelize’s sync method.
5

Start the development server

Run the server in development mode with hot-reloading:
npm run dev
You should see output indicating the server is running:
REST Api on port 3005
Database connection successfull

​
Your First API Call

Once the server is running, you can make your first API request to retrieve all games. 
curl http://localhost:3005/api/games

​
Example Response

[
  {
    "id": 1,
    "title": "Environmental Quiz",
    "explanation": "Test your knowledge about nature",
    "points_reward": "100",
    "categoryId": 1,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
]

​
Production Build

To build and run the application in production:
1

Build TypeScript

Compile TypeScript to JavaScript:
npm run build
2

Start production server

Run the compiled application:
npm start

​
Database Models

The API includes the following main models:

​
User Model

  • username - User’s display name
  • email - Unique email address
  • password - Hashed password (bcrypt)
  • token - 6-digit verification token
  • points - Gamification points
  • confirmed - Email confirmation status

​
Games Model

  • title - Game name
  • explanation - Game description
  • points_reward - Points awarded on completion
  • categoryId - Reference to game category

​
Security Features

Cognit Backend includes several security features out of the box:
  • Helmet.js - Sets secure HTTP headers
  • CORS - Configured for specific origins
  • Rate Limiting - 5 requests per minute on auth endpoints
  • JWT Authentication - Secure token-based auth
  • Password Hashing - Bcrypt with salt rounds
  • Input Validation - Express-validator on all inputs
Rate limiting is set to 5 requests per 60 seconds on authentication endpoints. You can adjust this in src/config/limiter.ts.

​
Next Steps

Now that you have the API running:

Explore Authentication

Learn how to implement user registration and login

API Reference

View all available endpoints and their parameters

Games Management

Discover how to manage games and categories

User System

Understand the user and points system

​
Troubleshooting

​
Database Connection Failed

If you see “Database connection failed” in the console:
  1. Verify PostgreSQL is running: pg_isready
  2. Check your DATABASE_URL in .env
  3. Ensure the database exists
  4. Verify user credentials and permissions

​
Port Already in Use

If port 3005 is already in use, change the PORT variable in your .env file: 
PORT=3006

​
Rate Limit Errors

If you’re hitting rate limits during development, you can temporarily adjust the limiter in src/config/limiter.ts or disable it on specific routes.

Build docs developers (and LLMs) love

Get started for freeTalk to us