> For the complete documentation index, see [llms.txt](https://docs.xenoraa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xenoraa.com/local-development-setup.md). # Local Development Setup ## Xenoraa Developer Onboarding & Environment Setup Guide Welcome to the **Xenoraa** development team! Xenoraa is a multi-tenant SaaS CRM/ERP platform designed to streamline business operations, financial management, e-commerce, and point-of-sale (POS) workflows. It is built using a modern, high-performance stack comprising **Laravel 11 (PHP 8.3)**, **PostgreSQL 16**, **Redis**, and a clean front-end architecture using **Blade** and **vanilla JS** with custom design systems. This document provides a comprehensive, step-by-step guide to setting up your local development environment, understanding our git workflows, and getting ready to contribute to Xenoraa. *** ### 1. Required Local Development Tools Before checking out the codebase, ensure your local machine is equipped with the following software packages. We support macOS, Linux, and Windows (via WSL2). #### Core Runtime Environment * **PHP 8.3.x**: Must be compiled with the following essential extensions: * `bcmath`, `ctype`, `curl`, `fileinfo`, `gd`, `intl`, `mbstring`, `openssl`, `pdo_pgsql`, `pgsql`, `redis`, `tokenizer`, `xml`, `xmlreader`, `xmlwriter`, `zip`. * **Composer 2.7+**: The dependency manager for PHP. * **Node.js 18.x / 20.x & NPM**: Required for compiling assets via Vite. * **PostgreSQL 16**: The active database engine for the platform. * **Redis 7.x**: Used as the cache, session, and queue driver. #### Recommended Tooling & Utilities * **Web Server**: We recommend **Nginx** or **Laravel Valet** (macOS) / **Laravel Herd** (macOS/Windows) for local hosting. * **Database Client**: TablePlus, pgAdmin, or DBeaver. * **IDE**: Visual Studio Code (with Laravel Extension Pack) or PHPStorm. * **Git**: Git command-line interface (CLI). *** ### 2. Git Workflow: Pulling, Branching, and Committing Xenoraa employs a strict branch management strategy to maintain production stability while allowing rapid development iterations. #### Repository Information * **Repository URL**: `https://github.com/goesscay/xenoraa.git` * **Primary Branches**: * `main`: Represents the production-ready state. Code here is automatically deployed to `xenoraa.com`. * `develop`: The integration branch for active development. Code here is automatically deployed to `staging.xenoraa.com`. #### Workflow Step-by-Step **Step 2.1: Clone the Repository** Clone the repository to your local development directory: ```bash git clone https://github.com/goesscay/xenoraa.git cd xenoraa ``` **Step 2.2: Branching Strategy** Never commit directly to `main` or `develop`. Always create a feature or bugfix branch off of `develop`: ```bash # Ensure you are on develop and have the latest changes git checkout develop git pull origin develop # Create your feature branch git checkout -b feat/your-feature-name # Or for bug fixes git checkout -b fix/your-bugfix-name ``` **Step 2.3: Commit Guidelines** Write clean, descriptive commit messages following the Conventional Commits specification: * `feat: add delete contact tool` * `fix: resolve sentry button overlap` * `docs: update developer setup guide` **Step 2.4: Code Quality & Syntax Check** Before committing, always perform a PHP syntax check on your modified files to prevent broken builds: ```bash php -l app/Http/Controllers/CrmModuleController.php ``` **Step 2.5: Push and Create a Pull Request (PR)** Push your local branch to GitHub and open a PR targeting the `develop` branch: ```bash git push origin feat/your-feature-name ``` Once your PR is reviewed and merged into `develop`, the **GitHub Actions Staging Deploy** workflow will automatically deploy your changes to the staging server. *** ### 3. Environment Configuration (`.env`) Xenoraa requires a configured `.env` file to establish connections to your local database, Redis cache, and third-party services. #### Local Environment Setup Copy the example environment file and generate your application key: ```bash cp .env.example .env php artisan key:generate ``` #### Essential Local Configuration Settings Modify your `.env` file with the following configurations adjusted for your local environment: | Key | Recommended Local Value | Description | | ------------------ | ----------------------- | ----------------------------------------------------------- | | `APP_NAME` | `"Xenoraa Local"` | The local name of your application instance. | | `APP_ENV` | `local` | Set to `local` to enable debug screens and verbose logging. | | `APP_DEBUG` | `true` | Enables detailed error pages (Laravel Ignition). | | `APP_URL` | `http://xenoraa.test` | Your local web server virtual host domain. | | `DB_CONNECTION` | `pgsql` | Configures PostgreSQL as the primary database driver. | | `DB_HOST` | `127.0.0.1` | Your local PostgreSQL host. | | `DB_PORT` | `5432` | Default PostgreSQL port. | | `DB_DATABASE` | `xenoraa_local` | Your local database name. | | `DB_USERNAME` | `postgres` | Your local PostgreSQL username. | | `DB_PASSWORD` | `your_local_password` | Your local PostgreSQL password. | | `CACHE_DRIVER` | `redis` | Uses Redis for high-performance caching. | | `SESSION_DRIVER` | `redis` | Uses Redis for fast session management. | | `QUEUE_CONNECTION` | `redis` | Configures Redis queue driver for background jobs. | | `REDIS_HOST` | `127.0.0.1` | Your local Redis host. | | `REDIS_PORT` | `6379` | Default Redis port. | *** ### 4. End-to-End Installation & Database Setup Follow these commands in sequence to initialize your local Xenoraa installation: #### Step 4.1: Install Composer Dependencies Install PHP dependencies required by the framework: ```bash composer install ``` #### Step 4.2: Install NPM Dependencies & Build Assets Compile the front-end stylesheets and JavaScript assets: ```bash npm install npm run dev ``` #### Step 4.3: Initialize the PostgreSQL Database Log into your PostgreSQL CLI or GUI client and create the database: ```sql CREATE DATABASE xenoraa_local; ``` #### Step 4.4: Run Database Migrations and Seeders Xenoraa includes a comprehensive set of migrations to construct the database schema: ```bash php artisan migrate --seed ``` #### Step 4.5: Start Background Queue Workers Xenoraa utilizes background queues for email campaigns, webhooks, and asynchronous AI tasks. Run a queue worker locally: ```bash php artisan queue:work redis --queue=default ``` *** ### 5. Coding Standards & Architectural Guidelines To maintain code consistency across the engineering team, adhere to the following architectural patterns established in Xenoraa: #### The Design System Xenoraa uses a custom-tailored CSS framework loaded for `admin.crm2*`, `admin.ecommerce*`, `admin.accounts*`, and `admin.pos*` routes. Always use the `crm2-*` utility classes for views: * **Page Container**: `crm2-page` * **Header & Titles**: `crm2-header`, `crm2-title` * **KPI Widgets**: `crm2-kpi-grid`, `crm2-kpi-card` * **Content Cards**: `crm2-card` * **Tables & Badges**: `crm2-table`, `crm2-badge` * **Buttons & Inputs**: `crm2-btn`, `crm2-btn-primary`, `crm2-input` #### PostgreSQL SQL Best Practices Since our migration to PostgreSQL, follow these database-specific rules: * **Case Insensitivity**: Use `::text ILIKE` instead of `LIKE` for string matching. * **String Aggregation**: Use `STRING_AGG(col, ',')` instead of `GROUP_CONCAT`. * **Date Functions**: Use `EXTRACT(MONTH FROM col)` for date extractions. * **Tenant Scoping**: Ensure all application tables are scoped by `user_id` to maintain multi-tenant isolation. #### Controller Structure * **`CrmModuleController.php`**: Handles all core CRM, Inventory, POS, and Settings logic. * **`AccountsController.php`**: Dedicated to financial reports and general ledger operations. * **`PosController.php`**: Handles point-of-sale sessions and orders. * **`XenaController.php`**: Manages the conversational Xena AI interface and tool routing. *** ### 6. Sentry and Logging For production error tracking, Xenoraa integrates with Sentry. Locally, error logs are written to `storage/logs/laravel.log`. * To test your local Sentry integration, configure `SENTRY_LARAVEL_DSN` in your `.env` and run: ```bash php artisan sentry:test ``` * Ensure that any new controllers log major user actions using the `logAction()` service to populate the cross-session context logs for Xena AI. *** With your environment configured and tools running, you are ready to build the future of Xenoraa! For any architectural questions, consult the `/var/www/xenoraa/AGENTS.md` file on the staging/production servers or reach out to the lead system architect. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xenoraa.com/local-development-setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.