InvoiceFlow – Indian Business Management Suite

InvoiceFlow is a Next.js application designed for Indian businesses to manage invoices, income, expenses, clients, suppliers, inventory, logistics, and employees — all in one place.

All financial flows are standardized to use Indian Rupees (INR, ₹) with Indian locale formatting.

---

1. Tech Stack

• Framework: Next.js (App Router)
• Language: TypeScript + React
• Styling: Tailwind CSS + shadcn/ui
• Icons: lucide-react
• Persistence: localStorage in the browser (no backend)
• Currency: INR only, via a centralized currency context

Project root:

• App entry: src/app/page.tsx
• Main application shell: src/app/(main)/layout.tsx
• Global styles: src/app/globals.css

---

2. Application Layout & Navigation

The main app lives under src/app/(main) and is wrapped by a shared layout that provides:

• Sidebar navigation with grouped modules:
  • Dashboard
  • Invoices
  • Transactions
  • Inventory
  • Logistics
  • Employees
  • Suppliers
  • Clients
  • Documentation
  • Settings
• Top header and main content area

Key files:

• Root layout: src/app/layout.tsx
• Main layout and sidebar: src/app/(main)/layout.tsx
• Landing page: src/app/page.tsx (marketing/overview + CTA to /dashboard)

---

3. Currency & Localization

All business values are expressed in INR:

• Currency context: src/context/currency-context.tsx
  • CurrencyCode is restricted to "INR".
  • CurrencyProvider exposes:
    • currency (always "INR")
    • formatCurrency(amount) → ₹ formatted via en-IN
    • availableCurrencies (only INR)
  • useCurrency() is used across dashboard, invoices, and income screens.

When values are rendered manually (without useCurrency()), patterns follow:

• ₹{value.toLocaleString("en-IN")}

All previous references to $ / USD have been removed or converted to INR.

---

4. Modules & Pages

4.1 Dashboard

• Route: /dashboard
• File: src/app/(main)/dashboard/page.tsx
• Features:
  • Quick actions:
    • Create Invoice (/invoices/new)
    • Create Purchase Order (/purchase/create-order)
    • Add Client (/clients/new)
    • Record Expense (/transactions/expenses)
  • KPIs via DashboardStats:
    • Total Revenue
    • Overdue Invoices (₹)
    • Paid (Last 30 days)
    • Draft Invoices
  • OverviewChart for trends
  • RecentInvoices (last 5 invoices with INR amounts)
  • Purchase Orders status pie chart using localStorage.purchase_orders
  • Low stock products bar chart using localStorage.inventory_products

4.2 Invoices

4.2.1 Invoices List

• Route: /invoices
• File: src/app/(main)/invoices/page.tsx
• Responsibilities:
  • Tabs for All, Paid, Overdue, Draft
  • Filters and search
  • Table columns: Invoice ID, Client, Status, Due Date, Amount
  • Amounts formatted with useCurrency().formatCurrency (₹).

4.2.2 New Invoice

• Route: /invoices/new
• File: src/app/(main)/invoices/new/page.tsx
• Key model:
  • InvoiceItem: { id, description, quantity, price, tax }
• Calculations:
  • subtotal = Σ(quantity * price)
  • totalTax = Σ(quantity * price * tax/100)
  • total = subtotal + totalTax - discount
• Currency:
  • Internal currency state exists, but currencySymbol is fixed to "₹".
  • Currency <Select> offers only INR (₹).
• Template integration:
  • templateId read from URL (?template=...)
  • Maps to templates in src/components/invoice-previews.tsx
  • Constructs InvoiceData and renders selected template.
• Persistence:
  • Final invoice data is stored in localStorage.invoices.

4.2.3 Recurring Invoices

• Route: /invoices/recurring
• File: src/app/(main)/invoices/recurring/page.tsx
• Types:
  • Frequency: "daily" | "weekly" | "bi-weekly" | "monthly" | "quarterly" | "yearly"
  • RecurringInvoice:
    • id, name, frequency, startDate, endDate?
    • nextRunDate, lastRunDate?, autoSend, status
    • Invoice data: clientId, items, currency, discount, notes, createdAt
• Features:
  • Modes:
    • list – overview table of profiles
    • create / edit – full form
  • Currency:
    • currencySymbol is "₹"
    • Currency <Select> restricted to INR
  • Persistence:
    • localStorage.recurringInvoices (dates hydrated from strings back to Date).

