Documentation for car-hub.xyz

Table of Contents

• Introduction
• Installation
• Configuration
• Features
• Database Structure
• Factories and Seeders
• Routes
• Controllers
• Policies
• Testing
• Accessibility
• Styling and Frontend
• Third-Party Integrations
• Deployment (with GitHub Actions)
• License

Introduction

car-hub.xyz is a Laravel-based web application designed for managing cars, their features, and user interactions such as watchlists and authentication. It leverages Laravel's built-in features like Eloquent ORM, Blade templates, and Sanctum for API authentication.

Installation

• Clone the repository
• Install dependencies:
  • Run composer install
  • Run npm install
• Copy .env.example to .env
• Generate the application key: php artisan key:generate
• Configure your database in .env and run migrations: php artisan migrate --seed
• Build frontend assets: npm run dev
• Start the development server: php artisan serve

Configuration

• Environment Variables: Configure the .env file for database, mail, and third-party services.
• Queue Configuration: Update queue.php for queue drivers like Redis or database.
• Authentication: Uses session-based login.

Features

• Car Management:
  • Add, edit, delete, and view cars.
  • Manage car features and images.
• User Authentication:
  • Login, signup, and password reset.
  • OAuth login via Google and Facebook.
• Watchlist: Add or remove cars from the user's watchlist.
• Profile Management: Update user profile and password.
• Search and Filters: Search cars by maker, model, city, and other attributes.
• Admin Panel: Manage users and cars via Filament Admin Panel.

Database Structure

Domain Tables:

• users: Stores user information.
• cars: Stores car details.
• car_features: Stores features for each car.
• car_images: Stores image paths for cars.
• favorite_cars: Stores user watchlist data.
• makers: Car manufacturers.
• models: Car models, linked to makers.
• car_types: Types of cars (e.g., sedan, SUV).
• fuel_types: Types of fuel (e.g., petrol, diesel).
• cities: Cities, linked to states.
• states: States.

Factories and Seeders

Factories:

• CarFactory: Generates random cars.
• CarFeatureFactory: Generates random car features.
• CarImageFactory: Generates random car images.
• UserFactory: Creates test users.

Seeders:

• DatabaseSeeder: Seeds initial data for makers, car types, and more.

Routes

Public Routes:

• /: Homepage.
• /car/search: Search cars.
• /signup: User signup.
• /login: User login.

Authenticated Routes:

• /car: Manage cars.
• /watchlist: View watchlist.
• /profile: Manage profile.

Routes are defined in:

• web.php
• auth.php

Controllers

Key Controllers:

• CarController: Handles car CRUD operations and features management.
• SignupController: Manages user registration.
• WatchlistController: Handles adding/removing cars to/from the watchlist.
• ProfileController: Manages user profile updates and password changes.

Policies

CarPolicy: Authorizes actions like creating, updating, and deleting cars.

Testing

Feature Tests:

• CarTest: Tests car-related functionality.
• AuthTest: Tests authentication.
• SignupTest: Tests user signup.
• WatchlistTest: Tests watchlist access and actions.
• ProfileTest: Tests profile page access.
• PasswordResetTest: Tests password reset flow.
• HomeTest: Tests homepage car display.

Run tests with: php artisan test

Accessibility

• Semantic HTML is used throughout the app for better screen reader support.
• Color contrast and font sizes are chosen for readability.
• Navigation is keyboard accessible.
• Forms use proper labels and error messages.
• Responsive design ensures usability on all devices.

Styling and Frontend

• CSS: Located in app.css.
• JavaScript: Located in app.js.

Third-Party Integrations

• Socialite: Google and Facebook OAuth login. Configured in services.php.
• Sanctum: API authentication. Configured in sanctum.php.
• Filament Admin Panel: Admin panel for managing resources. Configured in AdminPanelProvider.php.

Deployment (with GitHub Actions)

The application uses GitHub Actions for Continuous Integration and Deployment (CI/CD). The deployment process is automated and triggered on the creation of a new release.

GitHub Actions Workflow

The deployment workflow is defined in deploy.yml.

How It Works

• Trigger: The workflow is triggered when a new release is created in the GitHub repository.
• Build Steps:
  • The code is checked out.
  • PHP and Node.js environments are set up.
  • Dependencies are installed using Composer and npm.
  • Laravel-specific tasks like generating the encryption key, creating a storage link, and running migrations are executed.
  • Frontend assets are built.
  • Tests are run to ensure the application is functioning correctly.
• Deployment: The app is deployed to the server using the appleboy/ssh-action. The server pulls the latest release tag, installs dependencies, builds assets, and optimizes the Laravel app.

License

This application is open-sourced software licensed under the MIT license.