Skip to content

HasibCoderLab/InsightOS

BranchesTags

Repository files navigation

InsightOS

AI-powered business management dashboard for small businesses — manage inventory, track sales, record expenses, and get intelligent insights.

InsightOS Node React MongoDB Tests

Overview

InsightOS is a full-stack business analytics platform built for small business owners who want to move beyond spreadsheets. It combines inventory management, sales tracking, expense monitoring, and AI-driven insights into a single modern dashboard.

The AI assistant (powered by Groq) analyzes your real business data and provides actionable recommendations — from identifying your top-selling products to spotting expense trends.

Supported languages: English & Bengali

Key Features

📦 Inventory Management

  • Product CRUD with name, category, price, and stock tracking
  • Low stock alerts with configurable thresholds
  • Search and category-based filtering
  • Paginated product listings + paginated low-stock endpoint

💰 Sales Tracking

  • Record sales with automatic total calculation
  • Atomic stock management via MongoDB transactions
  • Sales analytics: revenue, quantity, top products, daily trends
  • Filter by date range and product

📉 Expense Monitoring

  • Track expenses across 8 categories (rent, salary, utilities, marketing, supplies, transport, maintenance, other)
  • Expense summaries with category breakdown and daily trends
  • Filter by category and date range

🤖 AI Business Assistant

  • Chat with an AI that has access to your real business data
  • Get insights on revenue, expenses, profit margins, and inventory
  • Multi-turn conversation support with streaming responses
  • Powered by Groq (fast inference via Llama 4 Scout)
  • Optional Google Search grounding for real-time data

📊 Dashboard

  • Consolidated dashboard API endpoint (GET /api/dashboard)
  • Real-time revenue, expense, and profit metrics
  • Revenue & expense trend charts
  • Top products ranking & category breakdown
  • Recent sales & expenses at a glance
  • Low stock product alerts

👤 User Management

  • Avatar upload with automatic file cleanup
  • Email verification flow
  • Password reset (forgot/reset)
  • Admin user listing endpoint
  • Destructive action confirmation ({ "confirm": true })

🛡️ Security

  • JWT authentication with dual httpOnly cookies (access + refresh tokens)
  • Role-based authorization (user/admin)
  • Rate limiting (1000 req/hr general, 60 req/hr for AI)
  • NoSQL injection sanitization
  • Helmet security headers
  • CSRF protection via sameSite: strict cookies
  • Password validation (uppercase, lowercase, number, special character)

🌐 User Experience

  • Dark mode / Light mode toggle
  • English & Bengali language support
  • Smooth animations (Framer Motion)
  • Responsive design
  • Fully accessible (ARIA labels, semantic HTML, keyboard navigation)
  • Configurable currency formatting (VITE_CURRENCY_CODE / VITE_CURRENCY_LOCALE)

Tech Stack

Backend

Technology Purpose
Node.js + Express 5 Server framework
MongoDB + Mongoose 9 Database & ODM
Groq AI Business insights
JWT + bcrypt Authentication & security
Zod 4 Request validation
Multer File uploads
Pino Logging
Nodemailer Email sending (verification, password reset)
Vitest Testing framework

Frontend

Technology Purpose
React 19 UI library
Vite 8 Build tool
Tailwind CSS 4 Styling
TanStack React Query 5 Data fetching & caching
Zustand 5 State management
React Hook Form + Zod Forms & validation
Recharts Data visualization
Framer Motion Animations
Axios HTTP client (with cookie-based auth)
Vitest + jsdom Frontend testing

Getting Started

Prerequisites

  • Node.js 20+ and pnpm (or npm)
  • MongoDB instance (local or MongoDB Atlas)
  • Groq API key (from Groq Console) — optional for AI features

Installation

git clone https://github.com/yourusername/InsightOS.git
cd InsightOS

Backend Setup

cd backend
pnpm install

Create a .env file in backend/:

PORT=5000
MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/insightos
JWT_ACCESS_SECRET=your-access-secret-here
JWT_REFRESH_SECRET=your-refresh-secret-here
AI_PROVIDER=groq
AI_MODEL=llama-4-scout
GROQ_API_KEY=gsk_your-groq-api-key
AI_WEB_SEARCH=disabled
CORS_ORIGIN=http://localhost:5173
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
EMAIL_FROM=noreply@insightos.app
APP_URL=http://localhost:5173
NODE_ENV=development

Start the development server:

pnpm dev

Backend runs at http://localhost:5000

Frontend Setup

cd frontend
pnpm install

Create a .env file in frontend/:

