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.
- 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`.
-`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.
