LocalConnect

Need → Match → Connect

An AI-powered hyperlocal service discovery and transparent matching platform connecting people with verified local service providers.

Explore the Docs »
Getting Started · AI Matching Architecture · Telegram Bot · API Reference · Testing Strategy

📌 Table of Contents

🌐 Project Overview
❗ Problem Statement
💡 Our Solution
✨ Key Features
🧠 AI & Smart Matching Architecture
🗺️ How It Works
🛠️ Technology Stack
🏛️ System Architecture
📁 Repository Structure
🚀 Getting Started
⚡ Running the Project
🔌 API Endpoints
🤖 Telegram AI Bot
🧪 Testing Strategy
🔒 Security & Privacy
🔄 Development Workflow
🗺️ Roadmap
📄 License & Authors

🌐 Project Overview

LocalConnect is an AI-first, hyperlocal service discovery platform designed to connect consumers with vetted, high-trust local service professionals (tutors, electricians, plumbers, home chefs, mechanics, fitness trainers, and technicians) based on their actual needs, exact location proximity, real-time availability, budget, and multi-pillar trust signals.

Unlike traditional static directory listings that rely on keyword spam and pay-to-win ads, LocalConnect treats local discovery as an intent-driven matching problem. Users describe their requirements naturally (e.g., "Need a Class 12 Maths tutor in Dharampeth under ₹500/hr for weekend boards prep"), and LocalConnect's intelligence layer extracts semantic parameters, computes a 7-factor explainable match score, and surfaces the best-fit local providers with verified trust audits.

LocalConnect delivers a dual-interface experience:

Modern Responsive Web Application: 12 interactive screens with conversational search refinement, algorithm weight customization, provider comparison modals, trust audits, and provider dashboards.
Telegram AI Chatbot (@LocalConnect001bot): Complete conversational natural language search, match cards, profile inspection, 4-pillar trust scorecards, and review intelligence directly inside Telegram.

❗ Problem Statement

The Consumer Dilemma

Finding a trustworthy local service provider today is fragmented across WhatsApp groups, word-of-mouth, Instagram accounts, and ad-heavy search engines. Consumers face:

Zero Transparency: Fake reviews, hidden prices, and unverified credentials.
Manual Overhead: Calling multiple numbers to inquire about rates and weekend availability.
Location Inefficiency: Getting recommendations for providers located too far across town.
Low Trust: Uncertainty over who is entering the household or teaching a family member.

The Local Provider Dilemma

Skilled independent workers and local micro-businesses face severe digital hurdles:

Lack of marketing budgets to compete with sponsored ad listings on legacy portals.
Inability to showcase verified proof of work, verified government credentials, or verified response rates.
Inbound inquiries with poor fit (mismatched budgets, incompatible timings, or unrealistic distances).

The Gap

There is a critical need for an intelligent, intent-based matchmaking engine that understands natural language needs, guarantees factual trust transparency, and connects local demand with local talent.

💡 Our Solution

LocalConnect replaces static search listings with an Explainable 7-Factor Semantic Match Engine and a 4-Pillar Verified Trust Audit:

flowchart LR
    A[Natural Language Need] --> B[AI Need Parser]
    B --> C[7-Factor Weighted Matching]
    C --> D[Ranked Local Providers]
    D --> E[4-Pillar Trust Audit]
    E --> F[Direct Connection]

Natural Understanding: Converts conversational text and Hinglish inputs into structured requirement contracts.
Deterministic & Explainable Matching: Computes a transparent 0–100% Match Score based on mathematical criteria weights, not black-box guesses.
Verified Credibility: Audits providers across Identity, Verified Experience, Ratings, and Responsiveness.
Conversational Multi-Turn Refinement: Refines searches dynamically without losing session context.

✨ Key Features

Category	Feature	Status	Description
Search & Discovery	Natural Language Need Parser	✅ Implemented	Extracts service category, skill level, budget ceiling, location radius, and timing constraints from free-form text.
Search & Discovery	Conversational Search Refinement	✅ Implemented	Multi-turn query adjustments (e.g. "Only highly rated", "Within 3 km", "Available Sunday") preserving active search context.
Matching Engine	7-Factor Explainable Matching	✅ Implemented	Transparent scoring algorithm evaluating skills, semantic similarity, distance, schedule, budget, trust, and response rate.
Matching Engine	Dynamic Algorithm Weighting	✅ Implemented	Interactive drawer allowing users to customize matching weight priorities in real time.
Matching Engine	Provider Comparison Modal	✅ Implemented	Side-by-side comparison of candidate match scores, hourly rates, verified jobs, and distance.
Trust & Verification	4-Pillar Trust Scorecard	✅ Implemented	100-point audit evaluating Identity (25 pts), Experience (25 pts), Ratings (30 pts), and Responsiveness (20 pts).
Trust & Verification	AI Review Intelligence	✅ Implemented	Grounded sentiment extraction displaying top praised qualities, honest caveats, and real client testimonials.
Provider Tools	Provider AI Assistant	✅ Implemented	Evaluates inbound job requests, computes Request Fit Score %, and generates rate-grounded suggested replies.
Telegram Interface	Full-Featured Telegram AI Bot	✅ Implemented	Complete conversational bot (`@LocalConnect001bot`) with interactive reply keyboards, inline match cards, profile viewers, and trust audits.
User Dashboard	Customer & Provider Dashboards	✅ Implemented	Active request status tracking, lead management, and profile enhancement modals.

🧠 AI & Smart Matching Architecture

The LocalConnect AI subsystem (ai/) is designed around a multi-provider architecture featuring Google Gemini 1.5/2.0 with an automated, zero-latency Local Deterministic Fallback Engine. This guarantees 100% uptime, zero hallucinations, and consistent test reliability even offline.

ai/
├── parser/                 # Converts free-form text into structured NeedRequirement JSON
├── matching/               # 7-factor weighted multi-criteria ranking algorithm
├── refinement/             # Stateful multi-turn conversational filter manager
├── trust/                  # 4-pillar verified trust score computation
├── review_intelligence/    # Review sentiment, praised themes, and nuance extraction
├── provider_assistant/     # Inbound lead fit evaluator & draft response generator
├── services/               # GeminiProvider, LocalDeterministicProvider, AIService
├── schemas/                # TypeScript interfaces and JSON data contracts
├── shared/                 # Semantic domain ontology and keyword dictionary
└── prompts/                # Structured LLM system prompts

1. 7-Factor Matching Weight Formula

$$\text{Match Score} = \sum (w_i \times s_i)$$

┌─────────────────────────────────────────────────────────────┐
│ 1. Skill & Category Match       (30%) ── [Core Competency] │
│ 2. Semantic Intent Similarity   (20%) ── [Context Match]   │
│ 3. Distance Proximity           (15%) ── [Haversine / Km]  │
│ 4. Availability & Schedule      (10%) ── [Day / Slot Fit]  │
│ 5. Budget Compatibility         (10%) ── [Price Fit]       │
│ 6. Verified Trust Score         (10%) ── [Credibility]     │
│ 7. Historical Response Rate     (05%) ── [Reliability]     │
└─────────────────────────────────────────────────────────────┘

2. Match Score vs. Trust Score Distinction

Match Score (0–100%): Measures how well the provider satisfies the current specific user request (Category, Distance, Budget, Schedule).
Trust Score (0–100 pts): Measures the provider's overall verified credibility across all time (Aadhaar verification, completed jobs count, verified client ratings, and reply speed).

🗺️ How It Works

Consumer Journey

sequenceDiagram
    autonumber
    actor User as Consumer
    participant UI as Web / Telegram Bot
    participant AI as AI Intelligence Layer
    participant Match as Matching Engine
    participant DB as Provider Registry

    User->>UI: "Need a Class 12 Maths tutor near Dharampeth under ₹500"
    UI->>AI: Parse natural language query
    AI-->>UI: Structured Requirement (Service: Maths, Budget: ₹500, Loc: Dharampeth)
    UI->>Match: Match against verified providers
    Match->>DB: Query candidates in radius
    Match-->>UI: Ranked Provider Cards with 7-factor Match Scores & Why Bullets
    User->>UI: Refine: "Only available on Sunday"
    UI->>Match: Re-rank with updated Sunday filter
    Match-->>UI: Refined Candidate Results
    User->>UI: View 4-Pillar Trust Scorecard & Reviews
    User->>UI: Click Connect

