---
# System prepended metadata

title: Web Application Design Document

---


# Web Application Design Document
## Overview
This design document outlines the architecture and key design choices for a simple web application to allow users to search for activities. This application will consist of a backend built using NestJS, a frontend developed with React, and communication between the two will be handled via RESTful APIs.

## Project Goals
The primary goal is to demonstrate the ability to develop a scalable and maintainable application using modern development practices and frameworks. The application is not intended to be production-ready but will adhere to best practices to ensure quality and potential scalability.

## System Architecture
### Backend (NestJS)
NestJS is chosen for its scalable architecture and its extensibility, which supports TypeScript. It integrates well with other libraries and allows for easy testing.

#### Key Components:
- Controller: Handles incoming requests related to activities.
- Service: Business logic layer that interacts with the data source.
- Module: Groups related components together.

#### Request Validation
- Current State: 
    - Validate param and query for incoming requests.
    - Improvement: Enhance structured error handling by introducing Winston/Bunyan library.
- Reason: 
    - Fined logging messages help in quickly diagnosing issues in future production.
    - Possibility to scale up by integrating with a log management system like Elastic Stack or Datadog.


#### Data Handling:
- Current State: 
    - Static JSON File: Initially, the application will use the provided activities.json for simplicity.
    - Use asyncronisation API handling although synchronization method could solve the problem.
- Consideration:
    - Database (Future Improvement): For scalability, migrating to a database like PostgreSQL or MongoDB would be beneficial
-  Reason: data is expected to be dynamically fetched, async promise is applied in favor of the flexibility.  

#### Error Handling and Logging
- Current State: 
    - Advanced error handling and detailed logs using middleware and interceptors globally.
    - Improvement: Enhance structured error handling by introducing Winston/Bunyan library.
- Reason: 
    - Fined logging messages help in quickly diagnosing issues in future production.
    - Possibility to scale up by integrating with a log management system like Elastic Stack or Datadog.

#### Performance Optimization
- Current State: 
    - Make use of [Fastify](https://github.com/fastify/fastify) framework to optimize performance. 
- Reason:
    - In compare of default framework `Express` using in Nest. `Fastify` is two times better benchmarks than Express.  


### Frontend (React)
React is selected for its component-based architecture, which helps in building reusable UI components.

#### Key Components:
- Activity List View: Displays all activities.
- Search Component: Allows users to search activities by title.
- Activity Item Component: Displays the title, price, rating, special offer status, supplier name, and location.

#### Search Input Optimization/Clean up
- Current State: 
    - Trimming user input in the search function
- Reason: 
    - Improved Usability and User Experience
- Improvement: add filter functions for more incoming options; introduce form library for more features on validation fields.
    - Reason:     
        - Enhanced Performance
        - Increased Security



### C4 Diagram
1. Level 1: System Context:
- Actors: 
    - Users: Individuals using the application to find activities.
- Activity Search Application: The complete system that provides activity searching capabilities to the users.
![image](https://hackmd.io/_uploads/r1gHj2sWR.png)


2. Level 2: Container Diagram
- System: Web Application
- Containers:
    - Web Application (React): Handles the user interface and user interactions. It communicates with the backend via API calls.
    - Backend API (NestJS): Processes business logic, accesses data from the JSON file, and handles API requests from the frontend.
![image](https://hackmd.io/_uploads/ryFBoniWR.png)



### API Design
- GET /activities?relationions[]: Fetches all activities.
    - with optional relations, could get 'suppliers' together with the activity, add the flexibility for the frontend design.
- GET /activities/\:id: Get activities by id.

### Filtering Logic
- The filtering by title implemented on the server-side.
- Reason:
    - In target to minimize the data transferred over the network and offload the processing from the client.


## Development and Deployment
- Docker: The application will be containerized using Docker, making it easy to build and deploy.
- Docker Compose: Use Docker Compose to manage multi-container Docker applications.

## Documentation
- Code Documentation: Use JSDoc for backend and Prop Types for frontend to document the codebase.
- API Documentation: Use tools Swagger, could access the endpoint by: [Document Endpoint ](http://localhost:3000/api/v1/document)
- Assumptions
    - The application is initially expected to handle a moderate load; hence, a JSON file and single-instance deployment are considered sufficient for initial testing purposes.
    - Users are not required to log in, as user management is not part of the core functionality at this stage.
    - Database is expected to be applied in the future.


## Potential Improvements
### System Scope
#### Scalability
- Load Balancing: Utilize load balancers to distribute requests across multiple instances of the application.
- Caching: Implement caching strategies for frequent queries to reduce database load and improve response times.
- Microservices (Future Scope): Break down the application into smaller, independent microservices to improve modularity and scalability.

#### Security Considerations
- Input Validation: Ensure all user input is validated on the server side to prevent SQL injection and other malicious attacks.
- HTTPS: Use HTTPS to encrypt data in transit.
- Authentication and Authorization (Future Improvement): Implement OAuth for secure API access.


### Backend
- Database Integration: Replace the static JSON file with a database to handle larger data sets and complex queries more efficiently.
- User Authentication: Add user management and authentication to personalize the application and secure sensitive data.
- Cache: set the expiration time for 10 mins.
- Global Pipe to trim requests input

### Frontend
- Advanced Search Features: Implement more sophisticated search capabilities (e.g., filtering by price range, rating, etc.).
- Pagination: As the data scaling up, pagination is required for accessibility.
- Local Cache: Since the API requests are idempotent, cache for local storage. 
- Internationalization(i18n): Prepare the application for different locales by adding internationalization support.
- Debounce: [to be continue]

