Skip to main content
This guide will help you get the Inventory Management System running quickly. You’ll have both the backend API and frontend application operational in just a few steps.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.8+ - For running the Flask backend
  • Node.js 18+ and npm - For the React frontend
  • Git - To clone the repository

​
Get the source code

Clone the repository to your local machine: 
git clone <your-repository-url>
cd inventory-management-system

​
Start the backend

1

Navigate to the backend directory

cd backend
2

Install Python dependencies

pip install -r requirements.txt
Consider using a virtual environment to isolate dependencies:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
3

Start the Flask server

python main.py
The backend API will start on http://localhost:8000. You should see:
Starting Inventory API on http://0.0.0.0:8000
4

Verify the backend is running

Open another terminal and test the health endpoint:
curl http://localhost:8000/api/health
You should receive:
{"status": "ok", "service": "inventory-api"}
The database and initial admin user are created automatically on first run. No manual database setup required!

​
Start the frontend

1

Navigate to the frontend directory

Open a new terminal window:
cd frontend
2

Install npm dependencies

npm install
3

Start the development server

npm run dev
The frontend will start on http://localhost:5173. You should see:
VITE ready in XXX ms
➜  Local:   http://localhost:5173/

​
Log in to the system

The system automatically creates a default admin user during initialization: 
{
  "username": "admin",
  "email": "[email protected]",
  "password": "Admin1234!",
  "role": "admin"
}
1

Open the application

Navigate to http://localhost:5173 in your web browser.
2

Enter credentials

  • Username: admin
  • Password: Admin1234!
3

Explore the system

After logging in, you’ll have full access to:
  • Products - Manage inventory items
  • Purchases - Record incoming stock
  • Point of Sale - Process sales transactions
  • Customers & Suppliers - Manage stakeholders
  • Reports - View inventory analytics
  • Users - Create and manage user accounts (admin only)
  • Audit Logs - Track system activities (admin only)
Change the default admin password immediately in a production environment. The current credentials are for development only.

​
User roles

The system includes three predefined roles:
RoleDescriptionAccess Level
AdminFull system access including user management and audit logsAll features
GestorManage products, inventory movements, and reportsNo user management or audit access
ConsultorRead-only access to view inventory and reportsView only
As an admin, you can create additional users with different roles from the Users page in the navigation menu.

​
Next steps

Installation Guide

Detailed installation instructions and configuration options

API Reference

Explore the REST API endpoints

User Management

Learn about roles, permissions, and authentication

Product Management

Start managing your inventory

​
Troubleshooting

​
Backend won’t start

If you see import errors, ensure all dependencies are installed: 
pip install -r requirements.txt --upgrade

​
Frontend won’t connect to backend

Verify the backend is running on http://localhost:8000 and check for CORS errors in the browser console. The backend is configured to accept requests from any origin in development mode.

​
Database errors

The SQLite database file inventory.db is created automatically in the backend directory. If you encounter database errors, you can delete this file and restart the backend to recreate it with fresh data.

​
Port already in use

If port 8000 or 5173 is already in use:
  • Backend: Modify the port in backend/main.py:73 (change port=8000)
  • Frontend: Vite will automatically suggest an alternative port
For production deployment, see the Installation Guide for environment-specific configuration options.

Build docs developers (and LLMs) love

Get started for freeTalk to us