PIMS/README.md

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.