Stock Pilot - Project Plan

Project Overview

What we're building and why

Stock Pilot is a web-based inventory and invoice management platform designed for businesses to track products, manage stock levels, generate invoices, and monitor operations through a centralized dashboard. The platform supports multi-user access with role-based permissions (Admin, Manager, Staff).

Inventory Control

Track products, quantities, and stock movements in real-time

Invoice Management

Create, manage, and export professional invoices

Multi-User & Roles

Admin, Manager, Staff with different permissions

Live Dashboard

Overview stats, charts, and low-stock alerts

Smart Alerts

Automatic notifications for low stock levels

Responsive UI

Works on desktop, tablet, and mobile devices

Tech Stack

Technologies powering Stock Pilot

React + Vite

Frontend UI & interactions

Tailwind CSS

Styling & responsive design

Node.js + Express

Backend REST API server

PostgreSQL

Relational database

Prisma ORM

Database queries & migrations

JWT + bcrypt

Authentication & security

Zod

Input validation

PDFKit

Invoice PDF generation

User Roles & Permissions

Access control matrix for each role

Admin

Full system access
Manages users & settings

Manager

Manage stock & invoices
View reports & analytics

Staff

View stock & create invoices
Limited dashboard access

Feature	Admin	Manager	Staff	Notes
View Dashboard	Full	Full	Limited	Staff sees basic stats only
Manage Products	Full	Full	View	Staff can only view products
Create Invoices	Yes	Yes	Yes	All roles can create
View All Invoices	All	All	Own	Staff sees own invoices only
Delete Invoices	Yes	No	No	Admin only for safety
Manage Users	Yes	No	No	Admin manages all users
Manage Categories	Yes	Yes	No	—
View Reports	Yes	Yes	No	—
System Settings	Yes	No	No	Admin only

Core Features (MVP)

Minimum viable product feature set

Authentication

User registration (by Admin)
Login / Logout flow
JWT-based session tokens
Password hashing (bcrypt)
Role-based route protection
Auto token refresh

User Management

Add / Edit / Delete users
Assign roles (Admin, Manager, Staff)
View all users list
User profile page
Change password
Account status (Active/Inactive)

Product & Stock

Add / Edit / Delete products
Product categories
Track quantities (in/out)
Low stock alerts & thresholds
Stock movement history log
Search, sort & filter

Invoice Management

Create new invoices
Add multiple line items
Auto-calculate totals & tax
Status: Draft / Sent / Paid
View / Print / Export PDF
Search & filter invoices

Dashboard

Total products & stock value
Low stock warning cards
Recent invoices list
Stock movement chart
Revenue overview graph
Quick action buttons

Reports (Future)

Stock summary report
Sales report by period
Top-selling products
Export to CSV / PDF
Profit margins analysis
Custom date ranges

Project Structure

File and folder organization

stock-pilot/
├── client/                      # Frontend (React + Vite)
│   ├── public/
│   └── src/
│       ├── assets/            # Images, icons, logos
│       ├── components/
│       │   ├── common/        # Button, Modal, Table
│       │   ├── layout/        # Sidebar, Header, Footer
│       │   └── forms/         # Form components
│       ├── pages/             # Page components
│       │   ├── Dashboard.jsx
│       │   ├── Products.jsx
│       │   ├── Invoices.jsx
│       │   ├── Users.jsx
│       │   ├── Login.jsx
│       │   └── Profile.jsx
│       ├── context/            # Auth context provider
│       ├── hooks/              # Custom React hooks
│       ├── services/           # API call functions
│       ├── utils/              # Helper functions
│       ├── App.jsx
│       └── main.jsx
│
├── server/                     # Backend (Node.js + Express)
│   └── src/
│       ├── controllers/        # Route handlers
│       ├── middleware/          # Auth & role guards
│       ├── routes/             # API route definitions
│       ├── validators/         # Input validation (Zod)
│       ├── utils/              # PDF gen, helpers
│       └── app.js              # Express app setup
│
├── prisma/                     # Database layer
│   ├── schema.prisma         # DB schema definition
│   ├── migrations/           # Migration files
│   └── seed.js               # Default admin seed
│
├── .gitignore
├── .env                       # Environment variables
└── package.json

Database Schema

PostgreSQL tables and relationships

Users

Categories

Products

StockMovements

Invoices

InvoiceItems

Users 1 → N Invoices • Users 1 → N StockMovements • Categories 1 → N Products
Products 1 → N StockMovements • Invoices 1 → N InvoiceItems • Products 1 → N InvoiceItems