4.2.4 Invoice Templates Gallery

• Route: /invoices/templates
• File: src/app/(main)/invoices/templates/page.tsx
• Description:
  • Shows mini previews of built-in templates using previewData with INR:
    • Example: total: "₹1,250.00"
  • Each template card can be “used”:
    • Navigates to /invoices/new?template=<id>.

4.2.5 Invoice Template Builder

• Route: /invoices/templates/builder
• File: src/app/(main)/invoices/templates/builder/page.tsx
• Purpose:
  • Build and customize invoice templates (drag/drop blocks).
• Components:
  • TemplateElement, CustomTemplateConfig from invoice-previews
  • previewData: InvoiceData with currencySymbol: "₹"
  • DynamicTemplate for live preview.
• Persistence:
  • Templates stored in localStorage.customInvoiceTemplates.
  • Used later by /invoices/new.

---

4.3 Documentation / Quotation

• Route: /documentation/quotation
• File: src/app/(main)/documentation/quotation/page.tsx
• Purpose:
  • Create quotation documents that leverage the same invoice templates.
• Logic:
  • Uses InvoiceItem and calculates:
    • subtotal, totalTax, discount, total
  • currencySymbol is "₹".
  • Builds InvoiceData with title: "QUOTATION" and feeds templates.
• Additional features:
  • Email:
    • Opens mailto: with subject/body including quotation number and total in ₹.
  • WhatsApp:
    • Opens wa.me with prefilled text including quotation number and total in ₹.

---

4.4 Transactions

4.4.1 Income

• Route: /transactions/income
• File: src/app/(main)/transactions/income/page.tsx
• Data:
  • Paid invoices from static invoice data.
  • Manual incomes from localStorage.manual_incomes.
• Features:
  • Tabs/filters for invoice income vs manual income.
  • Total income and trends.
  • All monetary values in INR (via useCurrency()).

4.4.2 Expenses & Recurring Expenses

• Route: /transactions/expenses
• File: src/app/(main)/transactions/expenses/page.tsx
• Data:
  • localStorage.expenses
  • localStorage.recurring_expenses
• Features:
  • Manual expenses (date, amount, category, description).
  • Recurring expenses:
    • Frequencies: weekly, monthly, yearly.
    • Add, Edit, Delete, Pause/Resume.
    • “Record Transaction” to log an actual expense instance.

4.4.3 Balance Sheet

• Route: /transactions/balance-sheet
• File: src/app/(main)/transactions/balance-sheet/page.tsx
• Data sources:
  • Invoices:
    • From localStorage.invoices if present, otherwise mock data.
  • Expenses:
    • From localStorage.expenses if present, otherwise mock data.
• Metrics:
  • Total Receivable (pending+overdue)
  • Total Revenue (paid)
  • Received This Month
  • Due This Month
• Visualizations:
  • Bar chart: Revenue vs Expenses (last 6 months, in ₹).
  • Pie chart: Invoice status distribution (Paid/Pending/Overdue).
  • Client insights table:
    • Revenue and outstanding (INR) per client.

4.4.4 Employee Payout

• Route: /transactions/employee-payout
• File: src/app/(main)/transactions/employee-payout/page.tsx
• Data:
  • Employees: localStorage.employees
  • Attendance: localStorage.attendance_records
  • Salary structures: localStorage.employee_salary_structures
• Models:
  • EmployeeType: "Salaried" | "Daily Wage"
  • SalaryStructure:
    • Earnings: basic, hra, da, ta, medicalAllowance, specialAllowance
    • Deductions: pf, professionalTax, tds, otherDeduction
    • Daily-wage specific: otherBonus, anyDeduction
• Calculations (per employee, per month):
  • Attendance:
    • presentDays, halfDays, absentDays, payableDays
  • Salaried:
    • Gross earnings = sum of earnings components
    • Total deductions = sum of deduction components
    • Net monthly = Gross – Deductions
    • Daily net = Net / number of days in month
    • Payout = Daily net * payableDays
  • Daily wage:
    • Base = dailyRate * payableDays
    • Payout = Base + bonus – deduction
• UI:
  • Tabs for salaried vs daily wage employees.
  • Salary structure configuration dialog.
  • Summaries using ₹ and Indian number formatting.

4.4.5 Salary Slip

• Route: /transactions/salary-slip
• File: src/app/(main)/transactions/salary-slip/page.tsx
• Purpose:
  • Generate printable salary slips for both employee types using the same attendance and salary structure data as Employee Payout.
• Features:
  • Month navigation.
  • Select salaried or daily wage employees (only Active).
  • Summary cards: Net Monthly, Payout This Month, Present/Payable, Absent/Half Days.
  • Detailed slip:
    • Employee info
    • Pay period (start/end dates)
    • Earnings & deductions breakdown (salaried)
    • Daily wage details, bonuses, and deductions (daily wage)
    • Net monthly and payout for period in ₹.
• Printing:
  • Download / Print Salary Slip → window.print().
  • @media print in globals.css hides the app and prints only the slip card (#salary-slip-print).

---

4.5 Inventory

4.5.1 Manage Stocks

• Route: /inventory/manage-stocks
• File: src/app/(main)/inventory/manage-stocks/page.tsx
• Features:
  • List of stock items.
  • Search by name/SKU.
  • Filter by category/status.
  • Adjustments:
    • Add, Remove, or Set stock.
• Data:
  • localStorage.inventory_products
  • localStorage.inventory_categories

4.5.2 Products

• Route: /inventory/products
• File: src/app/(main)/inventory/products/page.tsx
• Features:
  • CRUD for products (name, SKU, category, etc.).
  • Synchronized with stocks page.
• Data:
  • localStorage.inventory_products

4.5.3 Categories

• Route: /inventory/categories
• File: src/app/(main)/inventory/categories/page.tsx
• Features:
  • Add, edit, remove inventory categories.
  • Used by both products and stocks for consistent classification.
• Data:
  • localStorage.inventory_categories

---

4.6 Logistics

4.6.1 Vehicles

• Route: /logistics/vehicle
• File: src/app/(main)/logistics/vehicle/page.tsx
• Features:
  • Manage vehicle list for shipments.
  • Fields include vehicle number, type, status, driver info.
  • Search/filter support.
• Data:
  • localStorage.logistics_vehicles

4.6.2 Shipments List

• Route: /logistics/shipment
• File: src/app/(main)/logistics/shipment/page.tsx
• Features:
  • List all shipments with basic info (vehicle, driver, destination, fare, status).
  • Actions to view, edit, and delete shipments.
• Data:
  • localStorage.logistics_shipments

4.6.3 New Shipment

• Route: /logistics/shipment/new
• File: src/app/(main)/logistics/shipment/new/page.tsx
• Features:
  • Create shipment:
    • Vehicle (from logistics_vehicles)
    • Driver (from employees where role is “Driver”)
    • Destination and contact details
    • Fare (input with IndianRupee icon, stored as number)
    • Status and timing (out/in time)
• Data:
  • Persists as new entry in localStorage.logistics_shipments.

4.6.4 Edit Shipment

• Route: /logistics/shipment/[id]
• File: src/app/(main)/logistics/shipment/[id]/page.tsx
• Features:
  • Loads shipment from logistics_shipments by id.
  • Editing same fields as creation:
    • Vehicle, driver, destination, fare, status, timings, destination contacts.
  • Fare input also uses IndianRupee icon.

---

4.7 Employees

4.7.1 Employee Management

• Route: /employees
• File: src/app/(main)/employees/page.tsx
• Model:
  • EmployeeType = 'Salaried' | 'Daily Wage'
  • Employee fields:
    • id, name, email, phone
    • type, department, role
    • salary? (salaried), dailyRate? (daily wage)
    • status (Active/Inactive)
    • joinDate
• Features:
  • Table view:
    • Name, role, department, contact, compensation, status, actions.
  • Compensation display:
    • Salaried: ₹{salary.toLocaleString("en-IN")}/yr
    • Daily wage: ₹{dailyRate.toLocaleString("en-IN")}/day
  • Add/Edit dialog:
    • Type, department, status, role, contact info, join date.
    • Compensation input with IndianRupee icon.
• Data:
  • localStorage.employees
  • Initial mock employees are seeded if storage is empty.

4.7.2 Attendance

• Route: /employees/attendance
• File: src/app/(main)/employees/attendance/page.tsx
• Features:
  • Calendar-style attendance matrix for the selected month.
  • Per‑employee, per‑day status:
    • Present, Absent, Late, Half-Day, Left Early
  • Bulk operations:
    • Mark all visible employees Present for a specific day, etc.
• Data:
  • Stored in localStorage.attendance_records
  • Used later by Employee Payout and Salary Slip.

---

4.8 Suppliers

4.8.1 Suppliers List

• Route: /suppliers
• File: src/app/(main)/suppliers/page.tsx
• Features:
  • List of suppliers with contact information.
  • Links to supplier detail pages.

4.8.2 New Supplier

• Route: /suppliers/new
• File: src/app/(main)/suppliers/new/page.tsx
• Features:
  • Create supplier with name, contact info, and supplied products.
  • On save:
    • Updates localStorage.suppliers.
    • Can also impact inventory_products depending on form logic.

4.8.3 Supplier Detail

• Route: /suppliers/[id]
• File: src/app/(main)/suppliers/[id]/page.tsx
• Features:
  • Show supplier details and associated purchase/orders.
  • Edit or delete supplier.
• Data:
  • localStorage.suppliers

---

4.9 Clients

4.9.1 Active Clients

• Route: /clients
• File: src/app/(main)/clients/page.tsx
• Features:
  • List all active clients with avatars, names, emails, and phones.
  • Link to client profile.

4.9.2 Client Detail

• Route: /clients/[clientId]
• File: src/app/(main)/clients/[clientId]/page.tsx
• Features:
  • Shows full client information and activity.
  • Quick actions:
    • mailto: (open email)
    • tel: (phone)

4.9.3 Inactive Clients

• Route: /clients/inactive
• File: src/app/(main)/clients/inactive/page.tsx
• Features:
  • Displays clients marked inactive.

4.9.4 New Client

• Route: /clients/new
• File: src/app/(main)/clients/new/page.tsx
• Uses:
  • src/components/client-form.tsx for the form logic.
• Data:
  • Persists to localStorage.clients.

---

4.10 Purchase

4.10.1 Purchase Orders Management

• Route: /purchase/purchase-management
• File: src/app/(main)/purchase/purchase-management/page.tsx
• Features:
  • List purchase orders with status (Pending/Ordered/Received/Cancelled).
  • Status changes:
    • Messages like:
      • “Order marked as RECEIVED. Inventory updated.”
      • or “Order status changed to .”
• Data:
  • localStorage.purchase_orders

4.10.2 Create Purchase Order

• Route: /purchase/create-order
• File: src/app/(main)/purchase/create-order/page.tsx
• Features:
  • Build PO with items and supplier selection.
  • Generates order number:
    • PO-YYYYMMDD-XXX (with numeric suffix).
  • Persists to localStorage.purchase_orders.
  • Integrates with inventory stocks if configured.

---

4.11 Settings

• Route: /settings
• File: src/app/(main)/settings/page.tsx
• Features:
  • Company Profile:
    • Name, address, logo, contact information.
    • Stored as localStorage.company_settings.
    • Used by invoice and quotation templates.
  • Default Currency:
    • Bound to CurrencyCode from currency-context.tsx (INR only).
  • Default Payment Terms:
    • “Due on Receipt”, “Net 15”, “Net 30”, “Net 60”.

---

5. Data Persistence Overview

Main localStorage keys:

• employees
• attendance_records
• employee_salary_structures
• invoices
• recurringInvoices
• manual_incomes
• expenses
• recurring_expenses
• inventory_products
• inventory_categories
• purchase_orders
• logistics_vehicles
• logistics_shipments
• suppliers
• clients / inactive_clients
• company_settings
• customInvoiceTemplates

Data is browser-local. Clearing browser storage or moving to a new browser will reset all these records (except built-in static seed data).

---

6. Development & Extension Notes

6.1 Running the App

Standard Next.js commands:

npm install
npm run dev

Note for Windows: if npm run build or npm run lint scripts use Unix-style environment variable syntax (NODE_ENV=production), you may need to adapt them (e.g. using cross-env) to run successfully on Windows terminals.

6.2 Adding New Features

When extending the application:

• Place new pages under src/app/(main)/<module>/page.tsx.
• Add the route into src/app/(main)/layout.tsx sidebar.
• Persist data in a clearly named localStorage key.
• For any monetary values:
  • Use useCurrency().formatCurrency(amount) where practical, or
  • Use ₹${amount.toLocaleString("en-IN")} for manual rendering.

This keeps the experience consistent for Indian business users and aligned with the existing implementation.