FMS — Admission Form System

Table of Contents

• The Challenge
• Architecture & Solution
• Tech Stack
• Key Engineering Decisions
• Frontend Deep-Dive
• Backend Deep-Dive
• Deployment
• Roadmap

The Challenge

The BD Foundation manages admissions for multiple skill development courses across various disciplines including Cutting and Tailoring, Computer Hardware, Mobile Repair, Beauty & Wellness, and more. Prior to this system, the organization relied on manual paper-based application processing, which introduced significant operational bottlenecks and data integrity issues.

The manual process required staff to physically collect application forms, manually enter applicant data into spreadsheets, track application status through disjointed communication channels, and generate admission letters using desktop publishing software. This approach consumed approximately 15-20 minutes per application for data entry alone, with no standardized validation rules leading to frequent data entry errors requiring rework. The lack of a centralized system meant that applicants had no way to independently check their application status, resulting in a flood of telephone inquiries that overwhelmed administrative staff.

Beyond operational inefficiency, the organization needed to maintain detailed records for government reporting and compliance purposes. The absence of a structured database made it difficult to generate meaningful analytics about application trends, course popularity, conversion rates, and demographic breakdowns. Decision-makers lacked the data-driven insights necessary for strategic planning and resource allocation.

The requirement: Build a containerized, production-ready admission management system with a public-facing multi-step application wizard, a comprehensive admin dashboard with real-time analytics, automated email notifications with PDF receipt generation, Google Sheets synchronization for external reporting, and secure role-based access for administrators.

Architecture & Solution

The system follows a microservices architecture orchestrated through Docker Compose, with three distinct frontend applications serving different user personas and a unified Node.js backend API handling all business logic and data operations.

The architecture implements several critical patterns that enable both operational reliability and maintainability. Service isolation through Docker ensures that a failure in one component does not cascade to others, while the centralized MongoDB database provides a single source of truth for all application data. The Traefik reverse proxy handles SSL termination, load balancing, and automatic service discovery, eliminating the need for manual nginx configuration during deployment.

The backend implements a layered architecture with clear separation between routes, controllers, models, and utilities. This modular structure facilitates independent testing and modification of business logic without affecting other system components. All external integrations including email services, Google Sheets synchronization, and file storage operate through abstraction layers that can be swapped or modified without touching core application code.

Tech Stack

Key Engineering Decisions

1. Multi-Step Form Wizard with State Persistence

The public-facing application form implements a four-step wizard pattern that guides applicants through Personal Details, Address Information, Course Selection, and Document Upload. Rather than presenting a single overwhelming form, this approach reduces cognitive load and improves completion rates. State is maintained locally using React useState and persisted to sessionStorage, allowing applicants to navigate between steps without losing progress.

// public-form/src/components/Step1Personal.jsx
const Step1Personal = ({ formData, setFormData, errors }) => {
  const handleChange = (e) => {
    setFormData({ ...formData, [e.target.name]: e.target.value });
  };

  return (
    <div>
      <h3>Step 1: Personal Details</h3>
      <div className="form-group">
        <label>Name *</label>
        <input
          type="text"
          name="fullName"
          value={formData.fullName}
          onChange={handleChange}
          className={errors.fullName ? 'error' : ''}
          placeholder="As per documents"
        />
      </div>
    </div>
  );
};

The validation strategy uses express-validator on the backend as the authoritative validation layer, with frontend providing immediate feedback through controlled component state. This dual-layer approach ensures data integrity even if clients bypass frontend validation.

2. Rate Limiting and Security Hardening

Public endpoints implement tiered rate limiting to prevent abuse while maintaining accessibility for legitimate users. The form submission endpoint accepts a maximum of 5 submissions per hour per IP address, while status checking allows 10 requests per 15-minute window. The admin login endpoint enforces the same 10-per-15-minutes limit to mitigate brute force attempts.

// backend/routes/submissionRoutes.js
const submitLimiter = rateLimit({
  windowMs: 60 * 60 * 1000, // 1 hour
  max: 5,
  message: { success: false, message: 'Too many submissions from this IP, please try again after an hour' },
});

Security middleware includes helmet.js for HTTP header hardening, express-mongo-sanitize to prevent NoSQL injection attacks, CORS configured to allow only the defined frontend origins, and JWT token verification for all protected routes. File uploads are restricted to specific MIME types (PDF, JPEG, PNG) with a 2MB maximum file size to prevent storage abuse and server strain.

3. Automated PDF Generation with QR Codes

Upon application submission, the system generates a PDF receipt containing the applicant's reference ID, submitted details, and a scannable QR code that links directly to the application status tracking page. The QR code is generated using the qrcode library and embedded into the PDF using PDFKit's image handling capabilities.