Users

Column	Type
id PK	UUID
name	String
email	String (unique)
password	String (hashed)
role	Enum (ADMIN\|MANAGER\|STAFF)
createdAt	DateTime

Categories

Column	Type
id PK	UUID
name	String
description	String?
createdAt	DateTime

Products

Column	Type
id PK	UUID
name	String
sku	String (unique)
categoryId FK	UUID
quantity	Integer
minQuantity	Integer
price	Decimal
costPrice	Decimal

Stock Movements

Column	Type
id PK	UUID
productId FK	UUID
type	Enum (IN\|OUT\|ADJ)
quantity	Integer
reason	String?
userId FK	UUID
createdAt	DateTime

Database Schema (cont.)

Invoice tables

Invoices

Column	Type
id PK	UUID
invoiceNumber	String (unique, auto)
customerName	String
customerEmail	String?
status	Enum (DRAFT\|SENT\|PAID\|CANCELLED)
subtotal	Decimal
tax	Decimal
total	Decimal
notes	String?
createdBy FK	UUID
createdAt	DateTime

Invoice Items

Column	Type
id PK	UUID
invoiceId FK	UUID
productId FK	UUID
quantity	Integer
unitPrice	Decimal
total	Decimal

API Endpoints

RESTful API routes

Authentication

Method	Endpoint	Description	Access
POST	/api/auth/login	Login user	Public
POST	/api/auth/logout	Logout user	All
GET	/api/auth/me	Get current user	All

Users

Method	Endpoint	Description	Access
GET	/api/users	List all users	Admin
POST	/api/users	Create new user	Admin
PUT	/api/users/:id	Update user	Admin
DELETE	/api/users/:id	Delete user	Admin

API Endpoints (cont.)

Products, Categories, Invoices & Dashboard

Products

Method	Endpoint	Description	Access
GET	/api/products	List all products	All
POST	/api/products	Create product	Admin, Manager
GET	/api/products/:id	Get product details	All
PUT	/api/products/:id	Update product	Admin, Manager
DELETE	/api/products/:id	Delete product	Admin, Manager
GET	/api/products/low-stock	Low stock items	Admin, Manager

Categories

Method	Endpoint	Description	Access
GET	/api/categories	List categories	All
POST	/api/categories	Create category	Admin, Manager
PUT	/api/categories/:id	Update category	Admin, Manager
DELETE	/api/categories/:id	Delete category	Admin

Invoices

Method	Endpoint	Description	Access
GET	/api/invoices	List invoices	All (filtered)
POST	/api/invoices	Create invoice	All
GET	/api/invoices/:id	Get invoice details	Owner / Admin
PUT	/api/invoices/:id	Update invoice	Admin, Manager
DELETE	/api/invoices/:id	Delete invoice	Admin
GET	/api/invoices/:id/pdf	Download PDF	Owner / Admin

Dashboard

Method	Endpoint	Description	Access
GET	/api/dashboard/stats	Overview statistics	All
GET	/api/dashboard/movements	Recent movements	Admin, Manager
GET	/api/dashboard/revenue	Revenue data	Admin, Manager

UI Screens

Application pages and views

1

Login Page

Email & password authentication

2

Dashboard

Stats, charts, alerts, recent activity

3

Products List

Search, filter, stock status table

4

Product Form

Add/Edit with all product fields

5

Categories

List & manage product categories

6

Invoices List

Filter by status, date, customer

7

Invoice Form

Create with line items & auto-totals

8

Invoice Detail

View, print, download PDF

9

Users List

Admin view — manage all users

10

User Form

Add/Edit user with role assignment

11

Profile

Edit own info, change password

12

Stock Movements

History log of all stock changes

Development Phases

Step-by-step build roadmap

Phase 1

Foundation & Setup

Project scaffolding (React, Express, Prisma)
Database schema & migrations
JWT authentication system
App layout (sidebar, header, routing)

Phase 2

Core Features

User management (CRUD + roles)
Product management + categories
Stock tracking & movement log
Low-stock alerts & thresholds

Phase 3

Invoices & PDF

Invoice CRUD operations
Line items & auto-calculations
PDF generation & export
Invoice status management

Phase 4

Dashboard & Polish

Dashboard stats & charts
Search, sort & filtering
Responsive design & mobile
Error handling & validation

Phase 5

Deployment

Production build optimization
Environment configuration
Deploy to hosting server
Testing & bug fixes