SAMS — Smart Asset Management System

Centralized asset lifecycle management, QR-enabled tracking, and collaborative operations for modern teams.

 

---

Overview

SAMS streamlines how enterprises catalogue, monitor, audit, and label fixed assets across locations. Assets, properties, users, tickets, and audit workflows live in a cohesive UI backed by modern tooling (React, TypeScript, Supabase).

Why SAMS

• Replace spreadsheets with a single source of truth for asset history and ownership.
• Enable facilities, finance, and audit teams to collaborate with guardrails.
• Deliver QR-ready labels and mobile friendly workflows for field operations.

Table of Contents

• Product Highlights
• Platform Modules
• Technology Stack
• Getting Started
  • Prerequisites
  • Installation
  • Environment Configuration
• Everyday Development
• Quality & Observability
• Pending Initiatives
• Deployment Notes
• Live Demo
• Support
• Browser & Device Support
• License & Conduct

Product Highlights

Asset Lifecycle & Registry

• Rich asset metadata (status, ownership, procurement, lifecycle dates).
• Quantity normalization into unit level records for accurate tracking.
• Natural asset ID ordering keeps sibling items grouped together.

Properties & Access Control

• Property directory with status flagging and role-based visibility.
• Department and property access configurations scoped per user.
• Approval indicators surface pending admin/manager actions in context.

QR Labelling & Printing Workflows

• One-off and bulk QR generation with PNG, ZIP, and PDF export flows.
• Label presets plus custom sizing for print hardware alignment.
• Print history and reprint safeguards for audit evidence.

Tickets, Notifications & Collaboration

• Role-aware maintenance tickets with Kanban and list views.
• SLA and priority badges, comment locking on closed tickets.
• Notification bell with deep links that open scoped context instantly.

Insights & Reliability

• Dashboard metrics, reports, and downloadable exports for audits.
• PWA-ready install experience with offline asset list caching.

Platform Modules

Module	What It Covers
Dashboard	Metrics, activity feed, quick actions, audit readiness snapshot
Assets	Advanced table & grid views, QR generation, bulk actions, exports
Properties	Location registry, status controls, per-role visibility
QR Codes	History, preview, downloads, print orchestration
Tickets	Maintenance lifecycle, SLA tracking, Kanban board
Announcements	Release notes, maintenance bulletins, category badges
Reports	Operational insights, audit exports, scoped access
Settings & Users	Role management, permissions, department/property access

Technology Stack

• Frontend: React 18, TypeScript, Vite, Tailwind CSS, Shadcn UI, Radix Primitives
• State & Data: React Query, context providers, local caching fallbacks
• Backend Services: Supabase (Auth, Database, Storage) with demo/local mock layers
• Utilities: date-fns, ExcelJS, ZXing, JSZip, Zod schema validation
• Tooling: ESLint, TypeScript, Prettier (via editor integration), pnpm/npm scripts

Getting Started

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• Supabase project (optional for local demo & auth features)

Installation

# install dependencies
pnpm install

# start the development server
pnpm dev

Visit http://localhost:5173 in your browser.

Environment Configuration

Copy .env.example to .env.local and populate the following when integrating with Supabase:

VITE_SUPABASE_URL=
VITE_SUPABASE_SERVICE_KEY=
VITE_SUPABASE_ANON_KEY=

When the environment variables are absent, SAMS gracefully falls back to seeded demo data, allowing evaluation without backend services.

Everyday Development

• pnpm dev — run locally with hot module replacement.
• pnpm lint — enforce TypeScript and accessibility rules via ESLint.
• pnpm build — create a production bundle through Vite.
• pnpm preview — serve the production build locally.

We recommend enabling the workspace ESLint and Tailwind extensions in VS Code for instant feedback.

Quality & Observability

• Testing: component level tests are being introduced alongside critical modules; snapshot and regression suites are planned for future milestones.
• Accessibility: UI patterns follow Shadcn/Radix best practices (keyboard navigable, ARIA annotations).
• Logging: application events are surfaced through toast notifications and audit trails; Supabase provides server-side logs when enabled.

Pending Initiatives

These items are actively tracked for upcoming releases:

• Advanced analytics dashboard with multi-property drill downs.
• Offline-first write queue for ticket updates made in the field.
• Automated label layout designer with saved presets per printer model.
• End-to-end testing harness (Playwright) integrated into CI.
• Role-based data retention policies and export audit trails.

Deployment Notes

• Vercel is the reference deployment target (see vercel.json).
• Configure environment variables through the Vercel dashboard or your hosting provider of choice.
• For self-hosting, ensure HTTPS is enforced; QR download endpoints expect secure origins for camera access.

Live Demo

Demo credentials: Username [email protected]  •  Password demo@123

Support

Need help, feature guidance, or a tailored walkthrough?

• Email: [email protected]
• Issues: open a GitHub ticket to report bugs or request enhancements.

Browser & Device Support

• Fully responsive layouts for desktop, tablet, and mobile breakpoints.
• Optimized for the latest versions of Chrome, Edge, Firefox, and Safari.
• Installable PWA for quick launch on mobile and desktop.

License & Conduct

This project is open source under the MIT License. Contributions adhere to the community Code of Conduct; please review both before submitting pull requests.

---

© SAMS Contributors. Built for resilient asset operations.