Vyapar AI - Daily Business Health Companion for Small Shop Owners

🏆 AWS Hackathon Submission - AI for Retail, Commerce & Market Intelligence

Executive Summary

Vyapar AI transforms small shop owners' daily business tracking from manual guesswork into intelligent, actionable insights. Built on a Hybrid Intelligence Architecture (governed by vyapar-rules.md), it combines deterministic financial calculations (always correct, always offline) with AWS Bedrock-powered explanations (context-aware, persona-adapted) to create India's first daily business health companion for 60+ million small retailers.

Core Innovation: "Deterministic numbers first → AI interprets → User takes action"

🎯 Architecture Philosophy: Hybrid Intelligence (Governed by vyapar-rules.md)

The Problem with Pure AI Solutions

Traditional AI tools compute everything, creating:

Black box decisions (unexplainable results)
Network dependency (fails offline) - violates §1.2: No network dependency rule
Unreliable calculations (AI hallucinations in finance) - violates §1.2: No AI dependency for financial metrics rule
High latency (slow API calls for simple math)

Our Solution: Deterministic-First Architecture (Code-Enforced Rules)

┌─────────────────────────────────────────────────────────┐
│                 HYBRID INTELLIGENCE MODEL               │
├─────────────────────────────────────────────────────────┤
│  🎯 DETERMINISTIC CORE (Authoritative Layer)            │
│  • Health Score (0-100) - /lib/finance/calculations.ts  │
│  • Stress & Affordability Indices - /lib/finance/       │
│  • Margin Calculations - Pure TypeScript functions      │
│  • Daily Suggestions Engine - Rule-based only (§A1)     │
│  • Credit Follow-up Logic - Fully offline capable       │
│                                                         │
│  ✅ ARCHITECTURE RULES (Enforced from vyapar-rules.md): │
│  • No AI dependency for financial metrics (§1.2)        │
│  • No network dependency for core calculations (§1.2)   │
│  • Fully offline capable (§4)                           │
│  • Fully unit testable with PBT (§7)                    │
│  • No side effects in deterministic functions (§1.2)    │
└─────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────┐
│  🤖 AI ENHANCEMENT LAYER (Interpretation Only)          │
│  • Explain computed metrics in native language          │
│  • Provide persona-aware advice (§A3)                   │
│  • Adjust explanation complexity (§A4)                  │
│  • Summarize financial state                            │
│  • Answer business questions                            │
│                                                         │
│  🚫 AI MUST NEVER (Architecture Enforcement §1.2):      │
│  • Calculate financial metrics                          │
│  • Replace deterministic logic                          │
│  • Store core business state                            │
└─────────────────────────────────────────────────────────┘

Key Architecture Decisions (Reference: vyapar-rules.md sections):

§1.2 Hybrid Intelligence Principle: Strict separation of deterministic core from AI layer
§3.1 DynamoDB Single-Table Design: PK = USER#{user_id}, SK = TYPE#{entity_type}#{timestamp}
§3.2 Session Store in DynamoDB: No in-memory session storage, PK = SESSION#{session_id}
§4 Offline-First Strategy: localStorage for daily entries, credit tracking, pending transactions
§5 Feature Steering: Daily health coach (§A1), udhaar follow-up (§A2), persona-aware AI (§A3)
§7 Testing Requirements: Property-based tests for all deterministic functions

Why Judges Should Care: This isn't just another AI app - it's a responsible AI implementation with architectural guardrails that prevent hallucinations in critical financial calculations. Every rule in vyapar-rules.md is enforced through:

Code structure: Financial logic in /lib/finance/, AI prompts in /lib/ai/
Testing: 150+ property-based tests proving correctness
AWS integration: Native use of Bedrock, DynamoDB, S3, Lambda
Offline-first: Works without internet, syncs when connected

✨ Key Features (Built on AWS)

📊 Daily Business Health Dashboard

Health Score (0-100): Calculated from margin, expenses, cash buffer, and credit risk
Stress Index: Measures business pressure from credit ratio and cash volatility
Affordability Index: Evaluates capacity for planned expenses based on profit
Real-time Updates: Scores update instantly as you add daily entries

