Skip to content
BranchesTags

Repository files navigation

Open Era Hackathon Backend API

A secure, scalable backend API for the Open Era Hackathon submission system built with Node.js, TypeScript, Express, Prisma, and PostgreSQL.

Features

  • Secure Submission System: Accept and manage hackathon submissions with duplicate prevention
  • Admin Dashboard API: Complete CRUD operations for submission management
  • JWT Authentication: Secure admin authentication with refresh token rotation
  • Comprehensive Audit Logging: Track all system activities and changes
  • Rate Limiting: Protect against spam and abuse
  • IP Tracking: Monitor submission sources and prevent fraud
  • API Documentation: Interactive Swagger/OpenAPI documentation
  • Docker Support: Containerized deployment ready
  • Health Monitoring: Health check endpoints for system monitoring

Tech Stack

  • Runtime: Node.js 18+ with TypeScript
  • Framework: Express.js
  • Database: PostgreSQL with Prisma ORM
  • Authentication: JWT with refresh tokens
  • Validation: express-validator with custom schemas
  • Security: helmet, cors, rate limiting, bcrypt
  • Documentation: Swagger/OpenAPI 3.0
  • Containerization: Docker & Docker Compose
  • Logging: Custom Winston-based logger

Prerequisites

  • Node.js 18 or higher
  • PostgreSQL 12 or higher
  • Docker & Docker Compose (optional but recommended)
  • npm or yarn package manager

Quick Start

Option 1: Docker (Recommended)

  1. Clone the repository

    git clone <repository-url>
cd openera-backend

  2. Start with Docker Compose

    # For development
npm run docker:dev

# For production
npm run docker:prod

  3. Setup database and seed admin

    npm run db:migrate
npm run db:seed

  4. Access the API

Option 2: Local Development

  1. Install dependencies

    npm install

  2. Setup environment variables

    cp .env.example .env
# Edit .env with your configuration

  3. Setup database

    # Start PostgreSQL (if not using Docker)
npm run db:migrate
npm run db:seed

  4. Start development server

    npm run dev:watch

Configuration

Environment Variables

Create a .env file based on .env.example:

# Server Configuration
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/openera_hackathon

# JWT Configuration
JWT_SECRET=your_super_secure_jwt_secret_key_here
JWT_REFRESH_SECRET=your_super_secure_refresh_secret_key_here
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# Admin Configuration
ADMIN_EMAIL=admin@openera.com
ADMIN_PASSWORD=SecureAdminPassword123!
ADMIN_NAME=System Administrator

# Security
CORS_ORIGIN=http://localhost:3000,https://openera.openlearn.org.in
BCRYPT_ROUNDS=12

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
SUBMISSION_RATE_LIMIT_MAX=5
SUBMISSION_RATE_LIMIT_WINDOW_MS=3600000

# Logging
LOG_LEVEL=info
LOG_FILE=logs/openera.log

API Documentation

Interactive Documentation

Visit /docs endpoint for interactive Swagger UI documentation.

API Endpoints

Submissions

  • POST /api/v1/submissions - Create new submission
  • GET /api/v1/submissions - List submissions (Admin)
  • GET /api/v1/submissions/:id - Get submission details (Admin)
  • PUT /api/v1/submissions/:id - Update submission (Admin)
  • DELETE /api/v1/submissions/:id - Delete submission (Admin)
  • PATCH /api/v1/submissions/:id/status - Update submission status (Admin)

Authentication

  • POST /api/v1/auth/login - Admin login
  • POST /api/v1/auth/refresh - Refresh access token
  • POST /api/v1/auth/logout - Admin logout
  • PUT /api/v1/auth/change-password - Change admin password
  • GET /api/v1/auth/profile - Get admin profile

Audit Logs

  • GET /api/v1/audit - List audit logs (Admin)
  • GET /api/v1/audit/submission/:id - Get submission audit logs (Admin)
  • GET /api/v1/audit/admin/:id - Get admin activity logs (Admin)
  • GET /api/v1/audit/stats - Get audit statistics (Admin)

Health & Monitoring

  • GET /ping - Basic health check
  • GET /api/v1/health - System health check
  • GET /api/v1/health/detailed - Detailed system information
  • GET /api/v1/health/db - Database connectivity check

Security Features

Authentication & Authorization

  • JWT-based authentication for admin users
  • Refresh token rotation for enhanced security
  • Role-based access control
  • Password hashing with bcrypt (12 rounds)

Rate Limiting

  • Global rate limiting: 100 requests per 15 minutes
  • Submission rate limiting: 5 submissions per hour per IP
  • Admin endpoint rate limiting: Enhanced protection for admin operations
  • Dynamic rate limiting based on endpoint sensitivity

Data Protection

  • Input validation and sanitization
  • SQL injection prevention with Prisma
  • XSS protection with helmet
  • CORS configuration for cross-origin requests
  • IP address tracking and logging

Audit Trail

  • Comprehensive logging of all admin actions
  • Submission tracking and history
  • IP address and user agent logging
  • Automatic audit log creation for sensitive operations

Database Schema

Core Models

  • Admin: Administrator users with authentication
  • Submission: Hackathon project submissions
  • AuditLog: System activity tracking
  • RefreshToken: JWT refresh token management

Key Features

  • Email uniqueness for submissions (prevents duplicates)
  • Automatic timestamp tracking
  • Soft delete support for submissions
  • Comprehensive audit trail relationships

Monitoring & Logging

Health Checks

  • /ping - Basic server responsiveness
  • /api/v1/health - Comprehensive system health
  • /api/v1/health/db - Database connectivity
  • Docker health checks included

Logging

  • Structured logging with Winston
  • Request/response logging
  • Error tracking and reporting
  • Audit trail logging
  • Configurable log levels

Deployment

Docker Deployment

# Build and deploy
docker-compose up -d

# Check logs
docker-compose logs -f

# Scale services
docker-compose up -d --scale app=3

Manual Deployment

# Build application
npm run build

# Start production server
npm start

Environment-Specific Configurations

Development

  • Enhanced logging and debugging
  • CORS enabled for localhost
  • Database migrations run automatically

Production

  • Optimized for performance
  • Security headers enforced
  • Rate limiting strictly enforced
  • Health checks enabled

🧪 Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Available Scripts

  • npm run dev - Start development server
  • npm run dev:watch - Start development server with auto-reload
  • npm run build - Build production application
  • npm start - Start production server
  • npm run db:migrate - Run database migrations
  • npm run db:seed - Seed database with admin user
  • npm run db:studio - Open Prisma Studio
  • npm run docker:dev - Start development Docker environment
  • npm run docker:prod - Start production Docker environment
  • npm run setup:dev - Complete development setup

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Links

About

backend repository for open era hackathon assignment submissions

openera-backend.onrender.com

Resources

Readme

Code of conduct

Code of conduct

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages