📦 InvicSuX - Modern Inventory Management System

InvicSuX is a comprehensive, full-stack Inventory Management System designed to help businesses manage products, monitor stock levels, and organize warehouse inventory efficiently.

Our goal is to provide a modern, scalable, and intuitive platform for warehouse staff, inventory managers, and administrators, offering real-time tracking and centralized stock management.

---

📑 Table of Contents

1. Tech Stack
2. Project Structure
3. Prerequisites
4. Getting Started
   • Database Setup
   • Backend Setup
   • Frontend Setup
   • Mobile App Setup
5. Recommended First Run Order
6. Verification Checklist
7. Mobile App Usage
8. Troubleshooting
9. Contributing

---

🛠 Tech Stack

Backend

• Language: Python 3.12
• Framework: FastAPI
• ORM / Database: SQLAlchemy 2.x, asyncpg, PostgreSQL
• Migrations: Alembic

Web Frontend

• Framework: Angular 19
• Language: TypeScript
• Styling: SCSS

Mobile App

• Framework: Flutter
• Language: Dart
• State Management: Provider

Security Features

• JWT Access & Refresh Tokens
• Bcrypt password hashing
• OTP password reset
• Comprehensive Audit logging

---

📂 Project Structure

invicsux/
├── backend/       # FastAPI monolith, Alembic migrations, PostgreSQL compose file, seed utilities
├── frontend/      # Angular 19 admin panel and operations UI
└── invicsux-app/  # Flutter mobile application

---

⚠️ Prerequisites

Before you begin, ensure you have the following installed on your local machine:

• Python: 3.12.x
• Node.js: 20.x or newer
• PostgreSQL: 16+ (or Docker Desktop)
• Flutter SDK: Latest stable release

---

🚀 Getting Started

1. Database Setup

Option A: Docker PostgreSQL (Recommended) From the workspace root, spin up the database using Docker:

cd backend
docker compose up -d postgres

This starts PostgreSQL on localhost:5433.

Option B: Local PostgreSQL Create a database named invicsux in your local Postgres instance, then update backend/.env with your credentials.

2. Backend Setup

Navigate to the backend directory, install dependencies, and set up your environment variables:

cd backend
py -3.12 -m pip install --user -r requirements.txt
Copy-Item .env.example .env

Note: Edit backend/.env if necessary. If DATABASE_URL is empty, the backend automatically builds it from the POSTGRES_* variables.

Run Database Migrations:

py -3.12 -m alembic upgrade head

(Useful Alembic commands: alembic current, alembic history, alembic downgrade -1)

Populate Demo Data (Seed): This creates roles, demo users, warehouses, products, and inventory operations.

py -3.12 -m app.utils.seed_demo

Demo Login Accounts:

• Admin: admin001 / Admin@123!
• Manager: manager01 / Manager@123!
• Staff: staff001 / Staff@123!

Start the Backend Server:

py -3.12 -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

• API: http://localhost:8000/api/v1
• Docs: http://localhost:8000/docs
• Health: http://localhost:8000/health

3. Frontend Setup (Angular)

Open a new terminal and run:

cd frontend
cmd /c npm install
cmd /c npm start

Default URL is http://localhost:4200. If the port is busy, run: cmd /c "npm start -- --port 4300"

4. Mobile App Setup (Flutter)

Open a new terminal and run:

cd invicsux-app
flutter pub get
flutter run

---

🏃 Recommended First Run Order

For the smoothest initial setup, execute commands in this exact order:

1. Backend: cd backend docker compose up -d postgres py -3.12 -m pip install --user -r requirements.txt Copy-Item .env.example .env py -3.12 -m alembic upgrade head py -3.12 -m app.utils.seed_demo py -3.12 -m uvicorn app.main:app --reload

2. Frontend: cd frontend cmd /c npm install cmd /c npm start

3. Mobile App: cd invicsux-app flutter pub get flutter run

---

✅ Quick Verification Checklist

After starting all services, confirm the following:

• Login works in the Angular UI using demo credentials.
• Dashboard displays accurate inventory KPIs.
• Products page lists the seeded demo products.
• Operations pages reflect demo receipts and transfers.
• Stock ledger entries appear correctly in the history tab.
• Admin pages successfully display RBAC roles and permissions.

---

📱 Mobile App Usage Example

The Flutter application provides warehouse staff with on-the-go access to product management, stock tracking, and low-stock identification.

Navigation Example:

Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => DashboardScreen()),
);

Accessing Inventory State:

final inventoryProvider = Provider.of<InventoryProvider>(context);
print(inventoryProvider.products);

---

🔧 Troubleshooting

Migration Issues

• Ensure PostgreSQL is running.
• Confirm the database invicsux exists.
• Re-run the migration command: py -3.12 -m alembic upgrade head

Login Works but UI is Empty

• The database might be empty. Re-run the seed script: py -3.12 -m app.utils.seed_demo

Frontend Cannot Reach Backend

• Verify the backend is actively running on port 8000.
• Check the CORS settings in your .env file.
• Ensure the frontend port (e.g., http://localhost:4200) is listed in ALLOWED_CORS_ORIGINS.

---

🤝 Contributing

Pull requests are highly encouraged and welcome!

For major changes, please open an issue first to discuss what you would like to change. Please ensure the project builds and all tests pass successfully before submitting your PR.