205 lines
7.1 KiB
Markdown
205 lines
7.1 KiB
Markdown
# 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.
|