StockFlow

Inventory and Business Expense Management System

StockFlow is a full-stack inventory and business expense management web application for small businesses. It helps users manage products, suppliers, product categories, stock movements, income, expenses, dashboard summaries, and reports from one secure web application.

The project is built as a professional portfolio project using Angular, FastAPI, PostgreSQL, SQLAlchemy, Alembic, JWT authentication, and clean Git-based phase-wise development.

---

Current Status

Status: MVP completed locally

Completed major modules:

• Backend API with FastAPI
• PostgreSQL database integration
• JWT authentication
• Angular frontend layout
• Protected frontend routes
• Dashboard API integration
• Product category CRUD
• Supplier CRUD
• Product CRUD
• Stock in, stock out, and stock adjustment
• Stock movement history
• Expense category CRUD
• Income CRUD
• Expense CRUD
• Reports dashboard
• Advanced report builder with filtered product, finance, and stock movement reports
• Multi-format report export: CSV, Excel, PDF, and Word
• Global UI polish
• Responsive dashboard layout
• Brand logo and favicon integration
• Light and dark theme toggle
• Collapsible sidebar
• Quick actions menu
• Lucide icon system
• Global toast notification system
• Toast feedback for CRUD, stock, finance, category, supplier, product, and report export workflows
• Manual build verification

---

Key Features

Authentication

• User registration
• User login
• JWT access token handling
• Protected backend routes
• Protected frontend routes
• Persistent login after page refresh
• Dynamic topbar user information
• Logout support

Dashboard

• Total product count
• Low-stock product count
• Supplier count
• Total income
• Total expense
• Net balance
• Recent stock activity
• Recent financial activity

Inventory Management

• Add, edit, deactivate, and restore product categories
• Add, edit, deactivate, and restore suppliers
• Add, edit, deactivate, and restore products
• Unique SKU validation
• Product category and supplier assignment
• Low-stock status detection
• Active, low-stock, and inactive product filters
• Search by product name, SKU, category, and supplier

Stock Management

• Stock in
• Stock out
• Insufficient stock protection
• Manual stock adjustment
• Stock movement history
• Movement type filtering
• Stock search by product ID, quantity, reason, and movement type

Finance Management

• Add, edit, and delete income records
• Add, edit, and delete expense records
• Expense category assignment
• Expense category CRUD
• Finance transaction filtering
• Financial summary with income, expense, and net balance

UI and User Experience

• Responsive dashboard layout
• Brand-based sidebar and auth layout
• Light and dark theme support
• Collapsible sidebar navigation
• Quick actions menu
• Lucide icon-based visual system
• Global toast notifications for success and error feedback

Reports

• Summary report cards
• Advanced report builder with report type selection
• Filtered product inventory reports
• Filtered finance transaction reports
• Filtered stock movement reports
• Product status, transaction type, movement type, product, search, and date-range filters
• Live report preview table
• Filtered summary metrics
• Export products, finance records, and stock movements as CSV
• Export filtered reports as Excel files
• Export branded PDF reports with title, generated date, filters, summary, table, and footer
• Export branded Word reports with header, summary, table, and footer
• Lazy-loaded export libraries for better frontend performance
• Toast confirmation after report export

---

Tech Stack

Layer	Technology
Frontend	Angular, TypeScript
Styling	SCSS, responsive custom UI
Icons	Lucide Angular
UI Feedback	Global toast notifications
Backend	FastAPI
Backend Language	Python
Database	PostgreSQL
ORM	SQLAlchemy
Migration	Alembic
Validation	Pydantic
Authentication	JWT
API Documentation	Swagger UI
Version Control	Git

---

Project Structure

stockflow/
├── backend/
│   ├── app/
│   ├── alembic/
│   ├── API_TEST_CHECKLIST.md
│   ├── README.md
│   ├── requirements.txt
│   └── alembic.ini
├── frontend/
│   ├── src/
│   ├── public/
│   ├── angular.json
│   ├── package.json
│   └── README.md
├── database/
├── docs/
├── postman/
├── screenshots/
├── README.md
├── .gitignore
└── LICENSE

---

Local Setup

Backend Setup

Go to the backend folder:

cd backend

Create a virtual environment:

python -m venv .venv

Activate the virtual environment:

.\.venv\Scripts\Activate.ps1