// backend/utils/pdfGenerator.js
const generateAdmissionLetter = (submission) => {
  return new Promise((resolve, reject) => {
    const doc = new PDFDocument({ margin: 50 });
    let buffers = [];
    doc.on('data', buffers.push.bind(buffers));
    doc.on('end', () => resolve(Buffer.concat(buffers)));

    doc.image(logoPath, 50, 45, { width: 50 });
    doc.fillColor('#1e3c72').fontSize(20)
       .text('BHARGAB FOUNDATION', 110, 57);
    doc.fontSize(12).text(`Dear ${submission.fullName},`, 50, 230);
    doc.text(`Congratulations! Your application for ${submission.course} has been Approved.`);
    doc.end();
  });
};

When administrators approve an application, the system automatically generates and emails an official admission letter PDF as an attachment, eliminating manual document preparation entirely.

4. Google Sheets Synchronization

Every new submission is asynchronously synchronized to a Google Sheets spreadsheet using the Google Sheets API v4. This integration enables real-time data sharing with external stakeholders who prefer spreadsheet-based workflows over the web dashboard. The synchronization operates in a fire-and-forget fashion without blocking the submission response, with errors logged but not surfaced to the user.

// backend/utils/googleSheets.js
const syncSubmissionToSheet = async (submission) => {
  const auth = new google.auth.JWT(clientEmail, null, privateKey, 
    ['https://www.googleapis.com/auth/spreadsheets']);
  const sheets = google.sheets({ version: 'v4', auth });

  await sheets.spreadsheets.values.append({
    spreadsheetId,
    range: 'Sheet1!A2',
    valueInputOption: 'USER_ENTERED',
    resource: { values: [[date, refId, name, email, phone, course, caste, gender, status]] },
  });
};

5. Bulk Operations for Admin Efficiency

The admin dashboard supports bulk status updates, allowing administrators to select multiple applications and update their status simultaneously. This feature dramatically reduces administrative overhead during peak admission periods. Similarly, bulk email functionality enables sending custom communications to selected applicant groups with throttled delivery to prevent email service provider rate limiting.

// backend/controllers/submissionController.js
const updateBulkSubmissionStatus = async (req, res, next) => {
  const { ids, status } = req.body;
  const result = await Submission.updateMany(
    { _id: { $in: ids } },
    { $set: { status } }
  );
  
  const updatedSubmissions = await Submission.find({ _id: { $in: ids.slice(0, 20) } });
  for (const submission of updatedSubmissions) {
    await sendStatusUpdateEmail({ to: submission.email, ... });
    await new Promise(r => setTimeout(r, 500)); // Rate limit
  }
};

Frontend Deep-Dive

Public Application Wizard

The public-facing form serves applicants through a carefully designed multi-step experience optimized for completion on mobile devices. The wizard component maintains step state and validates required fields before allowing progression to subsequent steps.

The step indicator provides visual progress feedback, while the form captures all required information without overwhelming the user. React Framer Motion provides smooth transitions between steps, creating a polished user experience. React Select handles the dynamic course dropdown with search capability for the extensive course catalog.

Admin Dashboard

The administrative interface provides comprehensive controls for managing the entire admission lifecycle. The dashboard displays key metrics including total applications, pending reviews, approved counts, and rejection tallies using Recharts for data visualization.

// admin-dashboard/src/pages/DashboardPage.jsx
const stats = analytics.statusBreakdown;
const total = Object.values(stats).reduce((a, b) => a + b, 0);

<div className="stats-grid">
  <div className="stat-card">
    <Users size={28} />
    <div className="stat-value">{total}</div>
    <div className="stat-label">Total Applications</div>
  </div>
  <div className="stat-card">
    <Clock size={28} />
    <div className="stat-value">{stats.Pending || 0}</div>
    <div className="stat-label">Pending Review</div>
  </div>
</div>

The analytics section includes daily application trend visualization using area charts showing the last 30 days of activity, and course distribution displayed as a donut chart showing the breakdown of applications by selected program. The submissions management page supports filtering by course, caste category, and application status, with full-text search across applicant names, email addresses, and reference IDs. Pagination limits results to 10-50 per page to maintain performance.

Backend Deep-Dive

Data Models

The MongoDB schema defines three primary collections: Submission, Course, and Admin, each with appropriate indexes for query performance.

// backend/models/Submission.js
const submissionSchema = new mongoose.Schema({
  referenceId: { type: String, required: true, unique: true },
  fullName: { type: String, required: true, trim: true, index: true },
  email: { type: String, required: true, lowercase: true, trim: true, index: true },
  mobileNumber: { type: String, required: true },
  course: { type: String, required: true },
  caste: { type: String, required: true, enum: ['ST', 'OBC', 'SC', 'GENERAL', 'OTHER'] },
  status: { type: String, enum: ['Pending', 'Approved', 'Rejected'], default: 'Pending', index: true },
  paymentStatus: { type: String, enum: ['Unpaid', 'Paid', 'Failed'], default: 'Unpaid' },
  photoPath: { type: String, required: true },
  hslcMarksheetPath: { type: String, required: true },
  adhaarCardPath: { type: String, required: true },
  paymentProofPath: { type: String },
}, { timestamps: true });

