Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Arthurr23/XHealtXperience/llms.txt

Use this file to discover all available pages before exploring further.

XHealtXperience is a multi-tenant healthcare clinic management platform built with Laravel 12 and React 18. This guide walks you through every step required to get the full stack — PHP backend, Inertia/React frontend, queue worker, and log viewer — running locally from a fresh clone.

​
Prerequisites

Before you begin, ensure the following tools are installed and available in your PATH:
ToolMinimum versionNotes
PHP8.2+Required by composer.json
Composer2.xPHP dependency manager
Node.js18+Required by Vite 7
npm9+Bundled with Node.js
SQLite3.xDefault database driver (no server needed)
MySQL8.0+Optional — swap in .env if preferred

​
Setup Steps

1
Clone the repository
2
git clone https://github.com/Arthurr23/XHealtXperience.git
cd XHealtXperience
3
Install PHP dependencies
4
Install all Composer packages, including Laravel 12, stancl/tenancy, spatie/laravel-permission, and the dev toolchain (PHPUnit, Pail, Sail, Pint).
5
composer install
6
Install JavaScript dependencies
7
Install the React 18 / Vite / Tailwind CSS frontend stack.
8
npm install
9
Copy the environment file and generate the application key
10
The .env.example file contains safe defaults for local development. Copy it and generate a unique APP_KEY:
11
cp .env.example .env
php artisan key:generate
12
Configure the database connection
13
The default driver is SQLite, which requires no running server. Open .env and confirm (or adjust) the following values:
14
# SQLite (default — no server needed)
DB_CONNECTION=sqlite
# The database file is created automatically at database/database.sqlite

# MySQL alternative — uncomment and fill in your credentials
# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=xhealthxperience
# DB_USERNAME=root
# DB_PASSWORD=
15
If you are using SQLite you can create the file manually:
16
touch database/database.sqlite
17
Run the central database migrations
18
This creates the central schema: users, tenants, domains, jobs, cache, permissions, personal access tokens, 2FA columns, and more. See Database Migrations for the full schema inventory.
19
php artisan migrate
20
Seed the central database
21
The DatabaseSeeder creates one central Super Admin role and one superadmin user account. This account logs in at the central URL (/login), not at any tenant’s subdomain.
22
php artisan db:seed
23
The seed creates a default superadmin with the email superadmin@xhealthxperience.com and the password SuperAdmin2024!. Change both before deploying to production.
24
Start all development processes
25
Use the composer run dev shorthand to launch the complete development stack in a single terminal:
26
composer run dev
27
This runs four processes concurrently (via npx concurrently):
28
ProcessCommandColorserverphp artisan serveBluequeuephp artisan queue:listen --tries=1 --timeout=0Purplelogsphp artisan pail --timeout=0Pinkvitenpm run devOrange
29
The application will be available at http://127.0.0.1:8000.
composer run dev uses npx concurrently to run php artisan serve, the queue worker, Laravel Pail (log viewer), and the Vite dev server all in one terminal with colour-coded output and --kill-others — so pressing Ctrl+C stops every process cleanly.

​
One-shot setup script

composer.json also ships a setup script that chains all bootstrap steps in one command: 
composer run setup
Internally this executes: 
composer install
# copies .env.example → .env (if .env does not already exist)
php artisan key:generate
php artisan migrate --force
npm install
npm run build
Use composer run setup for CI pre-flight checks or when onboarding a new team member who wants to get to a built state quickly. For day-to-day development, prefer composer run dev (which starts the Vite dev server instead of a production build).

​
Environment variables reference

All variables below come directly from .env.example. Copy them into your .env and adjust as needed.
​
APP_NAME
string
default:"Laravel"
Human-readable name of the application. Surfaced in emails (MAIL_FROM_NAME) and the Vite build (VITE_APP_NAME). Change to something like "Clínica".
​
APP_URL
string
default:"http://localhost"
The root URL of the central (non-tenant) application. The tenancy package also uses this to determine central domains. Must match the host used by php artisan serve.
​
DB_CONNECTION
string
default:"sqlite"
Database driver. Accepted values: sqlite, mysql, pgsql. Defaults to sqlite for zero-config local development.
​
SESSION_DRIVER
string
default:"database"
Where PHP sessions are stored. The .env.example default is database (stored in the sessions table). In tests, phpunit.xml overrides this to array.
​
QUEUE_CONNECTION
string
default:"database"
Queue backend. database uses the jobs table created by migrations. Change to redis or sync as needed.
​
MAIL_MAILER
string
default:"log"
Mail transport used in local development. log writes all outgoing mail to the Laravel log — no SMTP server is needed. Change to smtp for real delivery.
​
MAIL_HOST
string
default:"127.0.0.1"
SMTP host. Only relevant when MAIL_MAILER is smtp.
​
MAIL_PORT
integer
default:"2525"
SMTP port. The default 2525 is compatible with local tools like Mailpit/Mailtrap.
​
MAIL_FROM_ADDRESS
string
default:"hello@example.com"
The From: address on all outgoing mail. Set to a real clinic address in production.

​
Queue worker requirement

Several features dispatch queued jobs. The composer run dev script starts a queue worker automatically, but if you run processes separately you must keep this command alive in its own terminal: 
php artisan queue:listen --tries=1 --timeout=0
  • --tries=1 means a failing job is marked as failed immediately rather than retried, which keeps local logs clean.
  • --timeout=0 disables the per-job time limit, which prevents long-running tenant operations from being killed mid-flight.
If the queue worker is not running, queued mail and background jobs will pile up in the jobs table and never be processed.

​
GitHub Codespaces support

The repository ships a .env_CODESPACES file with pre-configured values for running inside GitHub Codespaces. It sets APP_URL and VITE_URL to the dynamic Codespace hostname, configures SESSION_DRIVER=cookie with SESSION_SECURE_COOKIE=true and SESSION_SAME_SITE=none (required for cross-origin cookie auth), and adds SANCTUM_STATEFUL_DOMAINS and TRUSTED_PROXIES="*". To use it in a Codespace, copy it over the standard env file: cp .env_CODESPACES .env.

Build docs developers (and LLMs) love

Get started for freeTalk to us