📍 PlaceBook

Overview

1. Description
2. Deployment Link
3. Installation
4. Technologies Used
5. Deliverables
6. Planning & Build Process
7. Challenges
8. Wins
9. Key Learnings & Takeaways
10. Future Improvements

---

1. Description

  
  

A full-stack MERN application enabling users to share and manage geo-tagged posts of places they’ve visited. Users can register, log in and generate posts with a title, description, image and address. Locations are geocoded from the address using the Google Maps API, and images are previewed with the FileReader API before being uploaded using Multer.
Access is secured with JWT-based authentication, role-based access control and route protection enforced on both on both the client and server sides. Authentication state is managed globally with React Context, enabling dynamic rendering of protected routes and navigation elements.

The React frontend features a responsive interface that is styled with SCSS and uses custom hooks for form handling and HTTP requests.The Express backend connects to MongoDB Atlas for persistent storage and provides a RESTful API with validation via express-validator and custom error handling.

  
  

2. Deployment Link

🔗  https://placebook.katieloesch.co.uk/

backend repository - https://github.com/katieloesch/placebook-backend

3. Installation

To run the application locally:

1. Clone the Repository

git clone https://github.com/your-username/hunting-buddy.git
cd hunting-buddy

2. Install Dependencies

Install the frontend dependencies:

npm install

3. Set Up Environment Variables

• The application requires a .env file in the root directory to function correctly.
  • This file defines the base URLs for the backend API and the Google Maps API key.

1. Create a .env file in the root directory of the project (same level as package.json).

2. Copy the required environment variables listed below into the .env file

   Required Environment Variables:

   REACT_APP_BASE_URL=REACT_APP_BASE_URL=https://placebook-015dbd92649b.herokuapp.com
   REACT_APP_API_BASE_URL=https://placebook-015dbd92649b.herokuapp.com/api
   REACT_APP_GOOGLE_API_KEY=your_google_api_key
   

3. Replace your_google_api_key with your actual Google Maps API key.

   • How to Get a Google Maps API Key:
     1. Go to the Google Maps Platform.
     2. Create an account or sign in.
     3. Get Started > create a new project or select an existing one (you may need to enter a credit card but there should be a free trial option available)
     4. Enable the Maps JavaScript API and Geocoding API
     5. Generate a new key: + Create Credentials > API key.
     6. Copy the generated key and add it to your .env file as REACT_APP_GOOGLE_API_KEY.

4. Start the App

Once your .env file is set up, start the app:

npm start

• This should launch the frontend on http://localhost:3000 in your default browser
• If it doesn’t open automatically, visit that address manually in your browser.

4. Technologies Used

Core Technologies

This application was built using the MERN stack, an open source–centric collection of technologies that uses JavaScript for both the browser and server sides of a web application:

• Frontend
  • React.js (v18.3.1)
  • _{A JavaScript library for building user interfaces, particularly single-page applications where efficient and dynamic rendering of components is crucial.}
    • _website
    • _{GitHub repository}
