Senior Project - Information Systems Department
Prince Sultan University

A comprehensive digital maintenance tracking system prototype for military and security vehicles and weapons, built with modern web technologies as a senior capstone project.

ARMS (Asset Readiness Management System) is a full-stack web application prototype developed as an academic demonstration of modern software development practices. This senior project showcases how traditional paper-based maintenance logs can be replaced with a modern, efficient digital solution.

🎓 Academic Context:

• University: Prince Sultan University
• Department: Information Systems
• Project Type: Senior Capstone Project
• Purpose: Prototype demonstration of enterprise-level maintenance management system

💡 Concept Demonstration: This project serves as a proof-of-concept for digital transformation in maintenance management, demonstrating real-world application of learned technologies and methodologies. The system provides real-time tracking, scheduling, and management of vehicle and weapon maintenance across different security sectors (Police, Traffic Police, Military Police).

• Digital Asset Registry - Complete vehicle and weapon inventory management
• Maintenance Tracking - Log, schedule, and monitor maintenance activities
• Real-time Dashboard - Live statistics and maintenance alerts
• Role-based Access Control - Secure authentication with WorkOS integration
• Dark/Light Mode - Modern UI with theme switching
• Mobile Responsive - Optimized for field technicians on mobile devices
• QR Code Integration - Quick asset identification and access (Coming Soon)
• AI-Powered Analytics - Predictive maintenance and intelligent reporting (Coming Soon)

• Next.js 15 - React framework with App Router
• React 19 - Latest React with modern features
• TypeScript - Type-safe development
• Tailwind CSS v4 - Modern utility-first CSS framework
• Shadcn UI - High-quality component library
• next-themes - Dark/light mode support
• Lucide React - Beautiful icons

• tRPC - End-to-end type-safe APIs
• Drizzle ORM - TypeScript ORM for database operations
• NeonDB - Serverless PostgreSQL database (Coming Soon)
• WorkOS - Enterprise authentication and user management

• pnpm - Fast, disk space efficient package manager
• ESLint - Code linting and formatting
• Prettier - Code formatting
• Vercel - Deployment and hosting platform

• Google Gemini API - AI-powered maintenance analysis (MVP 3)
• QR Code Libraries - Asset identification system (MVP 2)

• Node.js 18+
• pnpm (recommended) or npm

1. Clone the repository

   git clone https://github.com/FahadAljabr/arms.git
   cd arms

2. Enable pnpm and install dependencies

   corepack enable pnpm
   pnpm install

3. Set up environment variables

   cp .env.example .env
   # Configure your WorkOS and database credentials

4. Run the development server

   pnpm dev

5. Open your browser Navigate to http://localhost:3000

src/
├── app/                          # Next.js App Router
│   ├── dashboard/               # Dashboard page
│   ├── maintenance/             # Maintenance tracking page
│   ├── vehicles/                # Vehicle management page
│   ├── weapons/                 # Weapon management page
│   ├── login/                   # Authentication routes
│   ├── callback/                # WorkOS callback handling
│   └── layout.tsx               # Global layout with navigation
├── components/
│   ├── ui/                      # Shadcn UI components
│   ├── main-navigation.tsx      # Global navigation component
│   ├── theme-provider.tsx       # Dark mode theme provider
│   └── theme-toggle.tsx         # Dark/light mode toggle
├── server/
│   ├── api/                     # tRPC API configuration
│   └── db/                      # Database schema and connection
├── styles/
│   └── globals.css              # Global styles with Tailwind CSS
└── trpc/                        # tRPC client configuration

• ✅ Asset registration (vehicles/weapons)
• ✅ Maintenance record logging interface
• ✅ Historical record viewing
• ✅ Role-based authentication (WorkOS)
• 🟡 Database integration (NeonDB setup pending)
• 🟡 Backend CRUD operations (in progress)

• Real-time dashboard with statistics
• Preventive maintenance scheduling
• Parts inventory management
• QR code generation for assets
• Mobile-optimized interface

• AI-powered predictive maintenance
• Intelligent report analysis with Gemini AI
• Risk scoring and recommendations
• Natural language query interface