🛠️ Technology Stack

Domain	Technology	Purpose
Frontend Framework	React 19 (TypeScript)	Declarative component UI and single-page application structure
Bundler & Tooling	Vite 8 + Rolldown	High-speed ESM development server and optimized production bundling
Styling & Design	Tailwind CSS + Vanilla CSS	Modern responsive design system, glassmorphism, and dark/light modes
UI Components	Radix UI + Lucide React	Accessible UI primitives, dialogs, drawers, sheets, and icon set
Animations	Motion (Framer Motion)	Smooth micro-interactions, page transitions, and slide animations
Backend API	Node.js + Express 5	REST API server routing `/api/ai/*` endpoints and service adapters
AI / NLP	Google Gemini + Deterministic Engine	Semantic natural language parsing, lead evaluations, and zero-hallucination fallback
Chatbot Interface	Telegram Bot API (Node.js)	Standalone Telegram bot with long-polling daemon and inline keyboard routers
Data Contracts	TypeScript Interfaces + JSON Schemas	Strict type safety across frontend, backend, and AI pipeline
Test Automation	Node.js Native Test Runner (`.test.mjs`)	153 automated tests covering parser, matching, refinement, trust, and bot

🏛️ System Architecture

graph TD
    subgraph Clients["User Interfaces"]
        WebApp["🌐 Web Application (React 19 / Vite)"]
        TeleBot["🤖 Telegram Bot (@LocalConnect001bot)"]
    end

    subgraph BackendAPI["Backend Layer (Node.js / Express)"]
        Router["Express Router (/api/ai)"]
        HealthEndpoint["/api/health"]
    end

    subgraph AIIntelligence["LocalConnect AI Subsystem (ai/)"]
        Parser["Parser Engine (ai/parser)"]
        MatchingEngine["7-Factor Match Engine (ai/matching)"]
        RefinementEngine["Refinement Engine (ai/refinement)"]
        TrustEngine["Trust Engine (ai/trust)"]
        ReviewEngine["Review Intelligence (ai/review_intelligence)"]
        AssistantEngine["Provider Assistant (ai/provider_assistant)"]
        ProviderAdapter["AIService Provider (Gemini / LocalFallback)"]
    end

    subgraph DataStore["Data & Domain Layer"]
        ProviderData["Verified Providers Registry"]
        Ontology["Semantic Domain Ontology & Thesaurus"]
    end

    WebApp --> Router
    TeleBot --> Router
    Router --> Parser
    Router --> MatchingEngine
    Router --> RefinementEngine
    Router --> TrustEngine
    Router --> ReviewEngine
    Router --> AssistantEngine
    Parser --> ProviderAdapter
    MatchingEngine --> ProviderAdapter
    MatchingEngine --> ProviderData
    MatchingEngine --> Ontology

📁 Repository Structure