VITE_API_URL=http://localhost:5000
VITE_CURRENCY_CODE=USD
VITE_CURRENCY_LOCALE=en-US

Start the dev server:

pnpm dev

Frontend runs at http://localhost:5173

Running Tests

Backend (46 tests)

cd backend
pnpm test

Frontend (30 tests)

cd frontend
pnpm test

Total: 76 tests across 8 test files

API Endpoints

Authentication

Method Endpoint Auth Description
POST /api/auth/register — Register new account
POST /api/auth/login — Login
POST /api/auth/refresh — Refresh access token (cookie)
POST /api/auth/logout JWT Logout
GET /api/auth/me JWT Get current user
PATCH /api/auth/me JWT Update profile
POST /api/auth/me/avatar JWT Upload avatar
DELETE /api/auth/me/avatar JWT Delete avatar
POST /api/auth/send-verification JWT Send email verification link
GET /api/auth/verify-email?token=xxx — Verify email
POST /api/auth/forgot-password — Send password reset email
POST /api/auth/reset-password — Reset password with token
GET /api/auth/users Admin List all users

Dashboard

Method Endpoint Auth Description
GET /api/dashboard JWT Consolidated dashboard data

Products

Method Endpoint Auth Description
POST /api/products JWT Create product
GET /api/products JWT List products (paginated, filterable)
GET /api/products/low-stock JWT Get low stock items (paginated)
GET /api/products/:id JWT Get product
PATCH /api/products/:id JWT Update product
DELETE /api/products/:id JWT Delete product

Sales

Method Endpoint Auth Description
POST /api/sales JWT Record sale (with stock decrement)
GET /api/sales JWT List sales (paginated, filterable)
GET /api/sales/analytics JWT Get sales analytics
GET /api/sales/:id JWT Get sale

Expenses

Method Endpoint Auth Description
POST /api/expenses JWT Create expense
GET /api/expenses JWT List expenses (paginated, filterable)
GET /api/expenses/summary JWT Get expense summary
GET /api/expenses/:id JWT Get expense
PATCH /api/expenses/:id JWT Update expense
DELETE /api/expenses/:id JWT Delete expense

AI Assistant

Method Endpoint Auth Rate Limit Description
POST /api/ai/chat JWT 60/hr Send chat message
POST /api/ai/chat/stream JWT 60/hr Streaming chat (SSE)
GET /api/ai/conversations JWT — List conversations
GET /api/ai/conversations/:id JWT — Get conversation with messages
DELETE /api/ai/conversations/:id JWT — Delete conversation

User Account

Method Endpoint Auth Description
DELETE /api/user/data JWT Clear all business data (requires { "confirm": true })
DELETE /api/user/account JWT Delete account (requires { "confirm": true })

System

Method Endpoint Auth Description
GET /health — Health check
GET /api-docs — Swagger API documentation

Database Models

User

Field Type Details
name String Required, max 50 chars
email String Required, unique, lowercase
password String Hashed (bcrypt 12 rounds), select: false
role String user or admin
refreshToken String Stored for refresh flow
avatar String File path to uploaded avatar
isVerified Boolean Email verification status
verificationToken String Email verification token
verificationTokenExpires Date Verification token expiry
resetPasswordToken String Password reset token
resetPasswordExpires Date Reset token expiry

Product

Field Type Details
userId ObjectId Ref: User (indexed)
name String Required, max 100 chars
category String Required
price Number Min 0
stock Number Min 0, default 0
lowStockThreshold Number Default 10

Sale

Field Type Details
userId ObjectId Ref: User (indexed)
productId ObjectId Ref: Product
quantity Number Min 1
unitPrice Number Product price at time of sale
totalAmount Number Auto-calculated
note String Max 200 chars
saleDate Date Indexed

Expense

Field Type Details
userId ObjectId Ref: User (indexed)
title String Required, max 100 chars
amount Number Min 0
category String Enum: rent, salary, utilities, marketing, supplies, transport, maintenance, other
note String Max 200 chars
date Date Indexed

AIConversation

Field Type Details
userId ObjectId Ref: User (indexed)
title String Auto-generated from first message
messages Array Embedded: { role, content, timestamp }

Project Structure