• WorkOS Integration - Enterprise-grade authentication
• Role-based Access Control - Maintenance Technicians vs Responsible Officers
• Secure Session Management - JWT tokens with proper expiration
• Audit Trail Logging - Complete activity tracking (Coming Soon)

This application now delegates all user identities and roles to WorkOS AuthKit and RBAC. The local database no longer stores users or roles. Instead, tables reference WorkOS user IDs (e.g., user_01...).

• Sign-in, sessions, and logout are handled by @workos-inc/authkit-nextjs.
• Role checks in the backend use WorkOS role data from the session; see src/server/auth/roles.ts.
• Tables like maintenance records reference WorkOS user IDs directly; foreign keys to a local users table were removed.

Required environment variables (see src/env.js):

• WORKOS_API_KEY – Server-side key for WorkOS SDK
• WORKOS_CLIENT_ID – Client ID for AuthKit
• WORKOS_COOKIE_PASSWORD – 32+ char cookie secret

Recommended dashboard setup in WorkOS:

• Create an Organization for your environment (single-tenant) or multiple (multi-tenant).
• Define roles (e.g., technician, officer) under RBAC.
• Assign user memberships and roles within the Organization.

Local DB migration (only if you are managing your own Postgres):

pnpm db:generate   # generate migration for schema changes
pnpm db:push       # push changes to your dev database

Note: In development, we've kept compatibility stubs so existing UI compiles while roles/users are removed from the schema:

• src/server/auth/provision.ts is now a no-op.
• postRouter.getLatest returns null to keep client types compiling.

• Modern Design System - Clean, professional interface
• Dark/Light Mode - User preference-based theming
• Responsive Design - Works seamlessly on desktop and mobile
• Accessibility - WCAG compliant components
• Interactive Components - Rich forms, tables, and data visualization

The system is designed with field technicians in mind:

• Touch-friendly interface for mobile devices
• QR code scanning capabilities (coming soon)
• Offline-capable data entry (future enhancement)
• Quick access to asset information

This project follows modern development practices:

1. Code Quality - TypeScript strict mode, ESLint, Prettier
2. Component Architecture - Reusable Shadcn UI components
3. Type Safety - End-to-end type safety with tRPC
4. Modern React Patterns - Server Components, Suspense, Error Boundaries

# Development
pnpm dev              # Start development server
pnpm build            # Build for production
pnpm start            # Start production server

# Code Quality
pnpm lint             # Run ESLint
pnpm lint:fix         # Fix ESLint issues
pnpm typecheck        # TypeScript type checking
pnpm format:check     # Check Prettier formatting
pnpm format:write     # Apply Prettier formatting

# Database
pnpm db:generate      # Generate Drizzle migrations
pnpm db:migrate       # Run database migrations
pnpm db:push          # Push schema to database
pnpm db:studio        # Open Drizzle Studio

• Next.js App Router - Modern React architecture with server components
• Shadcn UI - Consistent, accessible component library
• tRPC - Type-safe API development without code generation
• Drizzle ORM - Lightweight, type-safe database operations
• WorkOS - Enterprise authentication without custom user management
• Tailwind CSS v4 - Latest utility-first CSS framework

Open Source License (Copyleft)

This project is released under an open source copyleft license. You are free to:

• ✅ Use this software for any purpose
• ✅ Study and modify the source code
• ✅ Distribute copies of the software
• ✅ Distribute modified versions

⚠️ Copyleft Requirement: If you use this software in your own projects, you must also make your project open source under the same license terms. This ensures that improvements and modifications remain available to the community.

This is a senior capstone project from Prince Sultan University's Information Systems program, designed to demonstrate:

• Modern full-stack web development practices
• Enterprise software architecture patterns
• Real-world problem-solving through technology
• Integration of multiple modern technologies and APIs

Student Developer: Fahad Aljabr Institution: Prince Sultan University - Department of Computer & Information Sciences

For academic inquiries or technical questions about this prototype, please contact through university channels.

Built with ❤️ at Prince Sultan University using the T3 Stack and modern web technologies