LocalConnect/
├── Backend/                        # Express API Backend
│   ├── src/
│   │   ├── config/                 # Database and service configs
│   │   ├── controllers/            # AI & request controllers
│   │   ├── routes/                 # Express route definitions (/api/ai, /api/health)
│   │   ├── app.js                  # Express application setup
│   │   └── server.js               # Server bootstrap entry point
│   └── package.json
├── ai/                             # Core AI Intelligence Subsystem
│   ├── matching/                   # 7-factor ranking algorithm & weights
│   ├── parser/                     # Natural language & Hinglish requirement parser
│   ├── refinement/                 # Conversational multi-turn search refiner
│   ├── trust/                      # 4-pillar trust evaluation engine
│   ├── review_intelligence/        # Review sentiment & theme analysis
│   ├── provider_assistant/         # Lead fit evaluator & reply generator
│   ├── services/                   # Gemini & deterministic fallback providers
│   ├── schemas/                    # JSON and TypeScript data contracts
│   ├── shared/                     # Semantic ontology and dictionary
│   ├── prompts/                    # System prompt templates
│   └── index.ts                    # AI module exports
├── src/                            # Frontend Source (React 19 + TypeScript)
│   ├── api/                        # Client API adapters (ai, providers, auth)
│   ├── assets/                     # Brand logos, photography, and fonts
│   ├── components/                 # Reusable UI primitives (dialogs, cards, buttons)
│   ├── context/                    # AuthContext and RequestContext state
│   ├── features/                   # Feature modules (matching, trust, refinement, provider)
│   ├── pages/                      # 12 page views (Home, Search, Results, Dashboards, Auth)
│   ├── services/                   # Matching & AI client bridge
│   ├── styles/                     # Global styling and Tailwind tokens
│   ├── types/                      # Domain interfaces and contracts
│   └── main.tsx                    # React application entry point
├── telegram/                       # Telegram AI Chatbot Subsystem
│   ├── bot/
│   │   ├── formatters/             # Card, profile, trust scorecard & review formatters
│   │   ├── handlers/               # Command, text, callback, and refinement routers
│   │   ├── keyboards/              # Inline and reply keyboard layouts
│   │   ├── services/               # Telegram API & LocalConnect client bridge
│   │   ├── session/                # Multi-turn user session context store
│   │   ├── config.js               # Bot configuration & token validation
│   │   └── main.js                 # Telegram bot polling runner
│   └── tests/                      # Automated Telegram test suites (Steps 3–7)
├── Docs/                           # Architecture specs, PRD, TRD, and schemas
├── dist/                           # Optimized production bundle
├── package.json                    # Project dependencies and script runner
├── tsconfig.json                   # TypeScript configuration
└── vite.config.ts                  # Vite build configuration

🚀 Getting Started

Prerequisites

Node.js: v18.0.0 or higher (node -v)
npm: v9.0.0 or higher (npm -v)
Git: Installed and configured

1. Clone the Repository

git clone https://github.com/Nipun75/LocalConnect.git
cd LocalConnect

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env file in the root directory (refer to .env.example):

cp .env.example .env

Set the required environment variables:

# Server & API Ports
PORT=5000
LOCALCONNECT_API_URL=http://localhost:5000/api

# Telegram Chatbot (Optional for Telegram bot)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_from_botfather
TELEGRAM_POLL_INTERVAL_MS=1000

# Google Gemini AI (Optional - Local Deterministic Fallback used automatically if absent)
GEMINI_API_KEY=your_gemini_api_key_here

⚡ Running the Project

LocalConnect components can be run independently or concurrently:

1. Start the Frontend (Development Server)

npm run dev

Access the web app at: http://localhost:5173

2. Build & Run the Production Frontend

npm run build
npm run preview

Access the production build at: http://localhost:4173

3. Start the Backend API Server

npm run start:backend

API health check available at: http://localhost:5000/api/health

4. Start the Live Telegram AI Bot

npm run start:telegram

Open Telegram and message: @LocalConnect001bot

🔌 API Endpoints

The Express Backend exposes clean RESTful endpoints consumed by both the web application and the Telegram bot:

Method	Endpoint	Description	Sample Payload / Params
`GET`	`/api/health`	Health check & feature discovery	`None`
`POST`	`/api/ai/parse-need`	Parse natural language text into structured requirement	`{"text": "Need a maths tutor for class 12 under 500"}`
`POST`	`/api/ai/match`	7-factor ranking of providers for structured need	`{"requirement": {...}}`
`POST`	`/api/ai/chat`	Conversational query refinement	`{"query": "Only highly rated ones", "currentRequirement": {...}}`
`POST`	`/api/ai/refine`	Alias for multi-turn search refinement	`{"query": "Within 3 km", "context": {...}}`
`GET`	`/api/ai/recommendations`	Get personalized provider recommendations	`?lat=21.1458&lng=79.0882&category=tutor`
`POST`	`/api/ai/feedback`	Record recommendation feedback for ranking tuning	`{"providerId": "prov_math_01", "rating": 5}`

🤖 Telegram AI Bot

The LocalConnect Telegram bot is a native integration running directly against the existing LocalConnect AI and Backend subsystem.

Telegram User ──> Telegram Bot Service ──> AI Parser ──> 7-Factor Match Engine ──> Ranked Cards

Live Bot Details