💰 Credit Management & Udhaar Follow-up

Track Customer Credit: Record who owes you money and when it's due
Automated Follow-up: WhatsApp message generator with pre-filled templates
Overdue Alerts: Visual indicators for credits past due date
Mark as Paid: One-click payment tracking with sync to cloud

🎤 Voice & Receipt Entry

Voice-to-Entry: Speak your daily sales/expenses in Hindi/Marathi/English
Receipt OCR: Upload receipt photos, extract amounts and vendor details
Click-to-Add: Review inferred transactions before adding to records
Duplicate Detection: Prevents accidental double entries

📈 AI-Powered Insights

Persona-Aware Advice: Tailored recommendations based on business type (kirana, salon, pharmacy, etc.)
Segment Benchmarking: Compare your performance with similar businesses
Cash Flow Prediction: 7-day forecast based on historical patterns
Expense Alert System: Flags unusual spending patterns

🔒 Enterprise-Grade Architecture

AWS DynamoDB: Single-table design for all user data
AWS S3 + Lambda: Event-driven processing for receipts and voice
AWS Bedrock: Multi-model AI with Claude 3 Sonnet and Titan
PWA Offline Support: Works without internet, syncs when connected
End-to-End Testing: 150+ property-based and integration tests

🏗️ AWS Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js 16.1.6)                │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐   │
│  │   React     │  │  TypeScript │  │  Tailwind CSS    │   │
│  │ Components  │  │   Logic     │  │     Styling      │   │
│  └─────────────┘  └─────────────┘  └──────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────────┐
│                 Backend API (Next.js App Router)            │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐   │
│  │   /api/*    │  │  Services   │  │   Repositories   │   │
│  │   Routes    │  │   Layer     │  │   (DynamoDB)     │   │
│  └─────────────┘  └─────────────┘  └──────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────────┐
│                    AWS Cloud Infrastructure                  │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐   │
│  │  DynamoDB   │  │     S3      │  │    Lambda        │   │
│  │  Database   │  │  Storage    │  │   Functions      │   │
│  └─────────────┘  └─────────────┘  └──────────────────┘   │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐   │
│  │  Bedrock    │  │  Transcribe │  │      SES         │   │
│  │ Nova Models │  │   (Voice)   │  │  (Email/Reset)   │   │
│  └─────────────┘  └─────────────┘  └──────────────────┘   │
└─────────────────────────────────────────────────────────────┘

AWS Services Used

AWS Bedrock: Amazon Nova Pro, Lite, and Micro models with per-feature routing and fallback chain
AWS DynamoDB: Single-table design with TTL for session management
AWS S3: Secure file storage with lifecycle policies (receipts: 7-day, voice: 1-day)
AWS Lambda: Serverless functions for OCR, voice processing, predictions, and report generation
AWS Transcribe: Voice-to-text for multilingual speech recognition
AWS SES: Transactional email for password reset and welcome flows
AWS IAM: Fine-grained access control with least privilege principle

🚀 Quick Start

Prerequisites

Node.js 20+ (required for AWS SDK v3)
AWS Account with Bedrock, DynamoDB, S3, and Lambda access
Git

Installation

# Clone the repository
git clone <repository-url>
cd vyapar-ai

# Install dependencies
npm install

# Configure environment
cp .env.local.example .env.local
# Edit .env.local with your AWS credentials

Environment Variables (.env.local)

# AWS Configuration
AWS_REGION=ap-south-1
AWS_ACCESS_KEY_ID=your-access-key-here
AWS_SECRET_ACCESS_KEY=your-secret-key-here
# Required only for temporary STS credentials
AWS_SESSION_TOKEN=your-session-token-here

# AWS Bedrock - Per-feature Nova model routing
BEDROCK_MODEL_ID=global.amazon.nova-2-lite-v1:0

BEDROCK_MODEL_QA_PRIMARY=apac.amazon.nova-pro-v1:0
BEDROCK_MODEL_QA_FALLBACK=apac.amazon.nova-lite-v1:0
BEDROCK_MODEL_QA_FINAL=apac.amazon.nova-micro-v1:0

BEDROCK_MODEL_ANALYSIS_PRIMARY=apac.amazon.nova-pro-v1:0
BEDROCK_MODEL_ANALYSIS_FALLBACK=apac.amazon.nova-lite-v1:0
BEDROCK_MODEL_ANALYSIS_FINAL=apac.amazon.nova-micro-v1:0

BEDROCK_MODEL_EXPLAIN_PRIMARY=apac.amazon.nova-pro-v1:0
BEDROCK_MODEL_EXPLAIN_FALLBACK=apac.amazon.nova-lite-v1:0
BEDROCK_MODEL_EXPLAIN_FINAL=apac.amazon.nova-micro-v1:0

BEDROCK_MODEL_REPORT_PRIMARY=apac.amazon.nova-lite-v1:0
BEDROCK_MODEL_REPORT_FALLBACK=apac.amazon.nova-pro-v1:0
BEDROCK_MODEL_REPORT_FINAL=apac.amazon.nova-micro-v1:0

BEDROCK_MODEL_VOICE_PRIMARY=apac.amazon.nova-lite-v1:0
BEDROCK_MODEL_VOICE_FINAL=apac.amazon.nova-micro-v1:0

BEDROCK_MODEL_EXPENSE_ALERT_PRIMARY=apac.amazon.nova-micro-v1:0
BEDROCK_MODEL_EXPENSE_ALERT_FALLBACK=apac.amazon.nova-lite-v1:0

# Enable automatic fallback to next configured Bedrock model
ENABLE_AI_FALLBACK=true

# DynamoDB
DYNAMODB_TABLE_NAME=vyapar-ai

# S3 Buckets
S3_BUCKET_RECEIPTS=vyapar-ai-receipts-123456789012
S3_BUCKET_VOICE=vyapar-ai-voice-123456789012
AWS_S3_BUCKET_RECEIPTS_OUTPUT=vyapar-receipts-output

# Lambda Functions
LAMBDA_CASHFLOW_PREDICTOR=cashflow-predictor
LAMBDA_EXPENSE_ALERT=expense-alert
LAMBDA_REPORT_GENERATOR=report-generator
LAMBDA_RECEIPT_OCR=receipt-ocr-processor
LAMBDA_VOICE_PROCESSOR=voice-processor

# SES Email
SES_REGION=ap-south-1
SES_ACCESS_KEY_ID=your-ses-access-key-id
SES_SECRET_ACCESS_KEY=your-ses-secret-access-key
EMAIL_FROM_ADDRESS=noreply@yourdomain.com
APP_BASE_URL=https://yourdomain.com

# Demo credentials (development only)
DEMO_USERNAME=admin
DEMO_PASSWORD=vyapar123

Development

# Start development server
npm run dev

# Run tests
npm test

# Run property-based tests
npm test -- --testPathPattern=property

# Build for production
npm run build

📱 User Flow

1. Sign Up & Profile Setup

Create account with username/password
Select business type (kirana, salon, pharmacy, restaurant, other)
Set preferred language (English, हिंदी, मराठी)
Choose explanation mode (simple/detailed)

2. Daily Business Entry

Manual Entry: Quick form for sales, expenses, cash in hand
Voice Entry: Speak transactions in natural language
Receipt OCR: Upload photos of receipts
CSV Upload: Bulk import from accounting software

3. Health Monitoring

Health Score: See overall business health (0-100)
Stress Index: Identify pressure points
Affordability: Plan for upcoming expenses
Benchmarking: Compare with similar businesses

4. Credit Management

Add Credits: Record customer udhaar
Follow-up Panel: See overdue credits with WhatsApp links
Payment Tracking: Mark credits as paid
Reminder System: Automated follow-up scheduling

5. AI Insights & Reports

Daily Suggestions: Rule-based recommendations
Cash Flow Forecast: 7-day prediction
Expense Alerts: Unusual spending detection
PDF Reports: Exportable business summaries

🛠️ Technical Stack

Frontend

Framework: Next.js 16.1.6 (App Router)
Language: TypeScript
Styling: Tailwind CSS + Design System
State Management: React Hooks + Context
PWA: Next-PWA for offline capability
Charts: Recharts for data visualization

Backend

API Routes: Next.js App Router
Database: AWS DynamoDB (Single-table design)
File Storage: AWS S3 with lifecycle policies
AI Services: AWS Bedrock (Amazon Nova Pro, Lite, Micro — per-feature model routing with fallback chain)
Serverless: AWS Lambda for async processing
Email: AWS SES for transactional emails (password reset, welcome)
Authentication: Session-based with bcrypt

Testing & Quality

Unit Tests: Jest + Testing Library
Property-Based Tests: FastCheck for correctness proofs
Integration Tests: End-to-end API testing
Bug Exploration: Systematic bug condition testing
Preservation Tests: Ensure fixes don't break existing functionality

🔧 AWS Infrastructure Setup

1. DynamoDB Table

# Create single-table design
Table: vyapar-ai
Partition Key: PK (String)
Sort Key: SK (String)
TTL: expires_at (Number)

2. S3 Buckets

# Receipt storage (7-day retention)
vyapar-ai-receipts-{account-id}

# Voice processing (1-day retention)  
vyapar-ai-voice-{account-id}

# Enable CORS and lifecycle policies

3. Lambda Functions

# Receipt OCR Processor
lambda/receipt-ocr-processor/

# Voice Processor  
lambda/voice-processor/

# Cash Flow Predictor
lambda/cashflow-predictor/

# Expense Alert System
lambda/expense-alert/

# Report Generator
lambda/report-generator/

4. IAM Roles & Permissions

Bedrock InvokeModel permissions (Nova Pro, Lite, Micro)
DynamoDB read/write access
S3 put/get/delete permissions
Lambda execution roles
SES send email permissions

🧪 Testing Strategy

Property-Based Testing (PBT)

// Example: Health score always between 0-100
test('health score bounds', () => {
  fc.assert(
    fc.property(
      fc.float({ min: 0, max: 1 }),
      fc.float({ min: 0, max: 1 }),
      fc.option(fc.float({ min: 0, max: 1000000 })),
      fc.record({
        overdueCount: fc.nat(),
        totalOutstanding: fc.float({ min: 0 }),
        totalOverdue: fc.float({ min: 0 }),
      }),
      (margin, expenseRatio, cashInHand, creditSummary) => {
        const score = calculateHealthScore(
          margin,
          expenseRatio,
          cashInHand,
          creditSummary
        );
        return score >= 0 && score <= 100;
      }
    )
  );
});

Bug Exploration Tests

Systematic discovery of edge cases
Counterexample generation
Preservation checking for fixes
Regression prevention

Integration Test Coverage

User authentication flow
Data sync between local and cloud
AI endpoint reliability
File upload processing

📊 Business Impact Metrics

For Shop Owners

5-15% Profit Improvement: Better understanding of true profitability
30% Time Reduction: Automated credit follow-up and reporting
Improved Cash Flow: 7-day forecasting and expense alerts
Reduced Stress: Clear visibility into business health

Technical Achievements

150+ Tests: Comprehensive test coverage
<100ms Response Time: Deterministic calculations
Offline-First: Works without internet connection
Multi-Language: Hindi, Marathi, English support
AWS Native: Full cloud integration

🚨 Security & Compliance

Data Protection

End-to-End Encryption: All data encrypted in transit and at rest
AWS KMS: Key management for sensitive data
GDPR Ready: Right to deletion and data portability
No PII Storage: Minimal personal information collection

Access Control

Session-Based Auth: Secure user sessions
DynamoDB Fine-Grained Access: Row-level security
S3 Presigned URLs: Temporary file access
AWS IAM Best Practices: Least privilege principle

📈 Deployment

Vercel (Recommended)

# Automatic deployment from GitHub
vercel --prod

# Environment variables in Vercel dashboard
# See .env.local.example for the full list of required variables

AWS EC2

# Use deployment script
./scripts/deploy-to-ec2.sh

# Configure NGINX + PM2
# Set up SSL with Let's Encrypt

AWS Infrastructure Setup

# Deploy all AWS resources (DynamoDB, S3, Lambda)
chmod +x scripts/*.sh
./scripts/deploy-aws-infrastructure.sh

# Validate deployment
./scripts/validate-infrastructure.sh

# Test Lambda functions
./scripts/test-lambdas.sh

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow TypeScript strict mode
Write property-based tests for new features
Maintain deterministic-first architecture
Update documentation for API changes
Use conventional commits

📚 Documentation

API Documentation: app/api/*/route.ts files
Architecture: .kiro/steering/vyapar-rules.md
Testing Guide: __tests__/ directory
Deployment: scripts/deploy-aws-infrastructure.sh
Demo Data: public/demo-data/README.md (CSV files for all business types × city tiers)
DynamoDB Migration: docs/dynamodb-userid-migration-plan.md

