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

# Design Document

## Overview

The car maintenance management system is designed as a modern, responsive web application built with Remix, featuring Arabic language support with RTL layout, role-based authentication, and comprehensive business management capabilities. The system follows a modular architecture with clear separation of concerns, utilizing Prisma for database operations and Tailwind CSS for styling.

## Architecture

### High-Level Architecture

```mermaid
graph TB
    A[Client Browser] --> B[Remix Frontend]
    B --> C[Remix Backend/API Routes]
    C --> D[Prisma ORM]
    D --> E[SQLite Database]
    
    F[Authentication Middleware] --> C
    G[Session Management] --> C
    H[Route Protection] --> B
    
    subgraph "Frontend Components"
        I[Dashboard Layout]
        J[RTL Components]
        K[Responsive Navigation]
        L[Form Components]
    end
    
    B --> I
    B --> J
    B --> K
    B --> L
```

### Technology Stack

- **Frontend Framework**: Remix with React 18
- **Backend**: Remix server-side rendering and API routes
- **Database**: SQLite with Prisma ORM
- **Styling**: Tailwind CSS with RTL support
- **Authentication**: Custom session-based authentication
- **TypeScript**: Full type safety throughout the application

## Components and Interfaces

### 1. Authentication System

#### Session Management
- Custom session-based authentication using Remix sessions
- Secure cookie storage with httpOnly and secure flags
- Session expiration and renewal mechanisms
- CSRF protection for form submissions

#### User Authentication Flow
```mermaid
sequenceDiagram
    participant U as User
    participant A as Auth Route
    participant S as Session Store
    participant D as Database
    
    U->>A: Submit login credentials
    A->>D: Validate user credentials
    D-->>A: Return user data
    A->>S: Create session
    S-->>A: Return session cookie
    A-->>U: Redirect with session cookie
```

#### Route Protection Middleware
- Higher-order component for protecting routes based on auth levels
- Automatic redirection to login for unauthenticated users
- Role-based access control for different user types

### 2. Database Schema Design

#### Core Entities and Relationships

```mermaid
erDiagram
    User {
        int id PK
        string name
        string username UK
        string email UK
        string password
        enum status
        int authLevel
        datetime createdDate
        datetime editDate
    }
    
    Customer {
        int id PK
        string name
        string phone
        string email
        string address
        datetime createdDate
        datetime updateDate
    }
    
    Vehicle {
        int id PK
        string plateNumber UK
        string bodyType
        string manufacturer
        string model
        string trim
        int year
        string transmission
        string fuel
        int cylinders
        decimal engineDisplacement
        enum useType
        int ownerId FK
        datetime lastVisitDate
        datetime suggestedNextVisitDate
        datetime createdDate
        datetime updateDate
    }
    
    MaintenanceVisit {
        int id PK
        int vehicleId FK
        int customerId FK
        string maintenanceType
        string description
        decimal cost
        string paymentStatus
        int kilometers
        datetime visitDate
        datetime createdDate
        datetime updateDate
    }
    
    Expense {
        int id PK
        string description
        string category
        decimal amount
        datetime expenseDate
        datetime createdDate
        datetime updateDate
    }
    
    Income {
        int id PK
        int maintenanceVisitId FK
        decimal amount
        datetime incomeDate
        datetime createdDate
        datetime updateDate
    }
    
    Customer ||--o{ Vehicle : owns
    Vehicle ||--o{ MaintenanceVisit : has
    Customer ||--o{ MaintenanceVisit : books
    MaintenanceVisit ||--|| Income : generates
```

### 3. UI/UX Design System

#### RTL Layout Implementation
- CSS logical properties for directional layouts
- Arabic font integration (Noto Sans Arabic, Cairo)
- Tailwind CSS RTL plugin configuration
- Component-level RTL support with `dir="rtl"` attribute

#### Responsive Design Breakpoints
```css
/* Mobile First Approach */
sm: 640px   /* Small devices */
md: 768px   /* Medium devices */
lg: 1024px  /* Large devices */
xl: 1280px  /* Extra large devices */
2xl: 1536px /* 2X Extra large devices */
```

