2025-09-11 14:22:27 +03:00

9.9 KiB

Raw Blame History

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

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

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

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

/* 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.

Dashboard Layout Structure

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]

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

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

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

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

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

9.9 KiB Raw Blame History