Sambhav

Sambhav is a prevention-first digital protection platform prototype built for academic evaluation. It combines behavioral risk scoring (DBS), modular policy activation, and structured claim operations.

Documentation Index

• Product and system specification: docs/sambhav-spec.md
• Detailed API contract: docs/api.md
• API quick reference: docs/api-list.md
• Deployment and operations runbook: docs/deployment-runbook.md
• Frontend setup and route map: frontend/frontend/README.md

Repository Structure

sambhav/
  backend/            Express + SQLite API
  docs/               Product, API, and operations documentation
  frontend/frontend/  React + Vite web client

Tech Stack

• Frontend: React, Vite, React Router, Axios, Framer Motion
• Backend: Node.js, Express, SQLite, JWT, bcrypt
• Auth: Bearer JWT (Authorization: Bearer <token>)

Quick Start (Local)

1) Backend

cd backend
npm install
cp .env.example .env
npm run start

Health check:

curl http://localhost:5000/test

2) Frontend

cd frontend/frontend
npm install
cp .env.example .env
npm run dev

Frontend runs on http://localhost:5173 and calls backend via VITE_API_URL.

Environment Variables

Backend (backend/.env)

• JWT_SECRET (required)
• PORT (default 5000)
• FRONTEND_URL (CORS origin, default http://localhost:5173)

Frontend (frontend/frontend/.env)

• VITE_API_URL (example: http://localhost:5000)

Local Network Error Runbook

If signup/login shows Network Error in local development, validate these in order:

1. Backend is running on port 5000 (npm run start in backend).
2. GET /test succeeds at http://localhost:5000/test.
3. frontend/frontend/.env has VITE_API_URL=http://localhost:5000.
4. backend/.env has FRONTEND_URL=http://localhost:5173.

Render Free-Tier Behavior (Current Deployment Mode)

• Free web services spin down after idle and cold-start on the next request.
• With SQLite on local service disk, runtime data durability is not guaranteed across restarts/redeploys.
• Keepalive monitors reduce cold starts but do not provide persistence guarantees.

Reference docs:

• https://render.com/docs/free
• https://render.com/docs/disks

Authoritative SQLite File

• Canonical database file for this codebase is backend/sambhav.db (from backend/config/db.js).
• backend/sambhav.sqlite is legacy/non-authoritative and should not be used for runtime assumptions.

Deployment Checklist

1. Backend service is up and GET /test responds.
2. Frontend VITE_API_URL points to deployed backend URL.
3. Backend FRONTEND_URL matches deployed frontend origin exactly.
4. Keepalive monitor is configured to ping /test every 5 minutes.
5. Both frontend and backend smoke tests pass after deploy.

What Is Implemented Now

• Authentication (signup, login)
• User dashboard summary and protected user routes
• Plan activation and policy listing/details
• Claim creation and admin review workflow
• DBS score submission and latest score retrieval
• Receipt retrieval by policy ID
• Public narrative pages + legal/support pages (/privacy, /terms, /contact)

Known Constraints

• Duplicate-claim prevention is frontend-guarded; backend hard idempotency is not strict yet.
• Backend currently calculates fixed premium (499) in receipt creation logic.
• Admin endpoint coverage is focused on metrics and claims; policy/user admin listing endpoints are limited.
• Free-tier Render + SQLite is suitable for demo use, not durable production persistence.