🆘 Troubleshooting

Common Issues

AWS Credentials Error

# Verify credentials in .env.local
# Check IAM permissions for Bedrock, DynamoDB, S3

DynamoDB Connection Issues

# Verify table exists in correct region
# Check IAM role permissions
# Use AWS CLI: aws dynamodb list-tables
# Default table name: vyapar-ai (set via DYNAMODB_TABLE_NAME)

3. Bedrock Model Access

# Request access to Amazon Nova models in AWS Console
# Verify model IDs match your region (ap-south-1 uses apac.* prefix)
# Check region availability for Nova Pro, Lite, and Micro

Build Errors

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

AWS Bedrock Team for AI model access
Next.js Team for the amazing framework
FastCheck for property-based testing
Small Shop Owners across India for inspiration

📞 Support

GitHub Issues: Report bugs or request features
Email: support@vyapar-ai.com
Documentation: Full documentation

Built with ❤️ for the AI for Retail, Commerce & Market Intelligence track

Making financial intelligence accessible to every small business owner in India

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.kiro		.kiro
.vscode		.vscode
__tests__		__tests__
app		app
backups		backups
components		components
docs		docs
lambda		lambda
lib		lib
public		public
sample-data		sample-data
scripts		scripts
.env.local.example		.env.local.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
README.md		README.md
app_run.log		app_run.log
jest.config.js		jest.config.js
next.config.mjs		next.config.mjs
next.headers.js		next.headers.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
proxy.ts		proxy.ts
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Vyapar AI - Daily Business Health Companion for Small Shop Owners

