Smart Maintenance Request System

Overview

Smart Maintenance Request System is a web application that automatically analyzes and prioritizes maintenance requests from tenants. The system helps property managers quickly distinguish urgent issues from less important ones, streamlining property maintenance operations.

---

Key Design Decisions

• Next.js (TypeScript) – Enables rapid development, SSR, API routes and seamless integration of frontend and backend logic in a single codebase.
• TypeScript – Provides static typing, better code safety and improved developer experience.
• MongoDB – Flexible, scalable NoSQL database for storing maintenance requests, supporting fast queries and easy schema evolution.
• Mock Analysis Service – A dedicated /api/analyze endpoint simulates external AI analysis using keyword-based logic, making the system easy to test and extend.
• Separation of Concerns – Clear modular structure: analysis logic, API endpoints, data models/types and database configuration are all separated for maintainability and scalability.
• Error Handling – All endpoints include basic error handling and validation to ensure robust API behavior.
• Testing with Jest – Comprehensive unit and integration tests for all main endpoints, including edge cases and error scenarios.
• Responsive UI – Component-based React UI with filtering, searching, and pagination for efficient request management.
• Environment Configuration – Uses environment variables for database credentials and configuration, supporting both local and cloud deployments.
• Extensibility – The system is designed to be easily extended with new keywords, additional request fields, or integration with real AI services in the future.

---

How to Run the Project

Prerequisites

• Node.js (v18 or newer)
• npm or yarn
• MongoDB instance (local or cloud)

Installation

1. Clone the repository:

   git clone <repo-url>
   cd smart-maintenance-request-system

2. Install dependencies:

   npm install

3. Configure environment variables:
   • Create a .env file in the root directory.
   • Add your MongoDB connection string:

     MONGODB_URI=mongodb+srv://<username>:<password>@<cluster-url>/<dbname>?retryWrites=true&w=majority

Running the App

npm run dev

The app will be available at: http://localhost:3000

Running Tests

npm run test:coverage

---

API Usage Examples

1. Analyze Endpoint

• POST /api/analyze
• Description: Analyzes the request message and returns detected keywords, urgency indicators, and a priority score.
• Request Body:

  {
    "message": "Bathroom pipe burst, water everywhere!"
  }

• Response Example:

  {
    "keywords": ["pipe burst", "water"],
    "urgencyIndicators": 1,
    "priorityScore": 0.9
  }

2. Requests Endpoint

Submit a Request

• POST /api/requests
• Request Body:

  {
    "tenantId": "T-12345",
    "message": "Kitchen sink is leaking badly!",
    "timestamp": "2025-06-05T10:00:00Z"
  }

• Response Example:

  {
    "requestId": "REQ1234",
    "priority": "high",
    "analyzedFactors": {
      "keywords": ["pipe burst", "water"],
      "urgencyIndicators": 1,
      "priorityScore": 0.9
    }
  }

Retrieve Requests (optionally filtered by priority)

• GET /api/requests?priority=high
• Response Example:

  {
    "requests": [
      {
        "id": "REQ1234",
        "tenantId": "T-12345",
        "priority": "high",
        "message": "Kitchen sink is leaking badly!",
        "createdAt": "2025-06-05T10:00:00Z",
        "resolved": false
      }
    ]
  }

---

Sample Test Data

Example requests for testing (can be used with POST /api/requests):

[
  {
    "tenantId": "T-10001",
    "message": "There is a water leak in my bathroom",
    "timestamp": "2025-06-05T09:00:00Z"
  },
  {
    "tenantId": "T-10002",
    "message": "The oven is not working",
    "timestamp": "2025-06-05T09:30:00Z"
  },
  {
    "tenantId": "T-10003",
    "message": "Paint is peeling in the hallway",
    "timestamp": "2025-06-05T10:00:00Z"
  }
]

---

Project Structure

• app/ – Next.js app directory (UI, API routes, components)
• app/api/analyze/route.ts – Mock analysis service
• app/api/requests/route.ts – Request handling (submit, retrieve)
• config/mongodb.ts – MongoDB connection setup
• types/ – TypeScript type definitions
• __tests__/ – Jest unit tests

---

How It Works – Architecture

1. Submission – Tenant fills out a form and describes the issue.
2. Analysis – Backend calls /api/analyze, which assigns a score and priority based on keywords.
3. Storage – The request with priority is saved to MongoDB.
4. Viewing – Manager can view and filter requests by priority and status.
5. Testing – Main use cases and error handling are covered by tests.

---

Screenshots