chill-bundles/.junie/guidelines.md

# Project Guidelines for Junie

## Project Overview

Chill is a comprehensive web application built as a set of Symfony bundles. It is a case management system, for social work. The project consists of multiple specialized bundles that provide different functionalities:

- **ChillMainBundle**: Core bundles that provide the foundation of the application
- **ChillPersonBundle**: Core bundles that provide the foundation of the bundles associated to person (which is the case for all other bundles)
- **ChillCalendarBundle**: Calendar and scheduling functionality
- **ChillDocStoreBundle** and **ChillDocGeneratorBundle**: Document management and generation
- **ChillActivityBundle**, **ChillEventBundle**, **ChillTaskBundle**: Activity and task tracking
- **ChillBudgetBundle**: Financial management
- **ChillThirdPartyBundle**: Integration with external systems
- **ChillCustomFieldsBundle**: Extensibility through custom fields
- **ChillReportBundle**: Save arbitrary reports about persons
- **ChillTicketBundle**: Record and track issues about persons

- And several other specialized bundles

## Technology Stack

- **Backend**: PHP 8.3+, Symfony 5.4
- **Frontend**: JavaScript/TypeScript, Vue.js 3, Bootstrap 5
- **Build Tools**: Webpack Encore, Yarn
- **Database**: PostgreSQL with materialized views
- **Other Services**: Redis, AMQP (RabbitMQ), SMTP

## Project Structure

Note: This is a project which exists from a long time ago, and we found multiple structure inside each bundle. When having the choice, the developers should choose the new structure.

The project follows a standard Symfony bundle structure:
- `/src/Bundle/`: Contains all the Chill bundles. The code is either at the root of the bundle directory, or within a `src/` directory (preferred). See psr4 mapping at the root's `composer.json`.
- each bundle come with his own tests, either in the `Tests` directory (when the code is directly within the bundle directory (for instance `src/Bundle/ChillMainBundle/Tests`, `src/Bundle/ChillPersonBundle/Tests`)), or inside the `tests` directory, alongside to the `src/` sub-directory (example: `src/Bundle/ChillWopiBundle/tests`) (this is the preferred way).
- `/docs/`: Contains project documentation

Each bundle typically has the following structure:

- `Controller/`: Contains controllers
- `Entity/`: Contains Doctrine entities
- `Repository/`: Contains Doctrine repositories
- `Resources/`: Contains views, translations, and public assets
- `DependencyInjection/`: Contains service configuration
- `Export/`: Contains services related to exports
- `Security/`: Contains services related to security. Most of the time, those are new voters, and so on.

### A special word about TicketBundle

The ticket bundle is developed using a kind of "Command" pattern. The controller fill a "Command", and a "CommandHandler" handle this command. They are savec in the `src/Bundle/ChillTicketBundle/src/Action` directory.

## Development Guidelines

### Building and Configuration Instructions

All the command should be run through the `symfony` command, which will configure the required variables.

For assets, we must ensure that we use node at version `^20.0.0`. This is done using `nvm use 20`.

#### Initial Setup

1. **Clone the Repository**:
   ```bash
   git clone <repository-url>
   cd chill-bundles
   ```

2. **Install PHP Dependencies**:
   ```bash
   composer install
   ```

3. **Install JavaScript Dependencies**:
   ```bash
   nvm use 20
   yarn install
   ```

4. **Configure Environment Variables**:

   - Create a `.env.local` file with minimal configuration
   ```bash
   echo "APP_ENV=dev" >> .env.local
   ```

5. Start the associated services (database, and so on):
   ```bash
   docker compose up -d
   ```

5. **Set Up the Database**:
   ```bash
   # Create the database
   symfony console doctrine:database:create

   # Run migrations
   symfony console doctrine:migrations:migrate

   # Load fixtures (optional)
   symfony console doctrine:fixtures:load
   ```

6. **Build Assets**:
   ```bash
   nvm use 20
   yarn run encore dev
   ```

7. **Start the Development Server**:
   ```bash
   symfony server:start -d
   ```

#### Docker Setup

The project includes Docker configuration for easier development:

1. **Start Docker Services**:
   ```bash
   docker-compose up -d
   ```

2. **Access the Application**:
   - The application will be available at `http://localhost:8000`
   - PostgreSQL will be available at `localhost:5432`
   - Redis will be available at `localhost:6379`

#### Building Assets

Before submitting any changes, you should build the project to ensure that all assets are properly compiled:

```bash
# For production
yarn run encore production

# For development with hot-reloading
yarn run encore dev --watch

# for development
yarn run encore dev
```

#### Configuration Files

