car_mms/.kiro/specs/car-maintenance-system/requirements.md

Requirements Document

Introduction

This document outlines the requirements for a comprehensive car maintenance management system built with Remix, SQLite, and Prisma. The system is designed for business owners to track vehicle visits and maintenance records with a focus on Arabic language support, RTL design, and mobile-friendly responsive UI/UX.

Requirements

Requirement 1: Core Framework and Database Setup

User Story: As a business owner, I want a robust web application built on modern technologies, so that I can reliably manage my car maintenance business operations.

Acceptance Criteria

1. WHEN the application is deployed THEN the system SHALL use Remix as the web framework
2. WHEN data needs to be stored THEN the system SHALL use SQLite database with Prisma ORM
3. WHEN the application starts THEN the system SHALL initialize properly with all database connections established

Requirement 2: Arabic Language and RTL Support

User Story: As an Arabic-speaking business owner, I want the interface to support Arabic language with proper RTL layout, so that I can use the system naturally in my native language.

Acceptance Criteria

1. WHEN the application loads THEN the system SHALL display all text in Arabic with RTL text direction
2. WHEN viewing any page THEN the system SHALL render Arabic fonts correctly
3. WHEN navigating the interface THEN all UI components SHALL support RTL layout orientation
4. WHEN using forms THEN input fields SHALL align properly for RTL text entry

Requirement 3: Responsive Design and Mobile Support

User Story: As a business owner who works on different devices, I want a responsive interface that works seamlessly on desktop, tablet, and mobile, so that I can manage my business from anywhere.

Acceptance Criteria

1. WHEN accessing the application on desktop THEN the system SHALL display a full dashboard layout
2. WHEN accessing the application on tablet THEN the system SHALL adapt the layout for medium screens
3. WHEN accessing the application on mobile THEN the system SHALL provide a mobile-optimized interface
4. WHEN resizing the browser window THEN the system SHALL smoothly transition between responsive breakpoints

Requirement 4: Dashboard Navigation System

User Story: As a user, I want an intuitive navigation system with collapsible sidebar, so that I can efficiently access different sections of the application.

Acceptance Criteria

1. WHEN viewing the dashboard THEN the system SHALL display a collapsible sidebar navigation menu
2. WHEN the sidebar is collapsed THEN the system SHALL show icon-only navigation
3. WHEN on mobile devices THEN the system SHALL provide a hamburger menu for navigation
4. WHEN navigating between sections THEN the system SHALL provide smooth transitions
5. WHEN the sidebar state changes THEN the system SHALL maintain the state across page navigation

Requirement 5: User Authentication System

User Story: As a system administrator, I want a secure custom authentication system, so that I can control access to the application and protect sensitive business data.

Acceptance Criteria

1. WHEN a user attempts to sign in THEN the system SHALL authenticate using username or email with password
2. WHEN storing passwords THEN the system SHALL hash passwords securely
3. WHEN managing sessions THEN the system SHALL implement proper session management
4. WHEN authentication fails THEN the system SHALL display appropriate error messages
5. WHEN authentication succeeds THEN the system SHALL redirect to the appropriate dashboard

Requirement 6: User Management and Access Control

User Story: As a superadmin, I want to manage user accounts with different access levels, so that I can control who has access to what features in the system.

Acceptance Criteria

1. WHEN creating users THEN the system SHALL support three auth levels: 1=superadmin, 2=admin, 3=user
2. WHEN an admin views users THEN the system SHALL hide superadmin accounts from admin users
3. WHEN a superadmin views users THEN the system SHALL display all user accounts
4. WHEN managing user status THEN the system SHALL support "active" and "inactive" status
5. WHEN no admin users exist THEN the system SHALL allow access to the signup page
6. WHEN admin users exist THEN the system SHALL restrict access to the signup page

Requirement 7: Customer Management

User Story: As a business owner, I want to manage customer information, so that I can maintain records of vehicle owners and their contact details.

Acceptance Criteria

1. WHEN adding a customer THEN the system SHALL store customer contact information
2. WHEN viewing customers THEN the system SHALL display a searchable list of all customers
3. WHEN editing customer information THEN the system SHALL update records with proper validation
4. WHEN deleting a customer THEN the system SHALL handle associated vehicle relationships appropriately
5. WHEN creating a customer THEN the system SHALL validate required fields and uniqueness constraints

