LexiChain/README.md

# LexiChain

<p align="center">
  <img src="public/LexiChain.png" alt="LexiChain logo" width="180" />
</p>

<p align="center">
  BFSI document intelligence platform that combines AI-assisted analysis with blockchain-backed verification.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Next.js-16-000000?logo=nextdotjs&logoColor=white" alt="Next.js badge" />
  <img src="https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black" alt="React badge" />
  <img src="https://img.shields.io/badge/Hardhat-Smart%20Contracts-FFF100?logo=ethereum&logoColor=black" alt="Hardhat badge" />
  <img src="https://img.shields.io/badge/Prisma-Database%20Layer-2D3748?logo=prisma&logoColor=white" alt="Prisma badge" />
  <img src="https://img.shields.io/badge/Clerk-Auth%20Ready-3B82F6?logo=clerk&logoColor=white" alt="Clerk badge" />
</p>

LexiChain is a team-ready platform for uploading documents, extracting important information, verifying integrity, and tracking records through a polished enterprise interface. It combines a modern Next.js frontend, a Solidity/Hardhat blockchain module, PostgreSQL with Prisma, and Clerk authentication.

## Overview

LexiChain is designed for banking, financial services, and insurance workflows where documents must be understandable, traceable, and trustworthy.

It addresses four core needs:

- converting dense documents into structured, reviewable insights
- reducing repetitive validation and manual review work
- preserving tamper-evident proof for uploaded files
- giving end users a clearer and more professional contract experience

## Product Highlights

- AI document analysis powered by Gemini
- OCR-based ingestion for digital and scanned documents
- automated extraction of key contract details
- chat-style retrieval over document content
- blockchain proof-of-existence for uploaded files
- document verification against on-chain hashes
- secure authentication and per-user access control
- dashboard views for contracts, contacts, and claims workflows
- responsive UI with a dark, premium visual style

## Visual Preview

The screenshots in [public/screens](public/screens) are intentionally included to make the README feel like a product page and to help new contributors understand the interface quickly.

| Landing page                                     | Dashboard                                       |
| ------------------------------------------------ | ----------------------------------------------- |
| ![Landing page](public/screens/landing_page.png) | ![Dashboard](public/screens/dashboard_dark.png) |

| Login                                          | Register                                             |
| ---------------------------------------------- | ---------------------------------------------------- |
| ![Login screen](public/screens/login_dark.png) | ![Register screen](public/screens/register_dark.png) |

| Contracts                                            |
| ---------------------------------------------------- |
| ![Contracts view](public/screens/contracts_dark.png) |

## Architecture

LexiChain follows a practical feature-oriented structure:

- [app](app) contains the Next.js app router, layouts, and pages
- [components](components) contains shared UI and layout building blocks
- [features](features) contains feature-level business logic
- [hooks](hooks) contains reusable client hooks
- [lib](lib) contains shared utilities and helpers
- [prisma](prisma) contains database schema files
- [blockchain](blockchain) contains the Hardhat project and smart contracts
- [public/screens](public/screens) contains screenshots and visual assets

The solution is split across three main concerns:

| Layer      | Purpose                                               |
| ---------- | ----------------------------------------------------- |
| Frontend   | UI, dashboards, forms, and user interactions          |
| Backend    | Server actions and API routes for business workflows  |
| Blockchain | Smart contract registration and document verification |

## Tech Stack

| Area           | Stack                                |
| -------------- | ------------------------------------ |
| Frontend       | Next.js 16, React 19, Tailwind CSS   |
| Backend        | Next.js server actions, API routes   |
| AI             | Google Gemini                        |
| Blockchain     | Solidity, Hardhat, Ethers.js         |
| Database       | PostgreSQL, Prisma                   |
| Authentication | Clerk                                |
| UI Components  | Radix UI, shadcn/ui-style primitives |

## Prerequisites

- Node.js 20 or later
- npm
- PostgreSQL database
- a local or remote blockchain endpoint for development and deployment
- environment variables for Clerk, Gemini, database, and blockchain access

## Environment Variables

The exact values depend on your deployment target, but the project expects environment configuration for the following areas:

| Area           | Typical Variables                              |
| -------------- | ---------------------------------------------- |
| App            | `NODE_ENV`, app URL settings                   |
| Database       | `DATABASE_URL`                                 |
| Authentication | Clerk publishable and secret keys              |
| AI             | Gemini API key or equivalent model credentials |
| Blockchain     | RPC URL, contract address, private key         |

Keep secrets in environment variables and never commit them to the repository.

## Installation

Install the root application dependencies first:

```bash
npm install
```

Then install the blockchain workspace dependencies:

```bash
cd blockchain
npm install
```

## Local Development

The recommended development command starts the app together with the local chain workflow:

```bash
npm run dev
```

This runs the bootstrap script defined in the root package and is the best option when you want the frontend and blockchain pieces aligned locally.

If you only need the Next.js app without the chain bootstrap, run:

```bash
npm run dev:next
```

## Scripts

### Root workspace

| Command                  | Description                                 |
| ------------------------ | ------------------------------------------- |
| `npm run dev`            | Starts the combined development workflow    |
| `npm run dev:with-chain` | Alias for the combined development workflow |
| `npm run dev:next`       | Runs only the Next.js dev server            |
| `npm run build`          | Builds the production application           |
| `npm run start`          | Starts the production server                |
| `npm run lint`           | Runs ESLint                                 |

### Blockchain workspace

| Command                  | Description                          |
| ------------------------ | ------------------------------------ |
| `npm run compile`        | Compiles the smart contracts         |
| `npm run test`           | Runs the Hardhat test suite          |
| `npm run node`           | Starts a local Hardhat node          |
| `npm run deploy:local`   | Deploys to the local Hardhat network |
| `npm run deploy:sepolia` | Deploys to Sepolia                   |

## Deployment

This is the clean production path for option 3 in the README.

```bash
npm run build
npm run start
```

Before deploying, verify:

- environment variables are set correctly
- the database is reachable
- the blockchain contract address and RPC settings are valid
- the code passes linting and any required tests

## Team Notes

These are the implementation details future contributors should know before extending the app:

- Contract records store the internal application user id, not the Clerk user id; resolve the Clerk user first before querying contract data.
- The upload flow triggers analysis automatically after saving a contract, so the UI should show analysis-in-progress feedback immediately.
- Dashboard and contacts routes live under `/dashboard` and `/contacts`.
- Trend charts should be aggregated by day with zero-filled windows so 30-day views stay accurate.
- Q&A over contracts uses Gemini embeddings and an in-memory contract vector cache.
- Claim status updates are intentionally restricted; the UI should use the allowed next statuses for each claim instead of a global list.

## Contribution Guidelines

If you are continuing this project as a team, keep the following practices in mind:

- make focused changes and avoid mixing unrelated refactors with feature work
- keep environment-dependent values out of source control
- prefer the existing feature structure when adding new UI or business logic
- update screenshots when user-facing screens change significantly
- document workflow changes in the README or the relevant docs file

## Troubleshooting

- If the app does not start, verify your Node.js version and reinstall dependencies.
- If blockchain features fail, confirm the local node is running and the contract address points to a deployed contract.
- If authentication fails, recheck the Clerk environment variables and callback configuration.
- If database access fails, validate the Prisma connection string and database availability.

## Summary

LexiChain is a BFSI document intelligence platform built for contract review, verification, and operational clarity. The codebase is structured to be maintainable by a team, with a clear split between app, blockchain, data, and shared UI concerns.