Key configuration files:

- `config/packages/*.yaml`: Symfony bundle configurations
- `webpack.config.js`: Webpack Encore configuration
- `composer.json`: PHP dependencies and scripts
- `package.json`: JavaScript dependencies and scripts
- `.env`: Default environment variables. Must usually not be updated: use `.env.local` instead.

### Testing Information

The project uses PHPUnit for testing. Each bundle has its own test suite, and there's also a global test suite at the root level.

For creating mock, we prefer using prophecy (library phpspec/prophecy).

#### Running Tests

```bash
# Run all tests
vendor/bin/phpunit

# Run tests for a specific bundle
vendor/bin/phpunit --testsuite NameBundle

# Run a specific test file
vendor/bin/phpunit path/to/TestFile.php

# Run a specific test method
vendor/bin/phpunit --filter methodName path/to/TestFile.php
```

#### Test Structure

Tests are organized by bundle and follow the same structure as the bundle itself:

- Unit tests: Test individual components in isolation
- Integration tests: Test components working together
- Functional tests: Test the application from the user's perspective

#### Writing Tests

Tests should be placed in the appropriate bundle's test directory. For example, tests for the TicketBundle should be placed in `src/Bundle/ChillTicketBundle/tests/`.

Here's an example of a simple entity test:

```php
<?php

namespace Chill\TicketBundle\Tests\Entity;

use Chill\TicketBundle\Entity\Ticket;
use PHPUnit\Framework\TestCase;

class TicketTest extends TestCase
{
    public function testGetAndSetExternalRef(): void
    {
        $ticket = new Ticket();
        $externalRef = 'REF-123';

        // Set the external reference
        $ticket->setExternalRef($externalRef);

        // Verify that getExternalRef returns the correct value
        self::assertSame($externalRef, $ticket->getExternalRef());

        // Change the external reference
        $newExternalRef = 'REF-456';
        $ticket->setExternalRef($newExternalRef);

        // Verify that getExternalRef returns the updated value
        self::assertSame($newExternalRef, $ticket->getExternalRef());
    }
}
```

#### Test Database

For tests that require a database, the project uses an in-memory SQLite database by default. You can configure a different database for testing in the `.env.test` file.

### Code Quality Tools

The project uses several tools to maintain code quality:

#### PHP Code Style

The project uses PHP-CS-Fixer for code style. You can run it with:

```bash
# Using the composer script
composer php-cs-fixer

# Or directly
php-cs-fixer fix --config=./.php-cs-fixer.dist.php
```

#### Static Analysis

The project uses PHPStan for static analysis. You can run it with:

```bash
# Using the composer script
composer phpstan

# Or directly
vendor/bin/phpstan analyse
```

#### Automated Refactoring

The project uses Rector for automated refactoring. You can run it with:

```bash
# Using the composer script
composer rector

# Or directly
vendor/bin/rector
```

#### JavaScript/TypeScript Linting

The project uses ESLint for JavaScript/TypeScript code quality. You can run it with:

```bash
yarn run eslint
```

## Deployment

The project can be deployed in a production environment following Symfony's deployment guidelines. The documentation provides detailed instructions for setting up a production environment.

### Production Deployment Checklist

1. Set environment variables for production
2. Optimize Composer autoloader: `composer install --no-dev --optimize-autoloader`
3. Compile assets for production: `yarn run encore production`
4. Clear and warm up the cache: `php bin/console cache:clear --env=prod`
5. Run database migrations: `php bin/console doctrine:migrations:migrate --env=prod`

## Documentation

Comprehensive documentation is available in the `/docs/` directory, including installation instructions, configuration guides, and operational procedures.

## Development Workflow

1. **Create a Feature Branch**: Always create a new branch for your feature or bugfix
2. **Write Tests**: Write tests for your changes before implementing them
3. **Implement Changes**: Implement your changes following the project's coding standards
4. **Run Tests**: Make sure all tests pass
5. **Run Code Quality Tools**: Make sure your code passes all code quality checks
6. **Submit a Pull Request**: Submit a pull request for review

## Debugging

The project includes several tools for debugging:

- **Symfony Profiler**: Available in development mode at `/_profiler`
- **Xdebug**: Configure your IDE to use Xdebug for step-by-step debugging
- **Symfony Debug Toolbar**: Available at the bottom of the page in development mode

## Conclusion

When working with this project, Junie should:

1. Understand the modular bundle structure and how the different components interact
2. Build the project before submitting changes to ensure assets are properly compiled
3. Run relevant tests to ensure changes don't break existing functionality
4. Follow the established code style and patterns
5. Use the provided tools for debugging and code quality