mem-dashboard / README.md
MEM Dashboard (rigs and hoists plotter)
MEM dashboard
MEM Dashboard (rigs and hoists plotter)
The client, Ministry of Energy and Minerals, was inspired by the visual appeal of the RAM Project and requested a similarly engaging dashboard. They need a visually appealing and intuitive interface to monitor units (rigs and hoists) and workforce data in real time. This will support decision-making for workforce deployment, especially as unit terms approach their end.
1. Problem Statement
The Ministry of Energy and Minerals lacks a centralized, real-time dashboard to visualize rigs, hoists, and workforce data, making it difficult to plan timely workforce deployments as unit terms near expiration.
2. Supporting documents
- Product brief
- System design
- API endpoints documentation
- Glossary
- Unit states explanation
- Known Issues
3. Getting started
3.1. Pre-requisites
list all pre-requisitses for the project to be able to run on any system }} Examples:
3.2. Project setup
Clone the repository
git clone https://github.com/rihal-om/mem-dashboard.git
cd mem-dashboard
Running the app locally
Since the app is fully frontend at the time of documenting, all you have to do is run the /web
- Change directory to the
web
cd web
- Install node dependancies
pnpm install
- Start the web app locally
pnpm dev
4. Building and publishing the app to production
In case you want to build and publish the app to production, follow these steps:
- If needed, edit the tag of the web image
docker-compose.build.yamlanddocker-compose.prod.yaml - Run
docker compose -f docker-compose.build.yaml buildto build the web image - Run
docker compose -f docker-compose.build.yaml pushto push the images to GitHub - Then, login into the ministry's portainer (secrets stored in vaultwarden)
- Modify the
mem-dashboardstack by editing the web image tag to be the new one and click on "update the stack" - The new docker image should be fetched from github and deployed, and you're good to go!
5. Project Structure
General structure of the project is as follows:
| Folder | Purpose |
|---|---|
docs | Contains project documentation files |
geojson | Stores GeoJSON files for geographic data and mapping features |
utils | Houses utility functions and helper modules |
web | Contains web application files (frontend code, assets, etc.) |
The app relies on GeoJson files to be able to meet the client's requirements,
utils/blocks_process.pyis used to cleanupgeojson/oman_blocks.geojsonfile to remove unnecessary data and make it more suitable for the app's needs. The cleaned up file is stored inweb/public/oman_blocks_processed.geojson; which is then used in the app to render the map and display the blocks.
6. Web Folder Structure
Almost all the code is in the web folder, which is structured as follows:
| Folder/File | Purpose |
|---|---|
public | Static assets served directly (images, favicon, etc.) |
src | Source code directory containing all application logic |
src/api | API-related functions and service calls -- currently only containing the axios configs |
src/components | Reusable React components that are not logic heavy |
src/feature | Feature-specific modules and components -- consists of components and some logic |
src/hooks | Custom React hooks -- containes most of data caching and filtering logic |
src/pages | Page components -- collection of componentts, features and data logic that falls under a single view |
src/store | State management -- Zustand store for global state management |
src/types | TypeScript type definitions |
src/utils | Utility functions and helpers |
App.tsx | Main component, has the routes and the main layout -- app is supposed to be simple |
index.css | Global CSS styles |
main.tsx | Application entry point |
vite-env.d.ts | Vite environment type declarations |
7. Tech Stack
Note to maintainers: Update the table when additional services or tools are introduced.
| Category | Tool | Description |
|---|---|---|
| Frontend | React.js | A declarative, component-based JavaScript library for building user interfaces |
| Containerization | Docker | A platform for developing, shipping, and running applications in isolated containers |
| CI/CD | GitHub Actions | A flexible automation tool for building, testing, and deploying code directly from GitHub |
Breakdown of the important libraries and tools used in the project:
| Category | Tool | Description |
|---|---|---|
| State Management | Zustand | A small, fast, and scalable state management solution for React applications |
| Styling | Tailwind CSS | A utility-first CSS framework for rapid UI development |
| Routing | React Router | A collection of navigational components that compose declaratively with your application |
| HTTP Client | Axios | A promise-based HTTP client for the browser and Node.js |
| Components Library | Custom Components | Custom-built reusable components for the dashboard UI |
| Map | mapLibre & ract-map-gl | A library for integrating interactive maps into React applications, using MapLibre GL JS for rendering |
Project Team
| Name | Role | GitHub |
|---|---|---|
| Vineeth Kumar | Project Manager | Vineeth.Kumar@tp.rihal.om |
| Jishnu Kidile | UX/UI Designer | Jishnu.Kidile@rihal.om |
| Maymoona Al Balushi | Lead Frontend Dev | @MaymoonaAlBoloshi |
| Mohamed Al-Rasbi | Backend Developer | @mohdrasbi |
Feel free to reach out to any of us for questions, feedback, or collaboration opportunities. We are always open to discussing new ideas and improvements for the project.
Happy coding!