Username: @LocalConnect001bot
Supported Commands:
- /start — Welcome screen with interactive navigation buttons.
- /help — How to search and command guide.
- /search — Start a fresh provider search and reset context.
- /profile — View user account status.
- /requests — View active service requests.
Natural Language Capabilities:
- Send any natural language requirement directly: "Need an emergency electrician in Dharampeth right now"
- Refine conversationally: "Only ones available Sunday", "Increase budget to ₹700", "Within 3 km"
- Tap [ 👤 View Profile ], [ 🛡️ Trust Scorecard ], and [ ⭐ Customer Reviews ] to inspect credentials before connecting.

🧪 Testing Strategy

LocalConnect includes an extensive automated test suite of 153 unit and end-to-end tests validating all algorithms, fallback states, and bot interactions.

# Run all test suites across the repository
npm run test:all

Test Suites Breakdown

AI Matching & Scoring Tests (npm run test:step6):
- 19 automated tests validating natural language parsing, 7-factor weighted scoring, explainable why generation, conversational refinement, and provider assistant fit calculations.
Telegram Bot Integration Tests (npm run test:telegram):
- 102 automated tests across Steps 3, 4, 5, 6, and 7 validating connection lifecycle, requirement summaries, candidate rankings, context preservation, 4-pillar trust scorecards, and security on malformed callback IDs.
Core AI Unit Tests (npm test):
- 32 automated tests validating offline deterministic fallbacks and semantic ontology matching.

🔒 Security & Privacy

Zero PII Exposure: Private provider contact details (phone number, email, address) are never exposed through Telegram cards or search APIs prior to confirmed user connection.
Credential Isolation: Secrets (TELEGRAM_BOT_TOKEN, MONGO_URI, GEMINI_API_KEY) are managed strictly via git-ignored .env files and validated at boot.
Deterministic Guardrails: AI response templates are strictly grounded in factual provider profiles to prevent LLM hallucinations.
Input Sanitization: Callbacks, queries, and numerical parameters are parsed with strict boundary validation and safe fallback handlers.

🔄 Development Workflow

Create Feature Branch ──> Local Development ──> Run Test Suite ──> Build Verification ──> Open PR

Create Branch: git checkout -b feature/your-feature-name
Develop: Make modular code changes following the existing architecture.
Test: Run npm run test:all (all 153 tests must pass 100%).
Build: Run npm run build to verify clean TypeScript compilation and asset bundling.
Commit & Push: Follow conventional commit conventions (feat:, fix:, docs:, test:).

🗺️ Roadmap

✅ Phase 1: Core Implementation (Completed)

Natural language need parser with Hinglish support
7-factor transparent provider matching algorithm
4-pillar verified trust scorecard engine
AI review intelligence and testimonial summarization
Conversational multi-turn search refinement
Provider AI Assistant with request fit score & reply drafting
Complete 12-screen responsive React 19 web application
Native Telegram AI chatbot (@LocalConnect001bot)
153 automated integration and unit tests

🚧 Phase 2: Platform Enhancements (In Progress)

Direct in-app WebRTC audio/video consultations
Multi-city expansion beyond the Nagpur pilot region
WhatsApp Business Cloud API bot integration
Real-time provider location tracking on interactive Leaflet/Mapbox maps

🔮 Phase 3: Long-term Vision (Planned)

Decentralized identity verification via verifiable credentials
Escrow-based smart milestone payments
Multi-lingual voice-to-text search support (Hindi, Marathi)

📄 License & Authors

This project is licensed under the ISC License — see the LICENSE file for details.

Developed with ❤️ for LocalConnect — Making local discovery smarter, more trusted, and seamlessly connected.

Repository: https://github.com/Nipun75/LocalConnect

Name		Name	Last commit message	Last commit date
Backend		Backend
Docs		Docs
Frontend		Frontend
LocalConnect		LocalConnect
__MACOSX		__MACOSX
ai		ai
node_modules		node_modules
public		public
src		src
telegram		telegram
.env.example		.env.example
.gitignore		.gitignore
.oxlintrc.json		.oxlintrc.json
README.md		README.md
components.json		components.json
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.app.tsbuildinfo		tsconfig.app.tsbuildinfo
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation