# Repository Guidelines

## Project Structure & Module Organization

OpenSem builds on Laravel 9.

Core application code lives in `app/`, while HTTP routes reside in
`routes/` and Blade views in `resources/views/`. Reusable front-end
assets (JS, SCSS, images) sit under `resources/` and are compiled into
`public/` via Laravel Mix.

Database blueprints are versioned in `database/migrations/` with seeds
in `database/seeders/`.

Tests are organised in `tests/Unit/` and `tests/Feature/`; keep large
fixtures in `tests/Fixtures/` to avoid polluting source directories.

## Build, Test, and Development Commands

- `composer install` — install PHP dependencies defined in
  `composer.json`.

- `php artisan serve` — start a local HTTP server on port 8000.

- `npm install && npm run dev` — install Node tooling and build UI
  assets for development.

- `npm run prod` — generate minified production assets in `public/`.

- `php artisan migrate --seed` — apply database schema and load
  default data for demo instances.

- `./build.sh` — builds a `.tar.xz` that contains the production and
  deployement ready source to be deployed.

## Coding Style & Naming Conventions

Follow PSR-12 with four-space indentation and `snake_case` database
columns. Controllers, models, and Livewire components use StudlyCase
class names; private methods remain `camelCase`. Run `composer run
inspect` before opening a PR to execute `phpcs` and `phpstan`. For
front-end changes, keep Blade sections in lowercase kebab IDs (for
example, `@section('order-summary')`).

## Testing Guidelines

Use PHPUnit via `php artisan test`; target deterministic tests with
clear Arrange/Act/Assert blocks. Feature tests should mirror top-level
route names (e.g., `OrdersTest.php`). Unit tests belong in
`tests/Unit/` and should stub external services. When adding
migrations or service integrations, include coverage that exercises
failure paths. For granular checks, `./vendor/bin/phpunit --filter
FooTest` is acceptable, but always run the full suite before pushing.

## Commit & Pull Request Guidelines

Commits in this repo mix Conventional Commit prefixes (`new:`, `fix:`,
`chg:`); `fix: prevent null totals`. Keep messages in the imperative
mood and reference ticket IDs when available.

Pull requests must describe scope, list schema or configuration
changes, and note any manual follow-up (cron, storage links,
queues).

Attach screenshots or terminal logs when touching UI or console
output, and ensure CI scripts (when available) pass.

## Environment & Security Notes

Copy `.env.example` to `.env` and run `php artisan key:generate`
before local work. Never commit `.env`, `storage/`, or database dumps
containing sensitive data. Use the Docker resources in `docker/` only
for reproducible environments; keep secrets in your host overrides,
not in version control.