Aashray Backend

REST API backend for managing Research Centre operations, serving both mobile app and admin website.

Tech Stack

Layer	Technology
Runtime	Node.js 23.x (ES modules)
Framework	Express 4.x
Database	MySQL via Sequelize 6.x ORM (Hosted - AWS Aurora)
Auth	JWT (admin), card-based password auth (client)
Payments	Razorpay
Email	AWS SES via Nodemailer + Handlebars templates
Push Notifications	Expo Server SDK
File Storage	AWS S3
Process Manager	PM2 (API server + cron worker)
CI/CD	GitHub Actions on self-hosted runner
Logging	Winston with structured JSON, correlation IDs, daily file rotation

Documentation Index

Getting Started

• Setup -- Prerequisites, local install, environment variables, running the server
• Project Structure -- Folder layout, request lifecycle, code organization
• Conventions -- Naming, formatting, logging, git workflow, code patterns

Architecture

• Overview -- System architecture, external integrations, logging, high-level design
• Database Schema -- All models, fields, types, relationships, indexes
• Auth Flow -- Client and admin authentication, JWT, role-based authorization
• Error Handling -- Error classes, response format, middleware chain, correlation
• Booking Lifecycle -- Status flows, payment states, credits, cancellation rules, waitlist promotion, cron automation

API Reference

• API Overview -- Base URL, headers, response envelope, pagination
• Endpoints:
  • Auth -- Client login/logout/password + admin login/create/reset
  • Rooms -- Client room/flat booking + admin room/flat management and reports
  • Food -- Client meal booking + admin plate issuance, menus, reports
  • Travel -- Client travel booking + admin management and driver manifest
  • Adhyayan -- Client registration/feedback + admin CRUD, attendance, reports
  • Utsav -- Client event booking + admin packages, check-in, reports
  • Bookings -- Unified guest/mumukshu booking + admin cancellation
  • Payment -- Razorpay order creation and webhook
  • Profile -- User profile, transactions, notifications
  • Gate -- Admin gate entry/exit tracking and history
  • Cards -- Admin user card CRUD
  • Accounts -- Admin financial management and settlement reconciliation
  • WiFi -- Client/admin WiFi code management
  • Admin Controls -- Super admin role and user management
  • Maintenance -- Client/admin maintenance requests
  • Support -- Support ticket creation
  • Location -- Countries, states, cities, centres
  • Updates -- App version checking

Guides

• Adding a New Endpoint -- Step-by-step walkthrough
• Database Migrations -- Creating, running, and rolling back migrations
• Testing -- Current state of test infrastructure
• Deployment -- CI/CD pipeline, PM2, production setup, logging
• Environment Config -- All configuration values and per-environment differences

Architecture Decision Records

• ADR-001: India-Only Payment Cancellation -- Why cron only auto-cancels unpaid bookings for India-based users
• ADR-002: Credit System Design -- JSON-based credit storage, type segregation, flat/room interchangeability, no-refund rules for travel/utsav
• ADR-003: Room Allocation and Gender Encoding -- Floor+gender concatenation (SCM/SCF), WL rooms, day visits, utsav boundary waiting
• ADR-004: Samvatsari Package Exclusivity -- Hardcoded mutual exclusivity between package IDs 21, 18, and 20
• ADR-005: Gate Entry Async Side Effects -- Booking status updates run after HTTP response via res.on('finish')
• ADR-006: Food Booking Requires Accommodation -- Meal booking tied to room/flat/adhyayan enrollment, utsav date exclusion
• ADR-007: Late Checkout Fee as Orphan Transaction -- Standalone transactions with no booking row, fee schedule, disabled overstay handling
• ADR-008: DataChef Migration Compatibility -- Runtime detection of legacy records via booking ID length heuristic
• ADR-009: Adhyayan Attendance and Feedback Windows -- Pre-created attendance (default attended), Research Centre only, feedback from start_date not end_date
• ADR-010: Travel Directional Conflict and Waitlist -- Same-direction duplicate prevention, FIFO waitlist promotion to awaiting confirmation, utsav waitlist not auto-promoted
• ADR-011: WiFi Username Generation -- Name prefix stripping, card+device suffix, collision counter, dry-run pattern
• ADR-012: UtsavBooking hasOne Relationship -- Likely bug: should be hasMany, silently returns only one booking via eager loading

System Context

This backend is one part of a three-component system:

+-------------------+     +-------------------+     +-------------------+
|  React Native     |     |  Admin Website    |     |  Cron Worker      |
|  Mobile App       |     |  (Vanilla JS)     |     |  (node cron.js)   |
|                   |     |                   |     |                   |
|  Client routes    |     |  Admin routes     |     |  Scheduled jobs   |
|  /api/v1/client/* |     |  /api/v1/admin/*  |     |  Every 30 min     |
+--------+----------+     +--------+----------+     +--------+----------+
         |                         |                         |
         +-------------------------+-------------------------+
                                   |
                          +--------v----------+
                          |  Aashray Backend  |
                          |  (this repo)      |
                          +--------+----------+
                                   |
              +--------------------+--------------------+
              |                    |                    |
     +--------v-------+  +--------v-------+  +--------v-------+
     |  MySQL DB      |  |  AWS (S3/SES)  |  |  Razorpay      |
     +----------------+  +----------------+  +----------------+

The mobile app uses client routes with card-based authentication. The admin website uses admin routes with JWT-based authentication. Both hit the same Express server. The cron worker runs as a separate PM2 process handling automated booking cancellations and waitlist promotions.