Requirement 7.1: Enhanced Customer Details View

User Story: As a business owner, I want a comprehensive customer details view that shows all related information in one place, so that I can quickly access customer vehicles, maintenance history, and take relevant actions.

Acceptance Criteria

1. WHEN viewing a customer's details THEN the system SHALL display a redesigned "المعلومات الأساسية" (Basic Information) section with improved layout
2. WHEN viewing customer details THEN the system SHALL show all vehicles owned by the customer
3. WHEN clicking on a vehicle in the customer details THEN the system SHALL navigate to the vehicles page filtered by that specific vehicle's plate number
4. WHEN viewing customer details THEN the system SHALL provide a "Show All Vehicles" button that opens the vehicles page filtered by the customer
5. WHEN viewing customer details THEN the system SHALL display the latest 3 maintenance visits for the customer
6. WHEN viewing customer details THEN the system SHALL provide a button to view all maintenance visits filtered by the customer
7. WHEN no maintenance visits exist THEN the system SHALL display an appropriate message encouraging the first visit
8. WHEN viewing vehicle information THEN the system SHALL show key details like plate number, manufacturer, model, and year
9. WHEN viewing maintenance visit information THEN the system SHALL show visit date, maintenance type, cost, and payment status

Requirement 8: Vehicle Management

User Story: As a business owner, I want to manage detailed vehicle information, so that I can track each vehicle's specifications and maintenance history.

Acceptance Criteria

1. WHEN adding a vehicle THEN the system SHALL store plate number, body type, manufacturer, model, year, transmission, fuel type, and use type
2. WHEN entering vehicle details THEN the system SHALL provide dropdown lists for body type, transmission, and fuel type options
3. WHEN saving a vehicle THEN the system SHALL ensure plate number uniqueness
4. WHEN linking vehicles THEN the system SHALL associate each vehicle with a customer owner
5. WHEN viewing vehicles THEN the system SHALL display last visit date and suggested next visit date
6. WHEN editing vehicle information THEN the system SHALL update records with proper validation

Requirement 9: Maintenance Visit Management

User Story: As a service technician, I want to record maintenance visits with detailed information, so that I can track what work was performed and when.

Acceptance Criteria

1. WHEN creating a maintenance visit THEN the system SHALL link the visit to a specific vehicle and customer
2. WHEN recording visit details THEN the system SHALL store maintenance type, description, cost, and kilometers
3. WHEN completing a visit THEN the system SHALL update the vehicle's last visit date to the current date
4. WHEN setting next visit THEN the system SHALL calculate suggested next visit date based on selected delay period
5. WHEN selecting visit delay THEN the system SHALL provide options for 1, 2, 3, and 4 months
6. WHEN saving a visit THEN the system SHALL generate corresponding income records

Requirement 10: Financial Management

User Story: As a business owner, I want to track expenses and income, so that I can monitor the financial performance of my maintenance business.

Acceptance Criteria

1. WHEN recording expenses THEN the system SHALL store expense details with proper categorization
2. WHEN a maintenance visit is completed THEN the system SHALL automatically generate income records
3. WHEN viewing financial data THEN the system SHALL provide summaries of income and expenses
4. WHEN managing financial records THEN the system SHALL support full CRUD operations
5. WHEN calculating totals THEN the system SHALL provide accurate financial reporting

Requirement 11: Data Validation and Error Handling

User Story: As a user, I want proper validation and clear error messages, so that I can understand and correct any input errors quickly.

Acceptance Criteria

1. WHEN submitting forms THEN the system SHALL validate all required fields
2. WHEN validation fails THEN the system SHALL display clear, localized error messages
3. WHEN database operations fail THEN the system SHALL handle errors gracefully
4. WHEN unique constraints are violated THEN the system SHALL provide specific error feedback
5. WHEN network errors occur THEN the system SHALL provide appropriate user feedback

Requirement 12: Database Seeding and Initial Setup

User Story: As a system administrator, I want the system to initialize with essential data, so that I can start using the application immediately after deployment.

Acceptance Criteria

1. WHEN the database is first created THEN the system SHALL seed one superadmin account
2. WHEN seeding data THEN the system SHALL create essential system configuration data
3. WHEN running seed scripts THEN the system SHALL handle existing data appropriately
4. WHEN initializing THEN the system SHALL set up proper database relationships and constraints