Install backend dependencies:

pip install -r requirements.txt

Create a .env file from .env.example and update the database settings:

APP_NAME=StockFlow API
APP_ENV=development
DEBUG=True
API_V1_PREFIX=/api/v1
DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/stockflow
SECRET_KEY=change-this-secret-key-in-production-use-at-least-32-characters
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60

Run database migrations:

alembic upgrade head

Start the backend server:

python -m uvicorn app.main:app --reload

Backend URL:

http://127.0.0.1:8000

Swagger API documentation:

http://127.0.0.1:8000/docs

Health check:

http://127.0.0.1:8000/health

---

Frontend Setup

Go to the frontend folder:

cd frontend

Install frontend dependencies:

npm install

Start the Angular development server:

npm start

Frontend URL:

http://localhost:4200

Build the frontend:

npm run build

---

Quick Run Commands

Backend

From project root:

.\backend\.venv\Scripts\Activate.ps1
cd backend
python -m uvicorn app.main:app --reload

Frontend

Open another terminal from project root:

cd frontend
npm start

---

API Documentation

FastAPI Swagger UI is available at:

http://127.0.0.1:8000/docs

Implemented API groups:

• Health
• Authentication
• Products
• Product Categories
• Expense Categories
• Suppliers
• Stock
• Finance
• Dashboard

---

Testing Status

The project has been manually tested for:

• Register, login, logout
• Protected frontend routes
• Dashboard API loading
• Product category CRUD
• Supplier CRUD
• Product CRUD
• Stock in
• Stock out
• Stock adjustment
• Stock movement history
• Expense category CRUD
• Income CRUD
• Expense CRUD
• Reports dashboard
• CSV exports
• Excel report exports
• Branded PDF report exports
• Branded Word report exports
• Advanced report filters and preview
• Light/dark theme toggle
• Collapsible sidebar
• Quick actions menu
• Toast feedback for major CRUD and action workflows
• Reports export toast feedback
• Frontend production build

Build command:

cd frontend
npm run build

Expected result:

Application bundle generation complete.

---

Screenshots

Screenshots can be added in the screenshots/ folder.

Recommended screenshots:

• Login page
• Dashboard dashboard
• Collapsible sidebar
• Quick actions menu
• Toast notification examples
• Products page
• Product form
• Suppliers page
• Stock movements
• Stock in/out forms
• Income page
• Expenses page
• Reports page
• Advanced report builder filters
• CSV, Excel, PDF, and Word export evidence

---

Known MVP Limitations

This version is a completed local MVP, but some production-level features are intentionally left for future improvement:

• Data is not yet isolated by company/workspace.
• No role-based permission system yet.
• No dedicated user profile page yet.
• Finance transaction delete is currently hard delete instead of void/cancel.
• Some stock activity views show product ID instead of product name.
• No chart library has been added yet.
• No production deployment has been completed yet.
• No automated test suite has been added yet.

---

Future Improvements

Recommended next improvements:

• Company/workspace-based data isolation
• Role-based access control
• User profile page
• Finance transaction void/cancel workflow
• Product-name mapping in stock movement views
• Dashboard charts
• Automated tests
• Production deployment with hosted database

---

Documentation

Additional project documentation is available in the docs/ folder:

docs/
├── 00-project-overview.md
├── 01-tech-stack.md
├── 02-database-design.md
├── 03-api-endpoints.md
├── 04-phase-plan.md
├── 05-testing-checklist.md
├── 06-git-commit-guide.md
├── 07-deployment-guide.md
├── 08-frontend-architecture.md
├── 09-ui-ux-guidelines.md
├── 10-frontend-phase-plan.md
└── prompts/

Backend-specific documentation:

backend/README.md
backend/API_TEST_CHECKLIST.md

---

Learning Goals

This project demonstrates:

• Full-stack project planning
• Angular frontend development
• FastAPI backend development
• PostgreSQL relational database design
• REST API development
• JWT authentication
• Protected frontend routing
• CRUD workflow implementation
• Stock and finance business logic
• CSV, Excel, PDF, and Word report export
• Advanced report filtering and preview workflow
• Global toast notification UX
• Responsive dashboard UI polish
• Light/dark theme implementation
• Clean Git workflow
• Professional project documentation

---

Author

Asif Elahi

This project is part of my professional portfolio development journey.