InsightOS

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

---

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=5000MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/insightosJWT_ACCESS_SECRET=your-access-secret-hereJWT_REFRESH_SECRET=your-refresh-secret-hereAI_PROVIDER=groqAI_MODEL=llama-4-scoutGROQ_API_KEY=gsk_your-groq-api-keyAI_WEB_SEARCH=disabledCORS_ORIGIN=http://localhost:5173SMTP_HOST=smtp.gmail.comSMTP_PORT=587SMTP_USER=your-email@gmail.comSMTP_PASS=your-app-passwordEMAIL_FROM=noreply@insightos.appAPP_URL=http://localhost:5173NODE_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:5000VITE_CURRENCY_CODE=USDVITE_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.