Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• composer.json
• resources/views/layouts/app.blade.php
• resources/views/dashboard/templates.blade.php
• README.md
• tests/Unit/Services/TemplateServicePropertyTest.php
• app/Services/TemplateService.php
• resources/views/dashboard/index.blade.php

This document outlines the process for setting up and running the qashierwise-be application in a local development environment. The project is a Laravel application that utilizes Vite for frontend asset bundling, with a fallback to CDN-hosted assets for specific local development scenarios.

The setup is managed through a series of Composer and NPM scripts, designed to streamline the installation of dependencies, database migration, and the launching of necessary development services.

Prerequisites

Before starting, ensure your development environment meets the following requirements:

• PHP: ^8.2
• Node.js & NPM: Required for frontend dependency management and asset building. The specific version is not defined, but a recent LTS version is recommended.

Sources: composer.json:10

Dependencies

The project relies on Composer for PHP packages and NPM for JavaScript packages.

Backend (PHP)

Key backend dependencies are managed via composer.json.

Package	Version	Description
laravel/framework	^12.0	The core Laravel framework.
laravel/sanctum	^4.2	API authentication system.
pusher/pusher-php-server	^7.2	PHP server for Pusher, used for real-time event broadcasting.
netflie/whatsapp-cloud-api	^2.2	A library for interacting with the WhatsApp Cloud API.
polar-sh/sdk	^0.7.0	Polar.sh SDK, likely for handling subscriptions or payments.
phpunit/phpunit	^11.5.3	The testing framework for unit and feature tests.
giorgiosironi/eris	^1.0	A library for property-based testing, used in unit tests.
laravel/sail	^1.41	A Docker-based development environment for Laravel (though not the primary setup method described).

Sources: composer.json:9-29, tests/Unit/Services/TemplateServicePropertyTest.php:9

Frontend (JavaScript)

Frontend dependencies are managed via NPM, although package.json is not provided. The application uses Vite for asset bundling. Key libraries are loaded directly via CDN in the main layout file.

Library	Version	Usage
Tailwind CSS	N/A	Used for styling. Loaded via CDN as a fallback in local development.
Alpine.js	3.x.x	A minimal JavaScript framework for component-like behavior in HTML.
Pusher JS	8.2.0	Client-side library for real-time WebSocket communication.
Laravel Echo	1.15.3	Simplifies subscribing to channels and listening for Pusher events.
ApexCharts	3.45.1	A modern charting library used for rendering graphs in the dashboard.
Font Awesome	6.4.0	Provides icons used throughout the UI.

Sources: resources/views/layouts/app.blade.php:24-60, resources/views/dashboard/templates.blade.php:1248

Installation and Setup

The project includes a convenient setup script in composer.json to automate the initial installation process.

To set up the project, run the following command from the root directory:

composer run setup

This command executes the following sequence of tasks:

1. composer install: Installs all required PHP dependencies.
2. @php -r "file_exists('.env') || copy('.env.example', '.env');": Creates a .env file from the example if it doesn't exist.
3. @php artisan key:generate: Generates a unique application key.
4. @php artisan migrate --force: Runs the database migrations.
5. npm install: Installs all required JavaScript dependencies.
6. npm run build: Compiles and bundles frontend assets using Vite.

The following diagram illustrates the setup flow.

Running the Development Environment

To start all necessary services for local development, use the dev script defined in composer.json.

composer run dev

This command uses concurrently to run multiple processes in parallel, each with a designated color-coded output for readability.

The following diagram shows the processes launched by the dev script.

Sources: composer.json:57-60

Services Breakdown

Command	Name in Output	Description
php artisan serve	server	Starts the built-in PHP development server, typically at http://127.0.0.1:8000.
php artisan queue:listen --tries=1	queue	Starts a queue worker to process background jobs. The --tries=1 flag means it will attempt a job once.
php artisan pail --timeout=0	logs	Tails the application logs in real-time. --timeout=0 prevents the command from timing out.
npm run dev	vite	Starts the Vite development server for hot-module replacement (HMR) of frontend assets.

Sources: composer.json:57-60

Frontend Asset Handling

The application has a dynamic approach to loading frontend assets in a local environment.

Vite vs. CDN Fallback

The main layout file, app.blade.php, contains logic to determine how to load CSS and JS assets.

1. Vite Build: If a build/manifest.json file exists (created by npm run build), the application uses the @vite Blade directive to load the compiled assets.
2. CDN Fallback: If the environment is local AND build/manifest.json does not exist, the application falls back to loading Tailwind CSS directly from a CDN. This allows developers to work on the frontend without needing to run npm run build continuously.

The following diagram illustrates this asset loading flow.

Frontend Interactivity

The frontend uses Alpine.js for reactive UI components directly within the Blade templates. This is evident in files like resources/views/dashboard/templates.blade.php, where x-data defines component state and x-show, x-for, and @click handle dynamic behavior.

<!-- Example from templates.blade.php -->
<div x-data="templatesApp()" class="min-h-screen flex bg-[hsl(var(--muted)/0.4)]">
    <!-- ... -->
    <button @click="openCreateModal()" class="btn btn-primary btn-md flex-1 sm:flex-none">
        <i class="fas fa-plus sm:mr-2"></i>
        <span class="hidden sm:inline">Create Template</span>
    </button>
    <!-- ... -->
    <template x-for="template in filteredTemplates" :key="template.id">
        <!-- Template card rendering -->
    </template>
</div>

Sources: resources/views/dashboard/templates.blade.php:49-155

Database

The project is configured to use a SQLite database for local development. The post-create-project-cmd script in composer.json automatically creates an empty database/database.sqlite file if one does not exist, and then runs migrations. This ensures a database is ready immediately after project creation.

Database migrations are run as part of the setup script.

Sources: composer.json:79-83

Testing

The project is equipped with a testing suite powered by PHPUnit. Tests can be executed using a dedicated Composer script.

composer run test

This command performs two actions:

1. @php artisan config:clear --ansi: Clears the configuration cache to ensure tests run with the correct environment settings.
2. @php artisan test: Executes the PHPUnit test suite.

The testing framework includes support for property-based testing using giorgiosironi/eris, as seen in TemplateServicePropertyTest.php, which validates the business logic of the TemplateService against a wide range of generated inputs.

Sources: composer.json:61-64, tests/Unit/Services/TemplateServicePropertyTest.php