🏆 AWS Hackathon Submission - AI for Retail, Commerce & Market Intelligence

Executive Summary

🎯 Architecture Philosophy: Hybrid Intelligence (Governed by vyapar-rules.md)

The Problem with Pure AI Solutions

Our Solution: Deterministic-First Architecture (Code-Enforced Rules)

✨ Key Features (Built on AWS)

📊 Daily Business Health Dashboard

💰 Credit Management & Udhaar Follow-up

🎤 Voice & Receipt Entry

📈 AI-Powered Insights

🔒 Enterprise-Grade Architecture

🏗️ AWS Architecture Overview

AWS Services Used

🚀 Quick Start

Prerequisites

Installation

Environment Variables (.env.local)

Development

📱 User Flow

1. Sign Up & Profile Setup

2. Daily Business Entry

3. Health Monitoring

4. Credit Management

5. AI Insights & Reports

🛠️ Technical Stack

Frontend

Backend

Testing & Quality

🔧 AWS Infrastructure Setup

1. DynamoDB Table

2. S3 Buckets

3. Lambda Functions

4. IAM Roles & Permissions

🧪 Testing Strategy

Property-Based Testing (PBT)

Bug Exploration Tests

Integration Test Coverage

📊 Business Impact Metrics

For Shop Owners

Technical Achievements

🚨 Security & Compliance

Data Protection

Access Control

📈 Deployment

Vercel (Recommended)

AWS EC2

AWS Infrastructure Setup

Docker

🤝 Contributing

Development Guidelines

📚 Documentation

🆘 Troubleshooting

Common Issues

3. Bedrock Model Access

📄 License

🙏 Acknowledgments

📞 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages