# PIMS — Personal Inventory Management System

PIMS is a Laravel + Inertia.js + Vue 3 application intended to manage personal inventory. This repository is a modern Laravel 12 starter that pairs a PHP backend with a TypeScript/Vue frontend, bundled via Vite and styled with Tailwind CSS.

Note: This README was updated to reflect the current codebase. Where details are unclear in the repository, TODOs are explicitly noted for maintainers to fill in.

## Overview

- Backend: Laravel Framework ^12.0 (PHP ^8.2)
- Inertia.js (server: `inertiajs/inertia-laravel` ^2.x)
- Frontend: Vue 3, TypeScript, Vite 7, Tailwind CSS 4
- Auth: Laravel Fortify
- Dev tooling: Laravel Boost, Pail (logs), Pint (code style), ESLint, Prettier
- Package managers: Composer (PHP) and npm (Node)
- Default entry point: `public/index.php`

## Requirements

- PHP 8.2+
- Composer 2.x
- Node.js 18+ (recommended LTS) and npm 9+
- SQLite (default on first-run) or another database supported by Laravel
  - The project creates `database/database.sqlite` on project creation and runs migrations automatically in some script flows.

## Getting Started

### 1) Clone and configure

```
git clone <YOUR_REPO_URL> pims
cd pims
```

Create your environment file and app key, install dependencies, run migrations, and build assets. The Composer `setup` script automates these steps:

```
composer run setup
```

What `composer run setup` does:
- `composer install`
- Copy `.env.example` to `.env` if it does not exist
- `php artisan key:generate`
- `php artisan migrate --force`
- `npm install`
- `npm run build`

If you prefer to do these manually:

```
cp .env.example .env   # if .env.example is populated; see TODO below
php artisan key:generate
composer install
php artisan migrate
npm install
npm run dev             # or npm run build
```

### 2) Run the app in development

Option A — Single terminal processes:

```
php artisan serve
php artisan queue:listen --tries=1   # optional if you use queues
php artisan pail --timeout=0         # optional live log viewer
npm run dev                          # Vite dev server for assets
```

Option B — Use the combined dev script (runs server, queue, logs, and Vite together):

```
composer run dev
```

Server will be available at the host/port shown in `php artisan serve` output (typically http://127.0.0.1:8000). The default route `/` renders an Inertia page `Welcome`. The `dashboard` route is protected by `auth` and `verified` middleware.

### Optional: Inertia SSR (Server-Side Rendering)

This project includes scripts to build SSR bundles and start the Inertia SSR server.

```
composer run dev:ssr      # will run php server, queue, logs, and the Inertia SSR server
```

Or build SSR assets without starting the SSR process:

```
npm run build:ssr
```

## Scripts

Composer:
- `composer run setup` — Full setup: install PHP deps, ensure `.env`, generate key, migrate, install Node deps, build assets
- `composer run dev` — Concurrent dev processes (server, queue worker, logs, Vite)
- `composer run dev:ssr` — Build SSR assets and run server + queue + logs + Inertia SSR
- `composer run test` — Clear config cache and run tests via `php artisan test`

npm:
- `npm run dev` — Vite dev server
- `npm run build` — Build production assets
- `npm run build:ssr` — Build production assets and SSR bundle
- `npm run lint` — ESLint with auto-fix
- `npm run format` — Prettier write on `resources/`
- `npm run format:check` — Prettier check

## Environment Variables

- The repository contains an `.env.example` file, but it is currently empty.
- TODO: Populate `.env.example` with the required variables for this app (e.g., `APP_NAME`, `APP_ENV`, `APP_KEY`, database config, mail config, etc.).
- On first setup, the scripts will generate `APP_KEY` automatically.
- Database: the project’s Composer post-create hook creates `database/database.sqlite` and runs migrations; you can continue with SQLite (set `DB_CONNECTION=sqlite`) or configure MySQL/PostgreSQL/etc. in `.env`.

## Project Structure

High-level directories of interest:

- `app/` — Laravel application code (models, jobs, controllers, etc.)
- `bootstrap/` — Laravel bootstrapping
- `config/` — Configuration files
- `database/` — Migrations, seeders; SQLite file may live here (`database.sqlite`)
- `public/` — Web server document root; main PHP entry point is `public/index.php`
- `resources/` — Frontend assets (Vue, TypeScript, styles)
- `routes/` — Route definitions (e.g., `web.php` renders Inertia pages)
- `storage/` — Framework storage (logs, cache, sessions)
- `tests/` — Test suite (Pest + Laravel plugin)
- `vite.config.ts` — Vite build configuration
- `composer.json` — PHP dependencies and Composer scripts
- `package.json` — Node dependencies and npm scripts

## Modules

This application is organized to support feature modules under `app/Modules/` (e.g., Movies, Books, Games, Collectibles). Each module owns its domain logic and ships with its own `README.md` documenting endpoints, data models, services/contracts, environment variables, and development notes.

- Current module(s):
  - Movies — see `app/Modules/Movies/README.md` for detailed documentation.

As additional modules are added (Books, Games, Collectibles, etc.), refer to their respective `app/Modules/<Module>/README.md` files for module-specific guidance.

## Running Tests

You can run tests with either Composer or Artisan directly:

```
composer run test
# or
php artisan test
```

The project is configured for Pest with `pestphp/pest` and `pest-plugin-laravel` in `require-dev`.

## Database & Migrations

Run pending migrations:

```
php artisan migrate
```

Seeders/factories are available under `database/` if defined.

Default behavior suggests SQLite can be used out of the box. To switch to another DB, update your `.env` accordingly and re-run migrations.

## Linting & Formatting

```
npm run lint            # ESLint
npm run format          # Prettier write
npm run format:check    # Prettier check
```

PHP code style is managed by Laravel Pint (installed as a dev dependency). You can run it via:

```
./vendor/bin/pint
```

## Development Notes

- Logs: `php artisan pail --timeout=0` starts a live log viewer.
- Queues: `php artisan queue:listen --tries=1` is used in the dev script.
- Docker: Laravel Sail is present as a dev dependency, but the repo does not include a Sail config section here.
  - TODO: Confirm whether Sail should be the preferred local environment and document the `./vendor/bin/sail` workflow if applicable.

## Deployment

General Laravel deployment notes:

1. Ensure environment variables are configured and `APP_KEY` is set.
2. Run migrations: `php artisan migrate --force`.
3. Build assets: `npm ci && npm run build`.
4. Cache optimizations (optional):
   - `php artisan config:cache`
   - `php artisan route:cache`
   - `php artisan view:cache`

TODO: Add specific deployment instructions (hosting provider, CI/CD, SSR process, queue workers, scheduler) once decided.

## License

This project is licensed under the MIT License (per `composer.json`).

TODO: If a `LICENSE` file is missing in the repository root, add one with the MIT license text.