uup
This commit is contained in:
399
.kiro/specs/car-maintenance-system/design.md
Normal file
399
.kiro/specs/car-maintenance-system/design.md
Normal file
@@ -0,0 +1,399 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user