Smart Inventory Core System

A fullstack inventory management system built with Go (Golang) for the backend and React for the frontend, supporting Stock In, Stock Out (Two-Phase Commitment), Inventory management, and transaction reporting.

---

Tech Stack

Layer	Technology
Backend	Go (Golang), Gin / Chi Router
Database	PostgreSQL
Frontend	React, Zustand (State Management)
Auth	JWT

---

Architecture Overview

Backend

The backend follows a layered architecture with SOLID and DRY principles applied throughout:

backend/
├── cmd/
│   └── main.go               # Entry point
├── internal/
│   ├── handler/              # HTTP handlers (controllers)
│   ├── service/              # Business logic layer
│   ├── repository/           # Database access layer (interfaces + implementations)
│   ├── model/                # Domain models & DTOs
│   └── middleware/           # Auth, logging, error handling
├── db/
│   └── migrations/           # SQL migration files
├── config/
│   └── config.go             # Environment config loader
└── .env.example

• Handler → receives HTTP requests, validates input, delegates to Service
• Service → contains all business rules (state machines, stock checks, rollback logic)
• Repository → abstracts all DB queries; uses interfaces for testability
• PostgreSQL transactions are used explicitly for multi-step operations (e.g., Stock Out Two-Phase Commit, Stock In → DONE state update)

Frontend

frontend/
├── src/
│   ├── pages/
│   │   ├── StockIn/
│   │   ├── StockOut/
│   │   ├── Inventory/
│   │   └── Report/
│   ├── components/           # Shared UI components
│   ├── store/                # Zustand global state
│   ├── services/             # API call layer (axios)
│   └── App.tsx

• Zustand manages global state (inventory list, active transactions)
• Services layer abstracts all API calls, keeping components clean
• Each feature page manages its own local UI state (loading, error, form)

---

Prerequisites

• Go >= 1.21
• Node.js >= 18
• PostgreSQL >= 14
• migrate CLI (optional, for running migrations manually)

---

Getting Started

1. Clone the Repository

git clone https://github.com/<your-username>/smart-inventory.git
cd smart-inventory

---

2. Backend Setup

a. Configure Environment

cd backend
cp .env.example .env

Edit .env:

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=yourpassword
DB_NAME=smart_inventory
SERVER_PORT=8080
JWT_SECRET=your_jwt_secret

b. Run Database Migrations

# Using migrate CLI
migrate -path db/migrations -database "postgres://postgres:yourpassword@localhost:5432/smart_inventory?sslmode=disable" up

Or manually execute the SQL files in db/migrations/ in order.

c. Run the Backend

go mod tidy
go run cmd/main.go

Backend will be available at: http://localhost:8080

---

3. Frontend Setup

cd frontend
npm install

Create a .env file:

VITE_API_BASE_URL=http://localhost:8080/api

Start the development server:

npm run dev

Frontend will be available at: http://localhost:5173

---

Key Features

Stock In

• State machine: CREATED → IN_PROGRESS → DONE
• Every status change is logged to a history/log table
• Physical stock in Inventory table only increases when status becomes DONE
• CANCELLED is only allowed before DONE

Inventory

• View all items with filter by Name, SKU, or Customer
• Displays:
  • Physical Stock: total quantity in warehouse
  • Available Stock: physical stock minus quantity reserved by in-progress Stock Out orders
• Stock Adjustment feature to manually edit stock quantity

Stock Out (Two-Phase Commitment)

• Stage 1 — Allocation (DRAFT): System checks available stock → reserves it (status: ALLOCATED). Reserved stock is locked from other orders.
• Stage 2 — Execution: Draft moves to IN_PROGRESS → then DONE
• If cancelled at IN_PROGRESS, system performs rollback: reserved stock is returned to Available

Report

• Only shows transactions with status DONE
• Detailed per-transaction view (Stock In & Stock Out)

---

API Endpoints (Summary)

Method	Endpoint	Description
POST	/api/stock-in	Create new Stock In
PATCH	/api/stock-in/:id/status	Update Stock In status
GET	/api/inventory	List inventory with filters
PATCH	/api/inventory/:id/adjust	Stock adjustment
POST	/api/stock-out	Create Stock Out (Stage 1)
PATCH	/api/stock-out/:id/execute	Execute Stock Out (Stage 2)
PATCH	/api/stock-out/:id/cancel	Cancel & rollback Stock Out
GET	/api/reports	Get completed transaction report

---

Running Tests

# Backend unit tests
cd backend
go test ./...

---

Notes

• All multi-step database operations use explicit PostgreSQL transactions with rollback on error.
• Repository layer uses interfaces, enabling easy mocking for unit tests.
• Stock availability is computed at query time to ensure accuracy under concurrent load.