• Backend
  • Express.js (v4.19.2)
    • _{A fast and minimalist web framework for Node.js, used to build web applications and APIs.}
    • _{npm page}
    • _{GitHub repository}
    • _website
  • Node.js (v20.14.0)
    • _{A JavaScript runtime built on Chrome's V8 JavaScript engine, allowing developers to use JavaScript to build server-side applications with event-driven, non-blocking I/O.}
    • _website
    • _{GitHub Repository}
• Database
  • MongoDB / MongoDB Atlas (v7.0.12)
    • _{MongoDB: a document-oriented NoSQL database designed for scalability and flexibility, making it easy to store and retrieve large volumes of structured and semi-structured data.}
    • _{MongoDB Atlas: a fully managed cloud-based service that hosts and manages MongoDB databases, provided by the creators of MongoDB.}
    • _{MongoDB website}
    • _{MongoDB GitHub Repository}
    • _{MongoDB Atlas website}
  • Mongoose (v8.5.3)
    • _{A MongoDB object modeling tool designed to work in an asynchronous environment, providing schema-based solutions to model data in a MongoDB database.}
    • _{npm page}
    • _{GitHub repository}
    • _website
    • _mongoDB

Key Dependencies - Frontend

• @fortawesome/free-solid-svg-icons (v6.7.2)
  • _{A package that provides a collection of free, solid-style icons from Font Awesome that can be imported and used in React.}
  • _{npm page}
  • _{GitHub repository}
  • _website
• @fortawesome/react-fontawesome (v0.2.2)
  • _{A package that provides a React component for easily rendering Font Awesome icons in React applications.}
  • _{npm page}
  • _{GitHub repository}
  • _website
• react-router-dom (v6.24.0)
  • _{An implementation of react-router that includes additional components for browser-based routing}
  • _{npm page}
  • _{GitHub repository}
  • _website
• react-transition-group (v4.4.5)
  • _{A library for handling animations and transitions in React applications}
  • _{npm page}
  • _{GitHub repository}
  • _website
• sass (v1.77.8)
  • _{A CSS preprocessor used for styling the application}
  • _{npm page}
  • _{GitHub repository}

Key Dependencies - Backend

• axios (v1.7.4)
  • _{A promise-based HTTP client for Node.js and the browser that simplifies making asynchronous HTTP requests to REST endpoints.}
  • _{npm page}
  • _{GitHub repository}
  • _website
• body-parser (v1.20.2)
  • _{A Node.js body parsing middleware, supporting JSON and URL-encoded data.}
  • _{npm page}
  • _{GitHub repository}
• bcryptjs (v2.4.3)
  • _{A JavaScript library for hashing and comparing passwords securely using the bcrypt algorithm.}
  • _{npm page}
  • _{GitHub repository}
• dotenv (v16.4.5)
  • _{A zero-dependency module that loads environment variables from a .env file into process.env, allowing secure configuration settings management.}
  • _{npm page}
  • _{GitHub repository}
  • _website
• express (v4.19.2)
  • _{A fast and minimalist web framework for Node.js, used to build web applications and APIs.}
  • _{npm page}
  • _{GitHub repository}
  • _website
• express-validator (v7.2.0)
  • _{A set of express.js middleware functions that offer a way to validate and sanitise input data, helping to prevent common security vulnerabilities.}
  • _{npm page}
  • _{GitHub repository}
  • _website
• jsonwebtoken (v9.0.2)
  • _{A library for creating, signing, and verifying JSON Web Tokens (JWTs), which are used for securely transmitting information between parties.}
  • _{npm page}
  • _{GitHub repository}
  • _{website (JsonWebToken implementation for node.js)}
• mongoose (v8.5.3)
  • _{A MongoDB object modeling tool designed to work in an asynchronous environment, providing schema-based solutions to model data in a MongoDB database.}
  • _{npm page}
  • _{GitHub repository}
  • _website
• mongoose-unique-validator (v5.0.1)
  • _{A Mongoose plugin that adds pre-save validation for unique fields within a Mongoose schema, ensuring unique constraints are respected.}
  • _{npm page}
  • _{GitHub repository}
• multer (v1.4.5-lts.1)
  • _{A middleware for handling multipart/form-data, commonly used for uploading files in Express.js applications.}
  • _{npm page}
  • _{GitHub repository}
• nodemon (v3.1.4)
  • _{A utility that automatically restarts your Node.js server when files change, making development faster and more efficient.}
  • _{npm page}
  • _{GitHub repository}
  • _website
• uuid (v10.0.0)
  • _{A library that generates RFC-compliant universally unique identifiers (UUIDs) for use in various applications where unique identification is required.}
  • _{npm page}
  • _{GitHub repository}

UI and Design

• Fonts
  • main: Isidora Soft, designed by Enrique Hernandez Vasquez
    • _{Font Download}
  • header: Rimouski Light, designed by Ray Larabie
    • _{Online WebFonts}
• Icons
  • Iconify
    • _{A free and open-source framework providing access to a vast number of icons, designed for use across various platforms and environments, including React.}
    • _website
    • _{GitHub repository}
    • _license
  • Font Awesome
    • _{An icon library offering a large set of scalable and customisable icons, with a free version that is open source.}
    • _website
    • _{GitHub repository}
    • _license

Development Tools

• Git / GitHub
  • _{Used for version control and collaboration.}
  • _{Git website}
  • _{GitHub website}
• Visual Studio Code (VSCode)
  • _{Code editor used for development.}
  • _website
  • _{GitHub repository}
• Google Chrome & Chrome DevTools
  • _{Used for testing, debugging, and developing in the browser.}
  • _{Google Chrome website}
  • _{Chrome DevTools documentation}
• serve
  • _{Runs a script to start a local static file server, used to preview production builds of frontend app.}
  • _{Google Chrome website}
  • _{Chrome DevTools documentation}
• Excalidraw
  • _{Tool used to create wireframes for the application.}
  • _website
  • _{GitHub repository}
• ChatGPT4o:
  • _{Generative AI tool used for debugging and development support.}
  • _website
  • _{GitHub repository}

Deployment

• Frontend - Hostinger
  • _{Web hosting service that offers shared, cloud, and VPS hosting solutions for websites, domains, and custom applications}
  • _{UK website}
  • _{US website}
• Backend - Heroku
  • _{Cloud platform that enables developers to build, run, and scale applications by abstracting away server infrastructure management}
  • _website
  • _{GitHub repository}

Resources and tutorials

• Documentation
  • _axios
  • _{express-validator}
  • _{FileReader - MDN Web Docs}
• Blogs
  • _{How To Use Axios with React by Paul Halliday and Christina Gorton}
  • _{Introduction to Multer by Geekster}
  • _{Beginner Topic: File Upload With Multer In Nodejs by Olufisayo Bamidele}
  • _{How to use the fileReader to show a file with Javascript by Moulun Kevin}
  • _{How to Handle Form Inputs Efficiently with Express-Validator in ExpressJs by Chiranjeev Singh and Abhimanyu Selvan}
  • _{How to solve CORS error in Node.js and React applications by Abhishek EH/Coding Deft}
  • _{React CORS Guide: What It Is and How to Enable It by StackHawk}
• YouTube
  • _{React Axios API Requests | Axios with React JS Tutorial by Dave Gray}
  • _{express-validator Node.js tutorial by Jan Goebel}
  • _{Uploading Images with Multer | NodeJS and ExpressJS by PedroTech}
  • _{Image Previews in React with FileReader by Leigh Halliday}
• Udemy
  • _{React, NodeJS, Express & MongoDB - The MERN Fullstack Guide by Manuel Lorenz & Maximilian Schwarzmüller}
  • _{React - The Complete Guide 2024 (incl. Next.js, Redux) by Maximilian Schwarzmüller}
  • _{MERN 2024 Edition - MongoDB, Express, React and NodeJS by John Smilga}
  • _{The Complete Node.js Developer Course (3rd Edition) by Andrew Mead & Rob Percival}

5. Deliverables

MVP

1. Authentication & Authorization

• Secure sign-up and login with JWT-based authentication
• Password hashing
• Role-based access control to protect user-specific data and routes

2. Full CRUD operations for places:

• Create new places with title, description, and address
• Upload an image associated with each place
• Edit or delete only the user’s own places
• View all users and their shared places

3. Frontend

• Responsive design with a clean, intuitive layout
• Context API for global state management
• Custom hooks for HTTP requests and form handling
• Real-time image preview during place creation
• Data validation for form inputs
• Interactive map display using Google Maps API to visualize location data

4. Backend

• RESTful API with modular routing, structured error handling, and data validation
• Data validation and sanitization
• Data storage using MongoDB and hosting via MongoDB Atlas

5. Deployment

• Independent deployment of frontend and backend

Potential Extra Features / Stretch Goals

• File upload for user profile picture
• User profile page
• Dark mode toggle
• Pagination for places
• Refresh token and token renewal system
• Cloudinary or S3 for cloud image storage
• Optimize image sizes automatically on upload
• Unit and integration tests (e.g. Jest, React Testing Library, Supertest)

User stories

Authentication & Access Control

• As a user, I should be able to sign up with my email and password, so that I can create an account and start sharing places.
• As a user, I should be able to log in securely, so that I can access and manage my content.
• As a user, I should be automatically logged out when my token expires, so that my account stays secure.
• As a user, I should only be able to access protected pages if I’m authenticated.

Place Management

• As a user, I should be able to add a new place with a title, description, address, and image, so that I can share locations I’ve visited.
• As a user, I should be able to see the address I entered on a map.
• As a user, I should be able to upload an image when creating a place.
• As a user, I should be able to preview my image before uploading it.
• As a user, I should be able to edit or delete a place, so that I can keep my content accurate and up to date.
• As a user, I should be able to view a list of all places shared by a specific user, so that I can see what others have shared.

User Experience & Interface

• As a user, I should be able to use the app comfortably on any device.
• As a user, I should be able to see loading spinners during data fetches, so that I know the app is working.
• As a user, I should be able to see error messages and modals when something goes wrong, so that I understand what’s happening and how to fix it.

6. Planning & Build Process

wireframe

ERD

7. Challenges

• Authorization Logic: Ensuring that only the original creator of a post could edit or delete their own content required careful implementation of role checks and user ID validation on both the client and server sides.
• CORS Configuration for Cross-Origin Requests: Allowing the frontend and backend to communicate across different domains required configuring CORS headers and handling preflight OPTIONS requests.
• Address Geocoding: Converting user-entered addresses into geo-coordinates for map display involved integrating a geocoding API, managing fallback behaviour, and gracefully handling errors or ambiguous results.
• Conditional Routing Based on Auth State: Dynamically rendering routes and navigation links based on the user's authentication status involved using React Context, route guards, and maintaining consistent state across components.
• File and Error Cleanup: Ensuring that uploaded files weren’t left orphaned after failed requests or remained after their associated places were deleted required implementing cleanup logic both during error handling and on resource deletion.

8. Wins

• Implemented role-based access control and JWT-based authentication with hashed passwords using bcryptjs, ensuring secure user login and registration.
• Achieved full CRUD functionality and integrated the Google Maps API to convert user-provided addresses into geo-coordinates, rendering them on a dynamic map.
• Created custom React hooks to encapsulate HTTP request and form logic, resulting in cleaner and reusable code.
• Delivered a fully responsive user interface that works across both desktop and mobile devices.
• Successfully deployed the frontend and backend independently on separate platforms.

9. Key Learnings & Takeaways

• Managed to build a full-stack MERN application from scratch, understanding how frontend and backend systems interact.
• Learned how to implement secure authentication using JWTs and password hashing with bcryptjs, including route protection on both client and server sides.
• Gained experience bridging frontend UX with real-world data services by integrating the Google Maps API to dynamically convert addresses into coordinates and display them on an interactive map
• Developed custom React hooks to abstract logic for HTTP requests and form handling, reinforcing the value of modular, reusable code.
• Deepened my understanding of CORS, environment variables, and cross-origin cookie/session strategies by deploying and debugging a split-stack MERN app

10. Future Improvements

• Testing Suite: Implement unit and integration tests using tools e.g. Jest, React Testing Library, Supertest
• Cloud Image Storage: Migrate image uploads to cloud-based solutions like Cloudinary or AWS S3
• Admin Dashboard: Develop an admin interface to view, manage, and moderate all user-generated content.
• Pagination: Introduce pagination for user and place listings to improve performance and user experience on data-heavy pages.
• Dark Mode: Introduce a dark mode toggle to accommodate user preferences.
• Accessibility Enhancements: Conduct accessibility audits and implement features such as keyboard navigation, screen reader compatibility, and ARIA roles to ensure an inclusive user experience.