Campus Recover：面向 Rishihood University 的 AI 失物招领平台

🌟 Overview

Campus Recover is an intelligent, privacy-first university lost-and-found management platform built for modern academic institutions, specifically calibrated and deployed for Rishihood University, Sonipat.

Traditional campus lost-and-found setups rely on cluttered WhatsApp groups, bulletin boards, and manual inquiries at security gates. Campus Recover replaces this chaos with a high-accuracy, 5-factor AI matching pipeline that analyzes images, descriptions, campus landmark proximity, temporal decay, and physical attributes to match lost and found reports automatically in real-time.

✨ Key Features

🧠 AI Multi-Modal Recovery Engine

When an item is reported as Lost or Found, the platform generates embeddings across multiple modalities and computes an aggregate match confidence score $S_{\text{total}}$ against candidate items:

                            ┌────────────────────────┐
                            │   Item Report Influx   │
                            └───────────┬────────────┘
                                        │
             ┌──────────────┬───────────┴───────────┬──────────────┐
             ▼              ▼                       ▼              ▼
       ┌───────────┐  ┌───────────┐           ┌───────────┐  ┌───────────┐
       │   Text    │  │   Image   │           │ Geospatial│  │ Temporal  │
       │ Embedding │  │  (CLIP)   │           │ Haversine │  │ Half-Life │
       └─────┬─────┘  └─────┬─────┘           └─────┬─────┘  └─────┬─────┘
             │              │                       │              │
      (30% Weight)   (30% Weight)            (20% Weight)   (10% Weight)
             │              │                       │              │
             └──────────────┼───────────────────────┴──────────────┘
                            ▼
              ┌───────────────────────────┐
              │  + 10% Attribute Overlap  │
              └─────────────┬─────────────┘
                            ▼
           ╔═════════════════════════════════╗
           ║   Aggregated Confidence Score   ║
           ║    High: ≥70% | Medium: ≥50%    ║
           ╚═════════════════════════════════╝

📐 Scoring Formulation

$$\text{Score}_{\text{final}} = 0.30 \cdot S_{\text{text}} + 0.30 \cdot S_{\text{image}} + 0.20 \cdot S_{\text{location}} + 0.10 \cdot S_{\text{time}} + 0.10 \cdot S_{\text{attributes}}$$

• Semantic Text ($S_{\text{text}}$ - 30%): Cosine similarity of 384-dimensional dense vectors generated by all-MiniLM-L6-v2. Captures semantic equivalence (e.g. "navy blue hydroflask" vs "dark blue water bottle").
• Vision Embeddings ($S_{\text{image}}$ - 30%): Cosine similarity of 512-dimensional visual feature vectors extracted by OpenAI's CLIP ViT-B/32. Robust against background variations, lighting, and camera angles.
• Geospatial Proximity ($S_{\text{location}}$ - 20%): Inverse-distance Haversine calculation with smooth gaussian falloff calibrated specifically to Rishihood University's campus footprint.
• Temporal Correlation ($S_{\text{time}}$ - 10%): Exponential time-decay function prioritizing items lost and found within corresponding temporal windows.
• Attribute Matching ($S_{\text{attributes}}$ - 10%): Exact and fuzzy intersection over category, color tags, brand name, and item dimensions.

🗺️ Interactive Campus GIS Map

The interactive campus map leverages OpenStreetMap with Leaflet to visualize lost and found incident hotspots across Rishihood University:

• Official Centroid: 28.9832° N, 77.0908° E (Rishihood University, Sonipat, Haryana).
• Campus Radar Picker: Drag-and-drop pinpoint accuracy with automatic landmark snapping.
• High-Value Item Obfuscation: High-risk categories (ELECTRONICS, DOCUMENTS, KEYS, ACCESSORIES) undergo automatic coordinate jittering ($\pm 60\text{m}$) on public views until ownership is verified.

🏛️ Rishihood University Campus Locations

The platform is pre-loaded with 20 verified landmark zones across Rishihood University:

🏗️ System Architecture

graph TB
    subgraph Client["Frontend Client (React 19 + TypeScript + Vite)"]
        UI[Tailwind CSS & Framer Motion UI]
        Map[Leaflet OpenStreetMap Radar]
        AuthC[Auth Context & JWT Store]
        Query[TanStack React Query Cache]
    end

    subgraph API["Backend API (FastAPI)"]
        Router[API Gateway /api/v1]
        AuthService[Argon2 Password & JWT Service]
        ItemService[Item & Upload Service]
        ClaimService[Claim & Verification Engine]
        MapService[GIS Location & Privacy Shield]
        WS[WebSocket Notification Hub]
    end

    subgraph AI["AI / ML Pipeline"]
        ST[Sentence-Transformers all-MiniLM-L6-v2]
        CLIP[OpenAI CLIP ViT-B/32]
        Radar[Haversine GIS Engine]
        Scorer[Multi-Modal Weighted Scorer]
    end

    subgraph DB["Persistence Layer"]
        Postgres[(PostgreSQL / SQLite)]
        Storage[(Local File Storage / Uploads)]
    end

    UI --> Router
    Map --> Router
    AuthC --> Router
    Router --> AuthService
    Router --> ItemService
    Router --> ClaimService
    Router --> MapService
    Router --> WS
    ItemService --> AI
    AI --> Scorer
    AuthService --> Postgres
    ItemService --> Postgres
    ClaimService --> Postgres
    MapService --> Postgres
    ItemService --> Storage

Loading

🛠️ Technology Stack

🚀 Quick Start Guide

📋 Prerequisites

• Python 3.11+ installed
• Node.js 20+ and npm installed
• (Optional) Docker and Docker Compose (for PostgreSQL)

1️⃣ Clone the Repository

git clone https://github.com/oreoviru/Campus-Recover.git
cd Campus-Recover

2️⃣ Backend Setup

cd backend

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate    # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env

# Initialize database and populate Rishihood University seed data
python -m app.database.seed

# Start FastAPI development server
uvicorn app.main:app --reload --port 8000

The API will start at http://localhost:8000.

• Interactive Swagger Documentation: http://localhost:8000/docs
• ReDoc Interactive Documentation: http://localhost:8000/redoc

3️⃣ Frontend Setup

cd ../frontend

# Install dependencies
npm install

# Configure environment
cp .env.example .env

# Start Vite development server
npm run dev

The web application will launch at http://localhost:5173.

👥 Default Seed Demo Accounts

Use these pre-configured accounts to test student and administrator workflows right away:

📡 API Endpoints

🔐 Authentication & Accounts

• POST /api/v1/auth/register — Register a student or staff account
• POST /api/v1/auth/login — Authenticate and receive JWT access token
• GET /api/v1/auth/me — Retrieve current authenticated user profile

📦 Lost & Found Items

• GET /api/v1/items — Paginated list of items with filters (status, category, location_id, search)
• POST /api/v1/items — Report a newly lost or found item (triggers auto-matching)
• GET /api/v1/items/{id} — Fetch detailed item record with privacy-shielded coordinates
• PUT /api/v1/items/{id} — Update item status or description
• POST /api/v1/upload — Upload item photographs for vision embedding extraction

🤖 Matching Engine

• GET /api/v1/matches/item/{id} — Retrieve AI-ranked match candidates with sub-score breakdowns
• POST /api/v1/matches/recalculate — Trigger background match re-indexing

🤝 Claims & Verification

• POST /api/v1/claims — Submit an ownership claim with challenge answer
• GET /api/v1/claims/my — View user's submitted claims
• PUT /api/v1/claims/{id}/status — Review and approve/reject claims (Admin/Staff)

📍 Campus Locations & Radar

• GET /api/v1/locations — Retrieve all 20 Rishihood University campus locations
• GET /api/v1/locations/map — GeoJSON / coordinate pins for campus map visualization

🔔 Notifications

• GET /api/v1/notifications — Fetch user's alert stream (matches, claims, status changes)
• PUT /api/v1/notifications/{id}/read — Mark notification as acknowledged
• WS /api/v1/ws/{user_id} — Real-time WebSocket event connection

🧪 Testing & Quality Assurance

The codebase includes comprehensive test suites covering unit logic, matching algorithms, and API flows:

cd backend
pytest -v

=================================== test session starts ====================================
collected 85 items

tests/test_items.py .........................                             [ 29%]
tests/test_text_matching.py ............                                  [ 43%]
tests/test_image_matching.py ........                                     [ 52%]
tests/test_location_matching.py ..........                                [ 64%]
tests/test_time_matching.py ........                                      [ 74%]
tests/test_scoring.py ...........                                         [ 87%]
tests/test_claims.py ...........                                          [100%]

==================================== 85 passed in 37.12s ===================================

Frontend compilation check:

cd frontend
npm run build

🛡️ Security & Privacy Architecture

1. Blind Verification: Item reporters can configure a secret security question (e.g. "What is the engraved text on the back?" or "What wallpaper is on the lock screen?"). The answer is hashed using cryptographic salt (Argon2id), preventing unauthorized finders from guessing answers.
2. Geospatial Privacy Shield: Items marked as high-value automatically obfuscate precise coordinates on public maps until administrative or owner clearance is granted.
3. Role-Based Access Control (RBAC): Fine-grained token scopes isolate student actions from campus security administrators.
4. Rate Limiting & Sanitation: File upload validation with strict MIME checking (image/jpeg, image/png, image/webp) and size quotas.

📄 License

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

_{Engineered with ❤️ by Viraj Salunkhe}