#### Color Scheme and Theming
- Primary colors: Blue gradient (#3B82F6 to #1E40AF)
- Secondary colors: Gray scale for neutral elements
- Success: Green (#10B981)
- Warning: Amber (#F59E0B)
- Error: Red (#EF4444)
- Dark mode support for future enhancement
- Design : use constant design for all pages, forms and buttons.

### 4. Navigation and Layout System

#### Dashboard Layout Structure
```mermaid
graph LR
    A[App Shell] --> B[Sidebar Navigation]
    A --> C[Main Content Area]
    A --> D[Header Bar]
    
    B --> E[Logo Area]
    B --> F[Navigation Menu]
    B --> G[User Profile]
    
    C --> H[Page Content]
    C --> I[Breadcrumbs]
    
    D --> J[Mobile Menu Toggle]
    D --> K[User Actions]
```

#### Sidebar Navigation Features
- Collapsible sidebar with full/icon-only modes
- Mobile-responsive hamburger menu
- Active state indicators
- Smooth animations and transitions
- Persistent state across page navigation

### 5. Form and Data Management

#### Form Validation Strategy
- Client-side validation using HTML5 and custom validators
- Server-side validation with Zod schemas
- Real-time validation feedback
- Internationalized error messages in Arabic

#### Data Table Components
- Sortable columns with Arabic text support
- Pagination with RTL navigation
- Search and filtering capabilities
- Responsive table design with horizontal scrolling
- Bulk actions for data management

## Data Models

### User Model
```typescript
interface User {
  id: number;
  name: string;
  username: string;
  email: string;
  password: string; // hashed
  status: 'active' | 'inactive';
  authLevel: 1 | 2 | 3; // 1=superadmin, 2=admin, 3=user
  createdDate: Date;
  editDate: Date;
}
```

### Vehicle Model
```typescript
interface Vehicle {
  id: number;
  plateNumber: string;
  bodyType: string;
  manufacturer: string;
  model: string;
  trim?: string;
  year: number;
  transmission: 'Automatic' | 'Manual';
  fuel: 'Gasoline' | 'Diesel' | 'Hybrid' | 'Mild Hybrid' | 'Electric';
  cylinders?: number;
  engineDisplacement?: number;
  useType: 'personal' | 'taxi' | 'apps' | 'loading' | 'travel';
  ownerId: number;
  lastVisitDate?: Date;
  suggestedNextVisitDate?: Date;
  createdDate: Date;
  updateDate: Date;
}
```

### Maintenance Visit Model
```typescript
interface MaintenanceVisit {
  id: number;
  vehicleId: number;
  customerId: number;
  maintenanceType: string;
  description: string;
  cost: number;
  paymentStatus: string;
  kilometers: number;
  visitDate: Date;
  nextVisitDelay: 1 | 2 | 3 | 4; // months
  createdDate: Date;
  updateDate: Date;
}
```

## Error Handling

### Client-Side Error Handling
- Global error boundary for React components
- Form validation error display
- Network error handling with retry mechanisms
- User-friendly error messages in Arabic

### Server-Side Error Handling
- Centralized error handling middleware
- Database constraint violation handling
- Authentication and authorization error responses
- Logging and monitoring for production debugging

### Error Response Format
```typescript
interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: any;
  };
}
```

## Testing Strategy

### Unit Testing
- Component testing with React Testing Library
- Business logic testing for utility functions
- Database model testing with Prisma
- Authentication flow testing

### Integration Testing
- API route testing with Remix testing utilities
- Database integration testing
- Authentication middleware testing
- Form submission and validation testing

### End-to-End Testing
- User journey testing for critical paths
- Cross-browser compatibility testing
- Mobile responsiveness testing
- RTL layout verification

### Testing Tools
- Jest for unit testing
- React Testing Library for component testing
- Playwright for E2E testing
- MSW (Mock Service Worker) for API mocking

## Security Considerations

### Authentication Security
- Password hashing using bcrypt
- Secure session management
- CSRF protection
- Rate limiting for authentication attempts

### Data Protection
- Input sanitization and validation
- SQL injection prevention through Prisma
- XSS protection through proper escaping
- Secure headers configuration

### Access Control
- Role-based access control (RBAC)
- Route-level protection
- API endpoint authorization
- Data filtering based on user permissions

## Performance Optimization

### Frontend Performance
- Code splitting with Remix route-based splitting
- Image optimization and lazy loading
- CSS optimization with Tailwind purging
- Bundle size monitoring and optimization

### Backend Performance
- Database query optimization with Prisma
- Caching strategies for frequently accessed data
- Connection pooling for database connections
- Response compression and minification

### Mobile Performance
- Touch-friendly interface design
- Optimized images for different screen densities
- Reduced JavaScript bundle size for mobile
- Progressive Web App (PWA) capabilities

## Deployment and Infrastructure

### Development Environment
- Local SQLite database for development
- Hot module replacement with Vite
- TypeScript compilation and type checking
- ESLint and Prettier for code quality

### Production Deployment
- Build optimization with Remix production build
- Database migration strategy
- Environment variable management
- Health check endpoints for monitoring

### Monitoring and Logging
- Application performance monitoring
- Error tracking and reporting
- User analytics and usage metrics
- Database performance monitoring