Build-first-run-onboarding-wizard

[MaryammAli]

feat: Build first-run onboarding wizard for new organisations

Summary

Implements a first-run onboarding wizard to guide newly created organisations through the initial AssetsUp setup process. The onboarding flow eliminates the blank-state experience by walking users through configuring their organisation, creating foundational data, and adding their first asset.

Closes FE-40.

What Changed

• Added a multi-step onboarding wizard accessible after first login for new organisations.
• Introduced a progress indicator showing the current onboarding step.
• Added support for exiting the onboarding flow while preventing it from appearing again once completed.
• Integrated existing backend endpoints for creating organisation resources.

Onboarding Steps

Step 1 – Organisation

• Update organisation name

• Optional logo upload

• Uses:

  • PATCH /organisations/me

Step 2 – First Department

• Create the first department

• Fields:

  • Name
  • Description

• Includes Skip option

• Uses:

  • POST /departments

Step 3 – Asset Categories

• Create 1–3 asset categories

• Suggested categories:

  • IT Equipment
  • Furniture
  • Vehicles

• Uses:

  • POST /categories

Step 4 – First Asset

• Simplified asset creation

• Fields:

  • Asset name
  • Category
  • Status

• Includes Skip option

• Uses:

  • POST /assets

Step 5 – Completion

• Success screen with confetti animation

• Quick links to:

  • Assets page
  • Import Assets wizard

Additional Features

• Progress indicator (e.g. Step 2 of 5)

• "Exit Setup" button

• Completion state persisted via localStorage (or user profile if supported)

• Wizard only appears when:

  • Organisation has 0 departments
  • Organisation has 0 assets
  • Onboarding has not been marked complete

Acceptance Criteria

• ✅ Organisation setup step implemented
• ✅ Department creation with Skip option
• ✅ Asset category creation with suggested templates
• ✅ Simplified first asset creation with Skip option
• ✅ Completion screen with navigation actions
• ✅ Progress indicator across all steps
• ✅ Exit Setup functionality
• ✅ Onboarding never shown again after completion

Testing

• Verified onboarding displays only for eligible organisations.
• Verified each step successfully calls the appropriate API endpoint.
• Verified Skip actions advance the wizard correctly.
• Verified Exit Setup prevents the wizard from reappearing.
• Verified successful completion displays the completion screen and redirects correctly.
• Verified onboarding state persists after page refresh.

Notes

• Existing API endpoints are reused; no backend changes required.
• Designed to be extensible for future onboarding steps.
• Supports rendering as either a dedicated /onboarding route or a dashboard modal, depending on application configuration.

feat: Build asset map and geolocation view

Summary

Implements an interactive map view for geolocated assets, allowing users to visualize asset locations, monitor field equipment, and quickly identify asset distribution across different locations.

Closes FE-41.

What Changed

• Added a dedicated Map View page for assets.
• Integrated an interactive map using a lightweight open-source mapping library.
• Plotted asset locations using GPS coordinates retrieved from the backend.
• Added clustering for nearby markers to improve map readability.
• Added filtering options to quickly locate assets by department, category, and status.
• Added a view toggle on the Assets page to switch between list and map views.

Features

Interactive Map

• Created frontend/app/(dashboard)/map/page.tsx

• Displays an interactive map centered on available asset locations.

• Fetches asset location data from:

  • GET /assets/map

Asset Markers

Each asset is rendered as a marker using:

• currentLatitude
• currentLongitude

Markers are colour-coded by asset status:

• 🟢 Active
• 🔵 Assigned
• 🟠 Maintenance
• ⚪ Retired

Marker Details

Clicking a marker opens a popup displaying:

• Asset name
• Asset ID
• Status badge
• Assigned user (if applicable)
• Link to the asset details page

Marker Clustering

• Groups nearby markers when zoomed out.
• Automatically expands clusters as users zoom in.
• Improves performance and reduces visual clutter.

Filters

Added sidebar filters for:

• Department
• Category
• Asset Status

Filters update the displayed markers in real time.

Assets Page Integration

Added a Map View toggle on the standard /assets page, allowing users to seamlessly switch between:

• List View
• Map View

Also added Map View to the application sidebar for quick navigation.

Acceptance Criteria

• ✅ Interactive asset map implemented
• ✅ Assets plotted using GPS coordinates
• ✅ Status-based marker colours
• ✅ Asset information popups
• ✅ Marker clustering for nearby assets
• ✅ Sidebar filters for department, category, and status
• ✅ Assets page list/map toggle implemented
• ✅ Sidebar navigation updated with Map View

Testing

• Verified map loads successfully.
• Verified assets are rendered at correct GPS coordinates.
• Verified marker colours correspond to asset status.
• Verified popup information is accurate.
• Verified clustering behaves correctly across zoom levels.
• Verified filters update markers correctly.
• Verified navigation between list and map views.
• Verified assets without coordinates are safely excluded from the map.

Notes

• Depends on BE-36 (GET /assets/map).
• Built using a lightweight mapping library to minimize bundle size.
• Designed for future enhancements such as live GPS tracking, geofencing, route visualization, and real-time asset movement monitoring.

Closes #976
Closes #977

[vercel]

@MaryammAli is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.