PulseOS

AI-Powered MSME Credit Intelligence & Decision Support Platform

PulseOS is a modern, internal banking platform designed for Credit Officers, Branch Managers, and Risk Teams to evaluate Micro, Small, and Medium Enterprises (MSMEs). By aggregating alternate financial data (GST, UPI, Banking, EPFO) and leveraging AI-powered underwriting, PulseOS enables objective, data-driven credit decisions while maintaining full transparency and auditability.

---

🛡️ Badges

---

📋 Table of Contents

1. Problem Statement
2. Solution
3. Key Features
4. System Architecture
5. Complete Workflow
6. Screenshots
7. Technology Stack
8. Repository Structure
9. Installation
10. Running the Project
11. Environment Variables
12. AI Architecture
13. Explainability
14. Portfolio Dashboard
15. Feature Store
16. Roadmap
17. Future Improvements
18. Security
19. Performance
20. Testing
21. Contributing
22. License
23. Acknowledgements

---

🚨 Problem Statement

Traditional MSME underwriting relies heavily on manual document verification, outdated credit bureau scores, and rigid heuristic rules. This approach fails to capture the true operational health of New-to-Credit businesses, leading to a massive financial inclusion gap.

Without utilizing real-time, high-frequency alternative data (such as digital payments, tax filings, and payroll consistency), banks often reject healthy businesses or misprice risk. PulseOS exists to bridge this gap by bringing modern data integration and AI-driven intelligence into the credit officer's daily workflow.

---

💡 Solution

PulseOS solves the MSME credit gap by transforming raw alternate data into actionable intelligence.

Instead of manual spreadsheet analysis, PulseOS automatically aggregates data to generate Financial Intelligence indicators. These indicators feed into a Hybrid Risk Engine, producing comprehensive risk grades and recommendations. To ensure transparency, the platform features robust AI Explainability, generating human-readable credit memos using local LLMs, and an Evidence Explorer to trace every AI decision back to the raw source data. For management, the Portfolio Dashboard provides a macro-view of the bank's entire MSME pipeline.

---

⭐ Key Features

Feature	Description	Status
Authentication	Secure JWT-based employee login and RBAC.	✅ Implemented
Applicant Lookup	Search and verify MSME identities via GSTIN/PAN.	✅ Implemented
Assessment Workspace	Centralized hub for managing the underwriting lifecycle.	✅ Implemented
Data Integration	Simulated ingestion of GST, UPI, Bank, and EPFO data.	✅ Implemented
Financial Intelligence	Converts raw data into financial, operational, and compliance indicators.	✅ Implemented
Risk Assessment	Hybrid heuristic scoring engine providing financial health and risk scores.	✅ Implemented
Recommendation Engine	Generates loan term suggestions and automated decisions.	✅ Implemented
AI Explainability	Uses Ollama to generate Executive Summaries and Credit Memos.	✅ Implemented
Evidence Explorer	Visualizes the decision lineage and traces AI outputs to source data.	✅ Implemented
Report Engine	Generates downloadable PDF risk reports for compliance.	✅ Implemented
Portfolio Dashboard	Macro-level view of MSME assessments for managers.	✅ Implemented
MongoDB Persistence	Document-oriented storage for nested assessment architectures.	✅ Implemented
Feature Store	Prepares flattened feature vectors for future ML training pipelines.	✅ Implemented

---

🏗️ System Architecture

graph TD
UI[Frontend: Next.js + React] --> API[Backend: FastAPI]
API --> Services[Service Layer]
subgraph Core Modules
Services --> FI[Financial Intelligence]
FI --> Risk[Risk Engine]
Risk --> Rec[Recommendation Engine]
Rec --> AI[AI Explainability]
end
AI --> Ollama[(Ollama Local LLM)]
Services --> DB[(MongoDB)]
Services --> FS[(Feature Store)]
DB -.-> Evidence[Evidence Explorer]
DB -.-> Reports[PDF Report Engine]

Loading

---

🔄 Complete Workflow

1. Employee Login: Secure authentication via JWT.
2. Applicant Search: Officer searches for MSME using PAN or GSTIN.
3. Assessment Creation: A new underwriting assessment is instantiated.
4. Consent Verification: Verification of borrower data sharing consent.
5. Data Collection: Simulated fetching of alternate data packages (GST, UPI, etc.).
6. Financial Intelligence: Raw data parsed into standardized financial indicators.
7. Risk Assessment: Heuristic models calculate financial health and risk grades.
8. Recommendation: Automated suggestions for loan terms based on risk.
9. AI Explainability: Ollama summarizes findings into a human-readable Credit Memo.
10. Evidence Explorer: Officer reviews the trace lineage for every AI statement.
11. Officer Notes: Manual insights appended to the assessment workspace.
12. Report Generation: Final PDF report generated for internal auditing.
13. Portfolio Dashboard: Aggregated metrics update in real-time for branch managers.

---

🖼️ Screenshots

Note: UI screenshots will be added here.

🔐 Login

[Placeholder: Screenshot of the JWT Login screen]

📊 Portfolio Dashboard

[Placeholder: Screenshot of the Macro Analytics and KPI Charts]

📂 Assessment Workspace

[Placeholder: Screenshot of the main underwriting hub]

🧠 Financial Intelligence

[Placeholder: Screenshot of indicators and data points]

📉 Risk Dashboard

[Placeholder: Screenshot of risk grades, scores, and drivers]

🤖 AI Explainability

[Placeholder: Screenshot of the generated Credit Memo]

🔍 Evidence Explorer

[Placeholder: Screenshot of the decision lineage graph]

📄 PDF Report

[Placeholder: Screenshot of the generated PDF download]

---

💻 Technology Stack

Backend

Technology	Purpose
Python 3.12	Core programming language
FastAPI	High-performance API framework
Pydantic	Data validation and schema definition
PyMongo / Motor	MongoDB database drivers
PyJWT	Secure authentication
ReportLab	PDF document generation

Frontend

Technology	Purpose
Next.js (App Router)	React framework for SSR and routing
TypeScript	Static typing for frontend stability
Tailwind CSS	Utility-first styling framework
Recharts	Interactive data visualization
Lucide React	Consistent SVG iconography
Axios	API request client

Infrastructure & AI

Technology	Purpose
MongoDB	Primary NoSQL document database
Ollama	Local LLM inference engine (Explainability)
Docker	Containerization (Optional)
Pytest	Backend testing framework

---

📁 Repository Structure

pulseos/
├── backend/
│ ├── ai/ # AI integrations (Ollama, Prompt Builders)
│ ├── app/ # Main FastAPI Application
│ │ ├── api/ # Route Definitions (v1)
│ │ ├── core/ # Config, Security, Middleware, Logging
│ │ ├── db/ # MongoDB Repositories
│ │ ├── schemas/ # Pydantic Models
│ │ └── services/ # Business Logic (Risk, FI, Reports, etc.)
│ ├── config/ # Centralized Configuration
│ ├── ml/ # Feature Store & ML Pipelines
│ ├── tests/ # Pytest Unit & Integration Tests
│ ├── seed_mongodb.py # Database Population Script
│ └── requirements.txt # Python Dependencies
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js Pages and Routing
│ │ ├── components/ # Reusable React Components (Assessments, Workspace, etc.)
│ │ ├── services/ # API Client Integration
│ │ └── lib/ # Utility Functions
│ ├── package.json # Node Dependencies
│ └── tailwind.config.js # Styling Configuration
└── README.md # Project Documentation

---

🛠️ Installation

1. MongoDB

Ensure you have MongoDB running locally or accessible via a cluster.

# Example for starting MongoDB via Docker
docker run -d -p 27017:27017 --name pulseos-mongo mongo:7.0

2. Ollama

Install Ollama from ollama.com and pull the necessary model.

ollama run llama3
# Note: Keep the Ollama service running in the background.

3. Backend Setup

Navigate to the backend directory and set up the Python environment.

cd backend
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Macsource venv/bin/activate
pip install -r requirements.txt

4. Frontend Setup

Navigate to the frontend directory and install dependencies.

cd frontend
npm install

---

🚀 Running the Project

1. Seed the Database

Populate MongoDB with demo employee and applicant data.

cd backend
python seed_mongodb.py

2. Start the Backend Server

Run the FastAPI application.

cd backend
uvicorn app.main:app --reload --port 8000

Health Check: Navigate to http://localhost:8000/api/v1/health

3. Start the Frontend Server

Run the Next.js development server.

cd frontend
npm run dev

Access: Navigate to http://localhost:3000

---

⚙️ Environment Variables

Create .env files in both backend and frontend directories as needed.

Backend (backend/.env)

Variable	Description	Default
MONGODB_URI	Connection string for MongoDB	mongodb://localhost:27017
DATABASE_NAME	Name of the primary database	pulseos
JWT_SECRET	Secret key for JWT signing	change_me_in_production
OLLAMA_URL	Local API endpoint for Ollama	http://localhost:11434
OLLAMA_MODEL	LLM model to use for AI explanations	llama3
LOG_LEVEL	Application logging level	INFO
ENVIRONMENT	Running environment	development

---

🧠 AI Architecture

PulseOS employs a structured "RAG-lite" pipeline for explainability without relying on the LLM for mathematical decision-making.

graph LR
FI[Financial Intelligence] --> Package[Assessment Package]
Risk[Risk Engine] --> Package
Rec[Recommendation] --> Package
Package --> Builder[Prompt Builder]
Builder --> Ollama[(Ollama)]
Ollama --> Output[Exec Summary & Credit Memo]
Output --> Evidence[Evidence Explorer]

Loading

The AI module's sole responsibility is translation. It converts complex, multi-dimensional JSON risk outputs into cohesive, human-readable banking narratives.

---

🔎 Explainability

To ensure compliance and auditability, PulseOS implements a strict Evidence Explorer:

• Decision Traceability: Every statement generated by the AI or Risk Engine is traced back to a specific node (e.g., "Revenue dropped by 10%" traces back to GST_Return_Q3).
• Confidence Scoring: The system calculates data sufficiency and source reliability to append confidence metrics to every recommendation.
• AI Transparency: Users can view the exact JSON payload and prompt fed to Ollama to verify that no hallucination occurred.

---

📈 Portfolio Dashboard

The Portfolio Intelligence module provides a Macro View of the bank's MSME pipeline:

• KPIs: Total MSMEs, Average Financial Health, Assessment Completion Rates.
• Charts: Risk Distributions, Assessment Trends, and Industry breakdowns.
• Alerts: Automated flags for businesses sitting in high-risk categories or delayed reviews.
• Portfolio AI Summary: A real-time, LLM-generated executive summary of the entire branch's performance over the last 30 days.

---

🗃️ Feature Store

PulseOS prepares for the future by implementing a Feature Store.

• Feature Vector: Highly nested JSON documents are flattened into numerical feature vectors.
• Training Dataset: Automated pipeline to export .csv datasets.
• Future ML Pipeline: Once sufficient labeled ground-truth data is collected, the current heuristic Rules Engine will be replaced by a trained Machine Learning classifier (XGBoost/RandomForest).

---

🗺️ Roadmap

Feature	Status	Description
Heuristic Risk Engine	✅ Completed	Rules-based scoring using alternate data.
Local LLM Integration	✅ Completed	Ollama-based explainability memos.
Portfolio Analytics	✅ Completed	Macro-level dashboard for managers.
Real ML Training	🚧 Future	Train Scikit-Learn models using Feature Store data.
Live API Integrations	🚧 Future	Connect to actual GSTN, Account Aggregator, and EPFO APIs.
CI/CD Pipeline	🚧 Future	Automated testing and deployment workflows.
Kubernetes Deployment	🚧 Future	Container orchestration for enterprise scalability.

---

🔮 Future Improvements

• Integration with OCEN (Open Credit Enablement Network).
• Integration with Account Aggregator frameworks.
• Advanced cash-flow based lending predictive models.
• OCR integration for automated bank statement parsing.
• Automated deployment scripts via Terraform/Ansible.

---

🔐 Security

• JWT Authentication: Stateless, secure token-based login.
• RBAC (Role-Based Access Control): Differentiates permissions between Credit Officers, Branch Managers, and Administrators.
• Audit Logs: Immutable tracking of status changes and manual overrides embedded directly into the Assessment document.
• Traceable Request IDs: Every API request is stamped with a Correlation ID for centralized logging and debugging.

---

⚡ Performance

• Denormalized Database: MongoDB allows fetching an entire assessment (Risk, FI, Recommendations, AI Memos) in a single highly-optimized query.
• Structured Logging: Centralized JSON logging ready for ELK/Datadog ingestion.
• Health Monitoring: Dedicated /health endpoint tracking database latency and system uptime.

---

🧪 Testing

PulseOS ensures reliability through rigorous testing:

• Unit Tests: Independent testing of FI parsers, Risk models, and Feature Builders.
• Integration Tests: End-to-end testing of the FastAPI routes, MongoDB repositories, and lifecycle webhooks.
• Command:python -m pytest tests/ -v

---

🤝 Contributing

1. Clone the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Ensure all tests pass (pytest tests/).
4. Commit your changes following conventional commits.
5. Push to the branch and open a Pull Request.

---

📜 License

This project is licensed under the MIT License.

---

🙏 Acknowledgements

PulseOS is built on the shoulders of giants. Special thanks to:

• FastAPI for an incredible backend framework.
• MongoDB for flexible, document-oriented persistence.
• Next.js & React for the UI foundation.
• Ollama for democratizing local AI.
• Recharts & Lucide for beautiful visuals and icons.
• ReportLab for robust PDF generation.