Building an AI-Powered Financial Wellness Assistant with Node.js and TypeScript

Introduction

What if employees could instantly understand their payslip, deductions, and tax-saving opportunities without bothering HR or Payroll teams?

In this post, I'll walk you through building a secure AI-powered financial wellness assistant that does exactly that. This system analyzes both structured payroll data and uploaded payslip documents, then provides document-grounded explanations in simple, employee-friendly language.

---

The Problem We're Solving

Employees frequently find payslips difficult to interpret because salary components, statutory deductions, reimbursements, and year-to-date values are often presented in a compact and technical format. This creates repeated queries for Payroll, HR, and Finance teams.

Common employee questions:

• "Why is my net salary lower this month?"
• "How much HRA did I receive?"
• "What deductions were applied?"
• "How can I save more tax?"

The objective is to reduce operational load by providing instant, personalized, and document-aware responses while maintaining strict user-level privacy for sensitive financial information.

---

What We Built

A complete AI-powered financial wellness assistant with:

• Secure Authentication - JWT-based authentication with role-based access control
• Payslip Processing - Upload PDF or images, extract data using AI vision capabilities
• AI-Powered Q&A - Ask natural language questions with grounded responses
• Tax Simulation - See impact of additional investments on tax liability
• Investment Checklist - Personalized proof submission checklist
• YTD Summary - Year-to-date salary and tax summary
• Trend Analysis - Salary comparison across months
• Salary Breakdown - Detailed view of earnings and deductions

---

Technology Stack

Layer	Technology
Backend	Node.js, Express.js, TypeScript
AI Integration	LLM Wrapper API (Gemini/Claude models)
Frontend	HTML, CSS, JavaScript (Vanilla)
Security	JWT, Role-Based Access Control
Testing	Jest
API Documentation	Postman

---

System Architecture

┌─────────────────────────────────────────────────────┐
│              Frontend (HTML/CSS/JS)                 │
│              http://localhost:3000                  │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────┐
│              Express.js API Server                  │
│  ┌──────────────────────────────────────────────┐  │
│  │  Routes Layer (auth/payslip/tax/query)      │  │
│  └──────────────┬───────────────────────────────┘  │
│  ┌──────────────▼───────────────────────────────┐  │
│  │  Middleware (Auth/RBAC/RateLimit)           │  │
│  └──────────────┬───────────────────────────────┘  │
│  ┌──────────────▼───────────────────────────────┐  │
│  │  Core Services (Payroll/Tax/Document)       │  │
│  └──────────────┬───────────────────────────────┘  │
│  ┌──────────────▼───────────────────────────────┐  │
│  │  External Services (LLM Wrapper API)        │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

---

Project Structure

financial-wellness-ai-agent/
├── src/
│   ├── config/               # Configuration files
│   │   └── llm.config.ts
│   ├── core/                 # Core business logic
│   │   ├── payroll.service.ts
│   │   ├── tax.service.ts
│   │   └── document.service.ts
│   ├── models/               # Data models
│   │   └── index.ts
│   ├── security/             # Authentication and authorization
│   │   └── auth.middleware.ts
│   ├── services/             # External service integrations
│   │   └── llm.service.ts
│   ├── routes/               # API routes
│   │   ├── auth.routes.ts
│   │   ├── payslip.routes.ts
│   │   ├── tax.routes.ts
│   │   └── query.routes.ts
│   ├── prompts/              # AI prompt engineering
│   │   └── grounding.prompts.ts
│   ├── utils/                # Helpers and utilities
│   │   ├── logger.ts
│   │   └── error-handler.ts
│   ├── data/                 # Mock data
│   │   └── mock-data.ts
│   ├── app.ts                # Express app setup
│   └── server.ts             # Server entry point
├── public/                   # Static frontend files
│   └── index.html
├── tests/                    # Unit and integration tests
│   ├── unit/
│   └── integration/
├── contrib/                  # Contribution files
│   ├── postman_collection.json
│   └── postman_environment.json
├── .env.example              # Environment variables template
├── package.json
├── tsconfig.json
└── README.md

---

Key Features Explained

1. Secure Authentication

JWT-based authentication with role-based access control ensures that employees can only access their own data.

export const authenticate = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'Unauthorized' });

  const decoded = verifyToken(token);
  req.user = { id: decoded.userId, role: decoded.role };
  next();
};

2. AI-Powered Document Processing

The system uses AI vision to extract structured data from payslip documents:

export const EXTRACT_PAYSLIP_PROMPT = `
You are a payroll data extraction assistant. Analyze the provided payslip document 
and extract the following fields in a valid JSON format.

Fields to extract:
- basicSalary (number)
- hra (number)
- pf (number)
- tds (number)
- grossPay (number)
- netPay (number)
- month (string)
`;

3. Grounded AI Responses

All AI responses are grounded in the user's actual payroll data to prevent hallucinations:

export const GROUNDED_QUERY_PROMPT = (userQuery, userData) => `
You are an employee-friendly financial wellness assistant.

STRICT GROUNDING RULES:
1. ONLY use information present in the provided data
2. If information is missing, say: "I don't have enough information"
3. DO NOT invent figures, tax rules, or financial advice
4. Use simple, clear language

USER'S DATA: ${JSON.stringify(userData)}

USER'S QUESTION: ${userQuery}
`;

4. Tax Simulation

Simplified tax calculation with simulation capabilities:

export class TaxService {
  private static readonly TAX_SLABS = [
    { limit: 250000, rate: 0 },
    { limit: 500000, rate: 0.05 },
    { limit: 1000000, rate: 0.20 },
    { limit: Infinity, rate: 0.30 },
  ];

  static simulateInvestment(records, additionalInvestment) {
    const annualIncome = this.calculateAnnualIncome(records);
    const currentTax = this.calculateTax(annualIncome, currentDeductions);
    const proposedTax = this.calculateTax(annualIncome, currentDeductions + additionalInvestment);

    return {
      taxSavings: currentTax.totalTax - proposedTax.totalTax,
      roi: (savings / additionalInvestment) * 100
    };
  }
}

---

API Endpoints Overview

Authentication

Method	Endpoint	Description
POST	/api/auth/login	Login user

Payslip Management

Method	Endpoint	Description
POST	/api/payslip/upload	Upload payslip
GET	/api/payslip/records	Get all records
GET	/api/payslip/ytd	YTD summary
POST	/api/payslip/compare	Compare months

AI Queries

Method	Endpoint	Description
POST	/api/query/ask	Ask AI question
POST	/api/query/explain	Explain component

Tax Services

Method	Endpoint	Description
GET	/api/tax/summary	Tax summary
POST	/api/tax/simulate	Tax simulation
GET	/api/tax/checklist	Investment checklist

---

Demo Walkthrough

1. Login

POST /api/auth/login
{
  "email": "[e-mail]",
  "password": "demo123"
}

2. Ask AI Question

POST /api/query/ask
{
  "question": "How much HRA did I receive?"
}

Response:

Your HRA (House Rent Allowance) breakdown:

Latest Month (June 2026):
- HRA Received: ₹19,553
- HRA Exemption (tax-free): ₹9,777

Month-by-Month Summary:
- June 2026: ₹19,553
- May 2026: ₹19,740
- April 2026: ₹20,649
- Total YTD: ₹1,21,493

3. Tax Simulation

POST /api/tax/simulate
{
  "additionalInvestment": 50000
}

Response:

Tax Savings Simulation:

Additional Investment: ₹50,000
Current Tax: ₹1,820
Proposed Tax: ₹1,450
Tax Savings: ₹370 (annual)
ROI: 0.74%

---

Installation and Setup

# Clone the repository
git clone [e-mail]:mohin-sheikh/ai-financial-assistant.git
cd ai-financial-assistant

# Install dependencies
npm install

# Create environment file
cp .env.example .env

# Add your LLM API token to .env
LLM_API_TOKEN=your_token_here

# Build the project
npm run build

# Start the server
npm start

# Or development mode with auto-reload
npm run dev

---

Demo Credentials

Role	Email	Password
Employee	[e-mail]	demo123
Admin	[e-mail]	admin123

---

Testing

# Run all tests
npm test

# Run tests with watch mode
npm run test:watch

# Run specific test file
npm test -- tests/unit/tax.service.test.ts

---

Security Features

• JWT-based authentication with expiry
• Role-based access control (Employee, Admin, Payroll)
• User-level data isolation
• Rate limiting (100 requests per 15 minutes)
• Audit logging for all user actions
• Input validation and sanitization
• Helmet.js for security headers

---

Postman Collection

A complete Postman collection is available in the contrib/ directory:

• postman_collection.json - All API endpoints with examples
• postman_environment.json - Environment variables for testing

To import:

1. Open Postman
2. Click "Import"
3. Select the JSON files from contrib/
4. Select the environment
5. Run "Login - Employee" first to get the token

---

Key Learnings and Takeaways

1. AI Grounding is Critical

Always ground AI responses in actual user data. This prevents hallucinations and builds trust.

2. Security First

Financial data requires strict user-level isolation, JWT authentication, and audit logging.

3. Simple Tax Logic

For prototypes, simplified tax logic is acceptable as long as assumptions are clearly documented.

4. User-Friendly Language

Translate technical payroll jargon into simple, employee-friendly explanations.

5. Document Grounding

Use AI vision capabilities to extract structured data from unstructured documents.

---

Challenges and Solutions

Challenge 1: Preventing AI Hallucinations

Solution: Strict grounding prompts that force the AI to only use provided data.

Challenge 2: Document Extraction Accuracy

Solution: Combined regex fallback with AI vision for better extraction.

Challenge 3: User Data Isolation

Solution: JWT-based authentication with middleware that checks data ownership.

Challenge 4: Time Constraint (1 Hour)

Solution: Prioritized core features over production polish, used mock data instead of real database.

---

Future Enhancements

• [ ] Persistent database (PostgreSQL/MongoDB)
• [ ] Real OCR integration (Tesseract/Google Vision)
• [ ] Multi-month comparison charts
• [ ] PDF payslip generation
• [ ] Email notifications for tax deadlines
• [ ] Mobile responsive UI
• [ ] Export to Excel/CSV
• [ ] Advanced tax rules (new/old regime)
• [ ] Multi-company support
• [ ] Dashboard with visual analytics

---

GitHub Repository

Star, Fork, and Contribute: https://github.com/mohin-sheikh/ai-financial-assistant

git clone [e-mail]:mohin-sheikh/ai-financial-assistant.git
cd ai-financial-assistant
npm install
npm run dev

---

Conclusion

Building an AI-powered financial wellness assistant demonstrates how AI can be safely and practically applied in an internal employee-finance use case where trust, correctness, and privacy are critical.

The system provides instant, personalized, and document-aware responses while maintaining strict user-level privacy for sensitive financial information. This prototype showcases:

• AI-powered document understanding
• Grounded responses with no hallucinations
• User-friendly explanations
• Secure data handling
• Scalable architecture

---

Share Your Thoughts

I'd love to hear your feedback! Have you built something similar? What features would you add?

• GitHub: mohin-sheikh
• LinkedIn: mohin-sheikh

---