📸 Upload → AI Analysis → Structured Output — all in seconds

Samadhan‑AI

---

One-line summary

A polished React + TypeScript frontend that accepts form images and uses Google Gemini (GenAI) to provide intelligent field guidance or structured validation of filled forms — built with production-minded reliability and developer hygiene.

Real-World AI Integration Connects image input to a generative model producing structured, validated outputs for downstream automation (data entry, audit, corrections).

Production Concerns Shows secret management, runtime schema validation, retries/backoff, file validation, CI/CD, and testable architecture.

Recruiter-Ready Clear technical ownership, data flow, failure modes, and developer experience — everything you look for in a portfolio project.

---

Live preview

📤 Drag & drop upload

📊 Structured output

✨ Two modes: Human-readable guidance or machine-usable JSON with confidence scores

---

Who built this

Tanmay Kunjir • Anshika Mishra

This repository demonstrates full‑stack integration of computer‑vision input and an LLM (Gemini) for practical form assistance: usable by product teams and demonstrative for technical recruiters.

Tanmay Kunjir

Anshika Mishra @10anshika

---

Table of contents

✨ Features • 🛠️ Tech Stack • ⚡ Quick Start • 🏗️ Architecture • 🤖 Gemini Integration • 🧪 Testing & CI • 🔒 Security • 🤝 Contributing

• Why this project matters
• Features
• Tech stack
• Quick start
• Architecture overview
• Gemini integration notes
• Tests & CI
• Security & privacy
• Contributors & contact

---

Why this project matters

• Connects image input to a generative model to produce structured, validated outputs suitable for downstream automation (data entry, audit, corrections).
• Shows production concerns: secret management, runtime schema validation, retries/backoff, file validation/compression, CI and tests.
• Clear technical ownership and design choices that recruiters look for: data flow, failure modes, and developer experience.

Real-World AI Integration Connects image input to a generative model producing structured, validated outputs for downstream automation (data entry, audit, corrections).

Production Concerns Shows secret management, runtime schema validation, retries/backoff, file validation, CI/CD, and testable architecture.

Recruiter-Ready Clear technical ownership, data flow, failure modes, and developer experience — everything you look for in a portfolio project.

---

Features

Capability	Description
Image Upload	Drag & drop, preview, MIME + size validation
Compression	Client-side resizing to reduce latency & cost
Field Guidance	Human-readable instructions for correcting entries
Validation Mode	Machine-usable JSON with confidence scores
Model Safety	Safe JSON parsing + runtime schema validation
Dev Hygiene	Env separation, CI-ready, testable architecture

---

Tech stack

Layer	Technology	Why
🎨 Frontend	React + TypeScript + Vite	Type safety, fast HMR, optimized builds
🧠 AI / LLM	Google Gemini (@google/genai)	State-of-the-art vision + language
🔍 Validation	zod	Runtime schema validation
🧪 Testing	Jest + React Testing Library	Unit & integration tests
⚙️ CI	GitHub Actions	Automated builds & tests

Layer	Technology
Frontend	React, TypeScript, Vite
AI / LLM	Google Gemini (@google/genai)
Validation	zod / AJV (runtime schemas)
Testing	Jest, React Testing Library
CI	GitHub Actions

---

Quick start (developer)

1. Clone and enter repo

git clone https://github.com/10anshika/Samadhan-AI.git
cd Samadhan-AI

2. Install

npm ci

3. Create .env.local from .env.example (do not commit)

GEMINI_API_KEY=sk-xxxxxx
VITE_PUBLIC_BASE_URL=http://localhost:5173
GEMINI_MODEL=gemini-3-pro-preview

4. Run dev server

npm run dev

5. Build

npm run build

---

Architecture overview

┌──────────────┐     Image (JPG/PNG)     ┌──────────────────────┐
│   Browser    │ ─────────────────────▶ │   Image Validation   │
│   (React)    │                         │  + Compression       │
└──────┬───────┘                         └─────────┬────────────┘
       │                                             │
       │                                   Prompt + Image
       │                                             │
       ▼                                             ▼
┌──────────────────┐                     ┌──────────────────────┐
│  UI State Layer  │ ◀──── Structured ── │   Gemini Adapter     │
│ (Guidance / Val) │        JSON         │ (safe parse + schema)│
└──────────────────┘                     └──────────────────────┘

Design intent:

• Explicit boundaries between UI, preprocessing, and model adapter.
• No raw model text reaches the UI without schema validation.

---

Gemini integration — operational notes

• Use canonical env var GEMINI_API_KEY. Replace any API_KEY references.
• Avoid direct JSON.parse of model text. Use a cleaning step, safe parse, and a zod schema to validate the final object.

Recommended model output schema (conceptual)

const ModelOutputSchema = z.object({
  mode: z.union([z.literal('guidance'), z.literal('validation')]),
  fields: z.record(z.string(), z.object({ value: z.string(), confidence: z.number().min(0).max(1), suggestion: z.string().optional() })),
})

Safe parse pattern

function safeJsonParse(text: string) {
  const cleaned = text.replace(/^```(?:json)?
?|
?```$/g, '')
  try { return JSON.parse(cleaned) } catch { throw new Error('Invalid JSON from model') }
}

---

Tests to include (priority)

• Unit tests for services/geminiService.ts that mock @google/genai and validate retries/parse behavior.
• Snapshot and interaction tests for ImageUploader and result components.
• Integration test (mocked) covering both guidance and validation flows.

---

CI (GitHub Actions) — minimal snippet

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - run: npm test --if-present

---

Security & privacy

• Images may contain sensitive data: add an explicit UI and README privacy notice: "Images are sent to a third‑party API for processing." Provide a local-only mode or an optional opt-out.
• Add .env.local to .gitignore.

Data Notice Images contain sensitive data. They are sent to a third‑party API for processing.

Local Option Provide local-only mode or opt-out

Env Security `.env.local` in `.gitignore` — always!

---

🤝 Contributing We ❤️ contributions! Here's how to get started:

🐛 Report Bugs Open an issue with clear steps to reproduce	💡 Suggest Features Describe the problem you're solving, not just the solution
📝 Improve Docs Better explanations, examples, typos	🔧 Submit PRs Check out good-first-issue label

bash # Fork → Clone → Branch → Commit → Push → PR git checkout -b feat/your-amazing-idea git commit -m "feat: add something awesome" git push origin feat/your-amazing-idea

Suggested next steps (for polish)

• Add an animated hero GIF showing the upload → result flow in assets/ and reference it in this README.
• Host a small demo (GitHub Pages / Vercel) and link it in the top section.
• Add screenshots for both guidance and validation result states.
• Add a CONTRIBUTING.md and CODE_OF_CONDUCT.md to improve project maturity.

_{Built with ❤️ by Tanmay Kunjir & Anshika Mishra
⭐ Star us on GitHub — it helps others discover the project!}

---

License

MIT — see LICENSE.