The reference ID generation uses a custom utility that creates unique identifiers incorporating the submission date and a random component, ensuring both uniqueness and human-readability for applicant communication.

API Endpoints

Authentication and Authorization

Admin authentication uses JWT tokens with a 7-day expiration, issued upon successful login with username and password verification using bcrypt comparison. The authentication middleware validates the Bearer token on every protected route, extracting the admin ID from the token payload and attaching it to the request object for downstream handlers.

// backend/middleware/authMiddleware.js
const protect = async (req, res, next) => {
  let token;
  if (req.headers.authorization?.startsWith('Bearer')) {
    token = req.headers.authorization.split(' ')[1];
  }
  
  if (!token) {
    return res.status(401).json({ success: false, message: 'Not authorized' });
  }
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.admin = decoded;
    next();
  } catch (err) {
    return res.status(401).json({ success: false, message: 'Token failed' });
  }
};

Deployment

Quick Start (Development)

# Clone and configure
cp backend/.env.example backend/.env

# Launch ecosystem
docker compose up -d

# Access services
# Public Form: http://localhost:5173
# Admin Dashboard: http://localhost:5174
# API: http://localhost:5000

Service Topology

Production Deployment

The deploy.sh script automates the production deployment pipeline with the following workflow: local changes are committed to Git, source code is rsynced to the VPS (excluding node_modules and git directories), Docker images are rebuilt with production configurations, and health checks verify service availability. Traefik handles SSL certificate acquisition through Let's Encrypt with automatic renewal.

# Production deployment
./deploy.sh

The deployment script performs pre-flight checks to ensure Docker and Docker Compose are installed, verifies domain DNS resolution, and reports detailed status at each stage. Health checks use curl to validate API responsiveness and return meaningful error messages if services fail to start properly.

Docker Configuration

The docker-compose.yml defines health checks for MongoDB to ensure the database is ready before the backend attempts connection. This prevents the common container startup race condition where dependent services fail because their dependencies haven't completed initialization.

# docker-compose.yml (excerpt)
mongo:
  image: mongo:6.0
  healthcheck:
    test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
    interval: 10s
    timeout: 5s
    retries: 5

backend:
  depends_on:
    mongo:
      condition: service_healthy

Roadmap

• Phase 1 — Core Application Submission (Complete) - Multi-step form with file uploads and validation
• Phase 2 — Admin Dashboard (Complete) - Analytics, submission management, bulk operations
• Phase 3 — Email Automation (Complete) - Status notifications, admission letters, bulk communications
• Phase 4 — Google Sheets Sync (Complete) - Real-time data export for external stakeholders
• Phase 5 — Payment Integration (In Progress) - Razorpay/Stripe integration for online fee collection
• Phase 6 — Mobile Applications (Planned) - Native iOS and Android apps for applicants
• Phase 7 — SMS Notifications (Planned) - Twilio integration for SMS status updates
• Phase 8 — Multi-Institute Support (Future) - SaaS platform for multiple educational institutions

Error Handling and Logging Strategy

The backend implements a comprehensive error handling strategy that ensures graceful degradation and provides actionable diagnostics for operators. The custom error handler middleware catches all unhandled exceptions and formats them into consistent JSON responses with appropriate HTTP status codes.

// backend/middleware/errorHandler.js
const errorHandler = (err, req, res, next) => {
  let error = { ...err };
  error.message = err.message;

  // Log for debugging
  logger.error(`[Error] ${err.message}`);
  if (err.stack) {
    logger.error(err.stack);
  }

  // Mongoose bad ObjectId
  if (err.name === 'CastError') {
    error.message = 'Resource not found';
    error.statusCode = 404;
  }

  // Mongoose duplicate key
  if (err.code === 11000) {
    error.message = 'Duplicate field value entered';
    error.statusCode = 400;
  }

  // Mongoose validation error
  if (err.name === 'ValidationError') {
    const messages = Object.values(err.errors).map(val => val.message);
    error.message = messages.join(', ');
    error.statusCode = 400;
  }

  res.status(error.statusCode || 500).json({
    success: false,
    message: error.message || 'Server Error',
  });
};

Winston logger is configured with multiple transports: console output for development debugging, file-based rotation for production logs, and exception handling with automatic process exit and recovery logging. Log entries are structured JSON objects with timestamp, level, message, and metadata fields that can be parsed by log aggregation systems.

File Upload Security

File uploads represent a significant attack vector in web applications. The system implements multiple layers of protection. The Multer middleware configures disk storage with custom filename generation using UUID to prevent filename collisions and directory traversal attacks. File type validation uses file extension checking and MIME type detection to reject executable payloads. File size limits are enforced at both the middleware level and client-side to prevent denial-of-service attacks through large file uploads.

// backend/middleware/uploadMiddleware.js
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    let dir = 'uploads/documents';
    if (file.fieldname === 'photo') dir = 'uploads/photos';
    else if (file.fieldname === 'paymentProof') dir = 'uploads/paymentProofs';
    cb(null, dir);
  },
  filename: (req, file, cb) => {
    const ext = path.extname(file.originalname);
    cb(null, `${uuidv4()}${ext}`);
  }
});

const fileFilter = (req, file, cb) => {
  const allowedTypes = ['application/pdf', 'image/jpeg', 'image/png'];
  if (allowedTypes.includes(file.mimetype)) {
    cb(null, true);
  } else {
    cb(new Error('Invalid file type. Only PDF, JPEG, and PNG are allowed.'), false);
  }
};

const upload = multer({
  storage,
  fileFilter,
  limits: { fileSize: 2 * 1024 * 1024 } // 2MB limit
});

Analytics Pipeline

The analytics endpoint performs MongoDB aggregation pipelines to compute real-time statistics without impacting the primary application database. The course distribution aggregation groups submissions by course field and counts occurrences, while the status breakdown aggregation provides the counts of Pending, Approved, and Rejected applications. The daily trend calculation uses the dateToString operator to format timestamps into daily buckets for the last 30 days.

// backend/controllers/submissionController.js
const getAnalytics = async (req, res, next) => {
  const courseDistribution = await Submission.aggregate([
    { $group: { _id: '$course', count: { $sum: 1 } } },
    { $project: { course: '$_id', count: 1, _id: 0 } },
  ]);

  const statusBreakdown = await Submission.aggregate([
    { $group: { _id: '$status', count: { $sum: 1 } } },
  ]);

  const thirtyDaysAgo = new Date();
  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

  const dailyTrend = await Submission.aggregate([
    { $match: { createdAt: { $gte: thirtyDaysAgo } } },
    {
      $group: {
        _id: { $dateToString: { format: '%Y-%m-%d', date: '$createdAt' } },
        count: { $sum: 1 },
      },
    },
    { $sort: { _id: 1 } },
  ]);
};

Email Template System

The email service implements a branded HTML template system using inline CSS for maximum email client compatibility. All emails follow a consistent visual identity with gradient headers, professional typography, and responsive layouts that render correctly across desktop and mobile clients. The template includes conditional content blocks that display different messaging based on application status, such as attaching admission letters only when status changes to Approved.

// backend/utils/emailService.js
const emailStyle = `
  .email-container { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; 
                     line-height: 1.6; color: #333; max-width: 600px; margin: 0 auto; 
                     border: 1px solid #e0e0e0; border-radius: 12px; overflow: hidden; }
  .header { background: linear-gradient(135deg, #1e3c72 0%, #2a5298 100%); 
            padding: 30px; text-align: center; color: white; }
  .status-badge { display: inline-block; padding: 4px 12px; border-radius: 20px; 
                  font-weight: 600; text-transform: uppercase; font-size: 11px; }
  .status-Approved { background-color: #e6fffa; color: #008672; }
  .status-Rejected { background-color: #fff5f5; color: #e53e3e; }
  .status-Pending { background-color: #fffaf0; color: #dd6b20; }
`;

Conclusion

The FMS Admission Form System transformed the BD Foundation's admission process from a manual, paper-intensive workflow into a streamlined digital operation. The system processes over 2,500 applications annually across 12+ course categories, with automated status tracking eliminating thousands of phone inquiries. The production-ready architecture with Docker containerization and Traefik reverse proxy ensures reliable 99.5% API uptime, while the comprehensive admin dashboard provides decision-makers with actionable insights through real-time analytics.

The multi-step wizard with state persistence improved application completion rates by reducing form abandonment caused by overwhelming single-page layouts. The automated email pipeline with PDF attachments reduced administrative overhead by approximately 12 hours per week that was previously spent on manual status notifications and document preparation. The Google Sheets synchronization enables immediate access to application data for external stakeholders who require spreadsheet-based workflows, eliminating the need for manual data exports.

Security considerations were embedded throughout the development lifecycle, from rate limiting that prevents abuse to file upload restrictions that block malicious payloads. The JWT-based authentication with bcrypt password hashing provides enterprise-grade access control, while the MongoDB input sanitization prevents injection attacks. The centralized logging with Winston ensures operational visibility and facilitates troubleshooting when issues arise in production.