InsightOS/
├── backend/
│   ├── src/
│   │   ├── __tests__/          # Backend tests (4 files, 46 tests)
│   │   ├── config/             # Environment, DB, AI, Swagger config
│   │   ├── constants/          # Shared constants (expense categories)
│   │   ├── middleware/         # Auth, error handling, upload, validate
│   │   ├── modules/            # Feature modules
│   │   │   ├── ai/             # AI chat & conversations
│   │   │   ├── auth/           # Authentication & user management
│   │   │   ├── dashboard/      # Dashboard data aggregation
│   │   │   ├── expense/        # Expense tracking
│   │   │   ├── product/        # Product inventory
│   │   │   ├── sales/          # Sales recording & analytics
│   │   │   └── user/           # Account management
│   │   ├── routes/             # Central route registry
│   │   ├── services/           # Shared services (email, businessData)
│   │   └── utils/              # Error classes, tokens, logger
│   ├── uploads/avatars/        # User avatar storage
│   ├── vitest.config.js
│   └── package.json
│
├── frontend/
│   ├── src/
│   │   ├── __tests__/          # Frontend tests (4 files, 30 tests)
│   │   ├── api/                # Axios config & API modules
│   │   ├── components/         # Reusable UI components
│   │   │   ├── charts/         # Recharts visualizations
│   │   │   ├── layout/         # Sidebar, Topbar, AppLayout, Footer
│   │   │   └── ui/             # Button, Card, Modal, Table, Input...
│   │   ├── context/            # Language context (i18n)
│   │   ├── hooks/              # React Query hooks
│   │   ├── lib/                # Translations, motion variants
│   │   ├── pages/              # Route pages
│   │   ├── store/              # Zustand stores
│   │   └── utils/              # Helpers (cn, config, format)
│   ├── vite.config.js
│   └── package.json
│
├── plan.md                     # Improvement plan (Bengali)
├── পরিবর্তনের-সারসংক্ষেপ.md    # Change summary (Bengali)
└── README.md

Architecture

The backend follows a modular architecture with clean separation of concerns:

Controller → Service → Repository → Model
  • Controller — Handles HTTP requests/responses
  • Service — Business logic and orchestration
  • Repository — Database queries and data access
  • Model — Mongoose schema definitions

Each module (auth, product, sales, expense, ai, user, dashboard) is self-contained with its own controllers, services, repositories, models, and validation schemas. Cross-module dependencies are handled through shared services (services/businessData.service.js, services/email.service.js).

Authentication Flow

Login → JWT (15min) + Refresh Token (7d)
       ↓
Both stored as httpOnly cookies (sameSite: strict)
       ↓
API calls automatically send cookies → authenticateToken middleware reads cookie
       ↓
On 401 → axios interceptor calls /auth/refresh → new accessToken cookie set

Environment Variables

Backend (backend/.env)

Variable Required Default Description
MONGODB_URI Yes — MongoDB connection string
JWT_ACCESS_SECRET Yes — Access token secret
JWT_REFRESH_SECRET Yes — Refresh token secret
GROQ_API_KEY No — Groq API key (for AI features)
PORT No 5000 Server port
NODE_ENV No development Environment mode
AI_PROVIDER No groq AI provider
AI_MODEL No llama-4-scout AI model name
AI_WEB_SEARCH No disabled Web search support (varies by provider)
CORS_ORIGIN No http://localhost:5173 Frontend origin
SMTP_HOST No smtp.gmail.com SMTP server
SMTP_PORT No 587 SMTP port
SMTP_USER No — SMTP username
SMTP_PASS No — SMTP password
EMAIL_FROM No noreply@insightos.app Sender email
APP_URL No http://localhost:5173 Frontend URL for email links

Frontend (frontend/.env)

Variable Required Default Description
VITE_API_URL No http://localhost:5000 Backend API URL
VITE_CURRENCY_CODE No USD Currency code (e.g. USD, BDT, EUR)
VITE_CURRENCY_LOCALE No en-US Locale for formatting (e.g. en-US, bn-BD)

Testing

Suite Files Tests Command
Backend (unit) 4 46 cd backend && pnpm test
Frontend (unit) 4 30 cd frontend && pnpm test
Total 8 76

Backend coverage

  • Utility classes (ApiError, ApiResponse, asyncHandler)
  • JWT token generation & verification
  • Validation middleware (Zod body/query)
  • All Zod schemas (auth, product, sale, expense)

Frontend coverage

  • Zustand auth store state management
  • Currency formatting (configurable locale)
  • Date formatting & relative time
  • Tailwind classname merging (cn utility)

License

This project is licensed under the MIT License.

Built with care for small business owners who deserve better tools.

About

AI-powered business management dashboard inventory, sales, expenses, and intelligent insights in one place.

Topics

inventory-management react-query zustand sales-tracking business-dashboard

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages