AI-Based Financial Reporting System for Ngenda Primary School

This is the final project guide for installation, setup, roles, AI features, and running the system.

Overview

This project is a full-stack financial management system for Ngenda Primary School built with:

• Frontend: HTML, Bootstrap 5, Vanilla JavaScript
• Backend: Node.js, Express
• Database: MongoDB with Mongoose
• Authentication: JWT
• PDF Export: Puppeteer
• AI: local rule-based, explainable financial intelligence

The frontend is served directly by the backend, so one application command runs the whole system.

Required Tools

Install these before running the project:

• Node.js
• npm
• MongoDB
• a browser like Google Chrome, Microsoft Edge, or Firefox

Recommended:

• VS Code
• MongoDB Compass

Project Structure

Ai financial/
├── backend/
│   ├── controllers/
│   ├── middleware/
│   ├── models/
│   ├── routes/
│   ├── services/
│   ├── templates/
│   ├── utils/
│   └── server.js
├── frontend/
│   ├── css/
│   ├── js/
│   ├── audit-logs.html
│   ├── dashboard.html
│   ├── expense.html
│   ├── income.html
│   ├── login.html
│   ├── receipts.html
│   ├── reports.html
│   ├── settings.html
│   ├── transactions.html
│   └── users.html
├── .env
├── .env.example
├── package.json
└── README.md

Main Features

• JWT authentication
• role-based access control
• dashboard with summary cards and Chart.js
• income recording
• expense management
• transactions page with filters
• receipts page with reopen and print
• financial report generation
• real PDF export using Puppeteer
• audit logging
• school settings
• AI-based categorization
• anomaly detection
• AI report narratives
• budget deviation AI
• recurring transaction detection
• data quality score
• self-service password change
• admin password reset

User Roles

Admin

Responsibilities:

• manage users
• assign roles
• activate or deactivate users
• reset passwords for users
• view all financial data
• view reports
• view anomaly alerts
• view audit logs
• configure school settings

Restrictions:

• cannot create income
• cannot create expense
• cannot edit financial transactions
• cannot delete financial transactions

Accountant

Responsibilities:

• review and correct existing income records
• create, edit, and manage expenses
• review anomaly flags
• generate reports
• export PDF reports
• change own password

Restrictions:

• cannot create new cashier-style income entries
• cannot manage users
• cannot reset other users’ passwords
• cannot change school settings

Cashier

Responsibilities:

• record incoming payments
• receive AI category suggestions
• generate receipts
• print receipts
• view own payment history
• view own receipts
• change own password

Restrictions:

• cannot manage expenses
• cannot edit old income records
• cannot delete old income records
• cannot manage users
• cannot access audit logs
• cannot access reports
• cannot change school settings

Explainable AI Features

This system uses only local, rule-based AI logic. No external AI APIs are used.

Smart Categorization

• suggests a category from description keywords
• shows confidence level
• examples:
  • school fees payment -> Fees
  • electricity bill -> Utilities

Anomaly Detection

• duplicate transaction detection
• zero or negative amount detection
• missing required fields detection
• category mismatch detection
• unusual expense detection using historical category averages

Smart Report Summary

• generates summary text from:
  • income
  • expenses
  • balance
  • previous period comparison
  • anomaly count

Budget Deviation AI

• compares expense totals against predefined thresholds
• highlights categories that are over or under expected budget

Recurring Transaction Detection

• detects repeated transactions with similar name, category, and amount

Data Quality Score

• gives a score out of 100
• score is based on:
  • anomaly count
  • high severity issues
  • duplicates
  • missing fields

Environment File

The project uses .env.

Current configuration:

PORT=5000
MONGO_URI=mongodb://127.0.0.1:27017/ngenda-financial-reporting
JWT_SECRET=supersecretjwtkey
JWT_EXPIRES_IN=1d

Installation

Open terminal in:

c:\Users\TEMP.KAMANZI11\Desktop\Ai financial

Install dependencies:

npm install

Seed Demo Data

Run:

npm run seed

This creates:

• demo users
• initial settings
• sample income
• sample expense
• sample receipt

Demo Accounts

• admin@ngenda.com / password123
• accountant@ngenda.com / Password123@
• cashier@ngenda.com / password123

Run The Project

Best option

Run:

npm run app

This will:

• start the backend
• serve the frontend
• open the browser automatically to the login page

Manual option

Run:

npm run dev

Then open:

http://localhost:5000/login.html

Important Pages

• Login
• Dashboard
• Income
• Expenses
• Transactions
• Receipts
• Reports
• Users
• Audit Logs
• Settings

Receipt Workflow

When a cashier records a payment:

1. AI suggests category
2. AI checks duplicates and suspicious fields
3. receipt number is generated
4. receipt opens automatically
5. receipt can be printed immediately

Receipts can later be reopened and printed from:

• Income page
• Receipts page

Report Workflow

When an accountant or admin generates a report:

1. report period is selected
2. totals are calculated from MongoDB data
3. anomalies are counted
4. AI summary is generated
5. data quality score is generated
6. budget deviation and recurring pattern insights are shown
7. PDF can be downloaded through Puppeteer

Password Management

Self-service password change

All logged-in users can change their own password from:

• Settings page

Requirements:

• current password
• new password
• password confirmation

Admin password reset

Admin can reset any user password from:

• Users page

This is useful for:

• forgotten password
• account recovery
• temporary password assignment

PDF Generation

PDF generation is real server-side PDF generation using Puppeteer.

Main route:

GET /api/reports/:id/pdf

PDF includes:

• school header
• logo if available
• report title
• selected date range
• total income
• total expenses
• net balance
• category breakdown
• flagged anomalies
• AI summary
• generation date
• generating user

Commands Summary

Install:

npm install

Seed:

npm run seed

Run and open browser automatically:

npm run app

Run backend manually:

npm run dev

Notes

• MongoDB must be running before seeding or starting the app
• the frontend is served by the backend
• no separate frontend server is required
• npm run app is the easiest command for demos and presentation