# SuiteX
SuiteX is currently a project management software. It will eventually grow out of this to provide more features.

## Additional Repos
[NetSuite files are stored and managed in a separate repo](https://github.com/SuiteDynamics/SuiteX_SDF). 

## 🤖 AI Governance & Maintenance
**⚠️ CRITICAL:** This project supports both Cursor and Antigravity.
If you update an AI Rule or Agent, you **MUST** update it in both locations to prevent logic drift.

### Mapping Table
| Logic | Cursor Location (Master) | Antigravity Location (Mirror) |
| :--- | :--- | :--- |
| **Testing Standards** | `.cursor/rules/400-testing-standards.mdc` | `.agent/rules/testing.md` |
| **Performance** | `.cursor/rules/500-performance.mdc` | `.agent/rules/performance.md` |
| **Test Runner** | `.cursor/rules/test-runner.md` | `.agent/workflows/test-runner.md` |
| **PR Reviewer** | `.cursor/rules/pr-reviewer.md` | `.agent/workflows/pr-reviewer.md` |

**Rule of Thumb:** Make the change in Cursor first (test it), then port the logic to the Antigravity workflow.

## Development Environment
This project requires a local domain for development. For example, `https://suitex.test`. The project relies on sub-domains which means working in `localhost` and `127.0.0.1` will not work properly.

Depending on your operating system there are different recommended setups.
- MacOS: it is recommended to utilize [Laravel Valet](https://laravel.com/docs/10.x/valet).
- Windows:
    - Use what you are comfortable with, otherwise...
        - Utilize [Docker to provide a local development environment](https://ianclemence.medium.com/setting-up-laravel-project-using-docker-step-by-step-guide-7c5720fbc2c8).
        - You may try setting up [Laravel Valet](https://laravel.com/docs/10.x/valet), but this has been difficult on Windows.

### PHP and Laravel
This project currently utilizes PHP 8.3 and Laravel 10.

## Design Principles
If you are unfamiliar with Laravel, please review parts of the [Laravel 8 From Scratch](https://laracasts.com/series/laravel-8-from-scratch) series on Laracasts. You may use our company account to access these videos, and Alexander may have recommendations for further reading/review.
```
https://laracasts.com
user: quinn@suitedynamics.io
pass: jTUNzZN8CMKMxuE
```
This project does not use the default Laravel file structure. All application and domain data is located within the `src` folder. Read the following sections to understand various design principles and workflow expectations.

### Workflow
- Get latest from Github
- Create a new branch for the feature you are working on
- Build out the new feature.
    - While developing your feature, be sure to merge the main branch into your own once a day.
- Before committing code to Github
    - Format your code to PSR-2 format
    - Run a static type checker (PHP is loosely typed so we use this to reduce future bugs)
    - Write unit tests

### Domain Driven Design (DDD)
This project uses Domain Driven Design (DDD) to organize code. This allows us to keep similar code grouped in a logical way. We have a company account for [Laravel Beyond CRUD](https://spatie.be/courses/laravel-beyond-crud). Be sure to review this series as needed while working on the project.
```
User: quinn@suitedynamics.io
Pass: cha77erBoxing
```

### Unit Testing
Unit testing is required with each new feature developed. We utilize [Laravel Pest](https://pestphp.com/) for writing our tests. Be sure to [review the video series and documentation for how to use Laravel Pest](https://spatie.be/courses/testing-laravel-with-pest).
```
User: quinn@suitedynamics.io
Pass: cha77erBoxing
```
Be sure to run Larastan (see below) prior to writing unit tests. This will save time when writing tests as it won't be necessary to write tests to ensure proper types.

### PSR-2 Code Formatting
Laravel utilizes PSR-2 code format. All code should be run through a code formatter to adhere to this code style. Depending on your code editor, here are a few extensions that may be useful:
- [Sublime Text 4](https://packagecontrol.io/packages/phpfmt)
- [Visual Studio](https://marketplace.visualstudio.com/items?itemName=Sophisticode.php-formatter)
- [PHP Storm](https://laraveldaily.com/post/how-to-configure-phpstorm-for-psr-2)

If using Sublime Text 4 with the phpfmt library, be sure to update the package settings to the following: 
```
{
    "psr2": true,
    "php_bin": "/opt/homebrew/bin/php" // Only if using Homebrew to install PHP on OSX
}
```

### Static Type Checking
PHP is a loosely typed language which can introduce a lot of unexpected bugs in production releases. It is required to use [Larastan](https://github.com/larastan/larastan) to do static code analysis prior to writing unit tests. Larastan is an extension of PHPStan built to work with Laravel.

Create a file called "phpstan.neon" in the project root directory, and save it with these default contents:
```
includes:
    - vendor/larastan/larastan/extension.neon

parameters:

    paths:
        - src/
        # Update above line to point at code paths currently being written.
        # Including the entire 'src' directory will include everyone else's code and
        # can pollute the error logs until existing code has been updated to meet requirements.

    # Level 9 is the highest level
    level: 5
```
Once the above file is setup run `./vendor/bin/phpstan analyse` from the project root to analyse code.

## Migrations
**Create a core migration:** `php artisan make:migration create_formfields_table`

**Create a tenant migration:** `php artisan make:migration create_formfields_table --path=database/migrations/tenants`

**Run core migration:** `php artisan migrate`

**Run a specific tenant migration:** `php artisan tenant:migrate {id}`

**Run migrations for all tenants:** `php artisan migrate:tenants`. This will prompt you yes/no to seed the databases as well.

## Seeders
**Create a tenant seeder:** `php artisan make:seeder TenantDatabaseSeeder`

**Manually move that file to `database/seeders/tenants/` and then import it into TenantDatabaseSeeder.php.**

## Domains
**Create a new Domain:** Run `php artisan make:Domain`, then you will be prompted to add a Domain name. Make sure it is Plural so "Projects" would be an example.

## Queues and Workers
The project utilizes server software called Supervisor to manage workers. These workers process jobs in the database such as data migrations from NetSuite to SuiteX. 

When updating code that should be acted on by workers the Supervisor workers will need to be restarted. This requires logging into the server and issuing the following command. 

```
// log into server using gcloud... change the 'quinn' to your SD email name
gcloud compute ssh quinn@suitex
// restart the workers
sudo supervisorctl restart "laravel-worker:*"
```