375 lines
13 KiB
Markdown
375 lines
13 KiB
Markdown
# 02 — Services Reference
|
|
|
|
All domain services live in `lib/services/`. They are plain TypeScript classes with static methods — no instantiation needed. Services are **server-only** (never imported in client components).
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [AIService](#1-aiservice)
|
|
2. [RAGService](#2-ragservice)
|
|
3. [BlockchainService](#3-blockchainservice)
|
|
4. [ContractService](#4-contractservice)
|
|
5. [NotificationService](#5-notificationservice)
|
|
6. [EmailService](#6-emailservice)
|
|
7. [StatsService](#7-statsservice)
|
|
8. [CertificateService](#8-certificateservice)
|
|
9. [StorageService](#9-storageservice)
|
|
|
|
---
|
|
|
|
## 1. AIService
|
|
|
|
**File:** `lib/services/ai.service.ts`
|
|
**Sub-modules:** `lib/services/ai/` (parser, normalizer, prompt builder, key manager)
|
|
|
|
### Purpose
|
|
Extracts structured information from uploaded contract documents (PDF or image). Implements a multi-model fallback chain with automatic retry and JSON repair.
|
|
|
|
### Pipeline
|
|
|
|
```
|
|
File URL
|
|
↓
|
|
Download bytes + resolve MIME type
|
|
↓
|
|
Pre-validation (is this actually a contract?)
|
|
↓
|
|
Build adaptive prompt (with context from previous analyses)
|
|
↓
|
|
[Attempt 1..N]
|
|
│
|
|
├── Try Gemini primary model (key rotation across AI_API_KEY1/2/3)
|
|
├── Try Gemini secondary model (if AI_MODEL_SECONDARY_GEMINI is set)
|
|
├── Try Gemini with lenient settings (last Gemini attempt)
|
|
│
|
|
└── If all Gemini models fail → Mistral Fallback
|
|
├── PDF: extract text via pdf-parse → ground Mistral on text
|
|
└── Image: send to Pixtral vision model directly
|
|
↓
|
|
Parse JSON → normalize → validate
|
|
↓
|
|
On parse failure: call Mistral repair model → emergency field extraction
|
|
↓
|
|
Return NormalizedAnalysis
|
|
```
|
|
|
|
### Key Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `analyzeContract(fileUrl, options?)` | Main entry point — full extraction pipeline |
|
|
| `askAboutContract(question, contract, userId?)` | RAG-grounded Q&A on an analyzed contract |
|
|
| `preValidateContract(input)` | Quick pre-check to reject non-contract files |
|
|
| `buildAdaptiveContext(userId?)` | Builds few-shot examples from user's previous contracts |
|
|
|
|
### Configuration
|
|
|
|
| Environment Variable | Default | Description |
|
|
|---------------------|---------|-------------|
|
|
| `AI_API_KEY1` / `AI_API_KEY2` / `AI_API_KEY3` | — | Gemini API keys (rotated automatically) |
|
|
| `AI_MODEL_PRIMARY` | `gemini-2.5-flash-preview-04-17` | Primary Gemini extraction model |
|
|
| `AI_MODEL_SECONDARY_GEMINI` | — | Optional secondary Gemini model |
|
|
| `AI_EMBEDDING_MODEL` | `text-embedding-004` | Gemini embedding model for RAG |
|
|
| `MISTRAL_API_KEY` | — | Mistral API key (activates fallback) |
|
|
| `AI_MODEL_FALLBACK` | `mistral-large-latest` | Mistral text fallback model |
|
|
| `AI_MODEL_MISTRAL_VISION` | `pixtral-large-latest` | Mistral multimodal model for images |
|
|
| `AI_MODEL_MISTRAL_OCR` | `mistral-ocr-latest` | Mistral OCR model |
|
|
| `AI_FORCE_FALLBACK_TEST` | — | Set to `"1"` to bypass Gemini for testing |
|
|
|
|
### Sub-modules
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `ai/analysis.prompt.ts` | Builds the Gemini extraction prompt with few-shot examples |
|
|
| `ai/analysis.parser.ts` | Robust JSON parser with fence stripping and repair |
|
|
| `ai/analysis.normalizer.ts` | Normalizes raw AI output into `NormalizedAnalysis` shape |
|
|
| `ai/analysis.types.ts` | TypeScript types for AI input/output |
|
|
| `ai/key-manager.ts` | Round-robin Gemini API key rotation with quota exhaustion detection |
|
|
|
|
### Output Schema (`NormalizedAnalysis`)
|
|
|
|
```typescript
|
|
{
|
|
title: string | null
|
|
type: ContractType | null // enum: INSURANCE_AUTO, LOAN, etc.
|
|
provider: string | null
|
|
policyNumber: string | null
|
|
startDate: Date | null
|
|
endDate: Date | null
|
|
premium: number | null
|
|
summary: string
|
|
extractedText: string
|
|
keyPoints: {
|
|
guarantees: string[]
|
|
exclusions: string[]
|
|
franchise: string | null
|
|
importantDates: string[]
|
|
explainability: Array<{
|
|
field: string
|
|
why: string
|
|
sourceSnippet: string
|
|
sourceHints: { page: string|null, section: string|null, confidence: number }
|
|
}>
|
|
}
|
|
keyPeople: Array<{ name: string, role: string|null, email: string|null, phone: string|null }>
|
|
relevantDates: Array<{ date: string, description: string, type: string }>
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. RAGService
|
|
|
|
**File:** `lib/services/rag.service.ts`
|
|
|
|
### Purpose
|
|
Retrieval-Augmented Generation (RAG) — splits contract text into chunks, generates embeddings, stores them in PostgreSQL, and retrieves the most relevant chunks when answering user questions.
|
|
|
|
### How It Works
|
|
|
|
```
|
|
analyzeContract completes
|
|
↓
|
|
RAGService.indexContract(contractId, extractedText)
|
|
├── Split text into 512-token chunks with 64-token overlap
|
|
├── Generate embeddings via Gemini text-embedding-004
|
|
└── Store in ContractRagChunk table
|
|
|
|
User asks question
|
|
↓
|
|
RAGService.query(contractId, question)
|
|
├── Embed the question via text-embedding-004
|
|
├── Load all chunks for this contract from DB
|
|
├── Compute cosine similarity between question embedding and each chunk
|
|
└── Return top-K most relevant chunks
|
|
```
|
|
|
|
### Key Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `indexContract(contractId, text)` | Chunks, embeds, and stores contract text |
|
|
| `query(contractId, question, topK?)` | Returns most similar chunks to a question |
|
|
| `deleteIndex(contractId)` | Removes all RAG chunks for a contract |
|
|
|
|
### Storage
|
|
Chunks are stored in the `ContractRagChunk` model:
|
|
- `content` — raw chunk text
|
|
- `embedding` — float array (Gemini embedding vector)
|
|
- `contentHash` — SHA-256 of content (deduplication)
|
|
- `chunkIndex` — position in original document
|
|
|
|
---
|
|
|
|
## 3. BlockchainService
|
|
|
|
**File:** `lib/services/blockchain.service.ts`
|
|
|
|
### Purpose
|
|
Server-side Ethereum integration. Computes SHA-256 hashes of documents and registers them on the `DocumentRegistry` smart contract, providing tamper-proof, timestamped proof-of-deposit.
|
|
|
|
> **Important:** This service uses a **server-side wallet** (`JsonRpcProvider + Wallet`). Users do NOT need MetaMask or any wallet.
|
|
|
|
### How It Works
|
|
|
|
```
|
|
Contract file URL
|
|
↓
|
|
BlockchainService.hashDocument(fileUrl)
|
|
├── Downloads raw file bytes from UploadThing CDN
|
|
└── Computes SHA-256 → returns 0x-prefixed bytes32 string
|
|
|
|
↓
|
|
BlockchainService.registerOnChain(documentHash, fileName)
|
|
├── Calls contract.registerDocument(bytes32) via server wallet
|
|
├── Waits for transaction to be mined (1 confirmation)
|
|
├── Gets block timestamp → this becomes the legal proof date
|
|
└── Returns BlockchainProof { txHash, blockNumber, blockTimestamp, ... }
|
|
```
|
|
|
|
### Configuration
|
|
|
|
| Environment Variable | Description |
|
|
|---------------------|-------------|
|
|
| `BLOCKCHAIN_NETWORK` | `"hardhat"` (dev) or `"sepolia"` (production) |
|
|
| `BLOCKCHAIN_RPC_URL` | JSON-RPC endpoint (Sepolia public RPC or Alchemy/Infura) |
|
|
| `BLOCKCHAIN_PRIVATE_KEY` | Private key of the signing wallet (holds Sepolia ETH) |
|
|
| `BLOCKCHAIN_CONTRACT_ADDRESS` | Deployed `DocumentRegistry` contract address |
|
|
|
|
### Key Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `hashDocument(fileUrl)` | Downloads file and computes SHA-256 |
|
|
| `registerOnChain(hash, fileName)` | Registers hash on the smart contract |
|
|
| `hashAndRegister(fileUrl, fileName)` | Convenience: hash + register in one call |
|
|
| `verifyOnChain(documentHash)` | Read-only verification of a hash |
|
|
| `getNetworkStats()` | Returns network status, block number, total docs |
|
|
| `isConfigured()` | Returns false if env vars are missing (graceful degradation) |
|
|
|
|
### Graceful Degradation
|
|
If `BLOCKCHAIN_CONTRACT_ADDRESS` or `BLOCKCHAIN_PRIVATE_KEY` are not set, `isConfigured()` returns `false` and the app skips blockchain registration silently. The rest of the analysis pipeline completes normally.
|
|
|
|
---
|
|
|
|
## 4. ContractService
|
|
|
|
**File:** `lib/services/contract.service.ts`
|
|
|
|
### Purpose
|
|
CRUD operations and lifecycle management for Contract records. Acts as the single point of interaction with the `Contract` Prisma model.
|
|
|
|
### Status Machine
|
|
|
|
```
|
|
UPLOADED → PROCESSING → COMPLETED
|
|
└──→ FAILED
|
|
```
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| `UPLOADED` | File received, waiting for analysis |
|
|
| `PROCESSING` | AI analysis in progress |
|
|
| `COMPLETED` | Analysis done, blockchain registered |
|
|
| `FAILED` | Analysis failed (error stored) |
|
|
|
|
### Key Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `create(userId, fileData)` | Creates a new Contract record (status: UPLOADED) |
|
|
| `updateWithAIResults(id, analysis)` | Saves AI-extracted fields, sets status COMPLETED |
|
|
| `updateBlockchainProof(id, proof)` | Saves blockchain transaction details |
|
|
| `setProcessing(id)` | Sets status to PROCESSING |
|
|
| `setFailed(id, error)` | Sets status to FAILED with error message |
|
|
| `getById(id, userId)` | Fetches a contract, validates ownership |
|
|
| `listForUser(userId, filters?)` | Returns all contracts for a user |
|
|
| `deleteContract(id, userId)` | Deletes contract + cascades to chunks/notifications |
|
|
|
|
---
|
|
|
|
## 5. NotificationService
|
|
|
|
**File:** `lib/services/notification.service.ts`
|
|
|
|
### Purpose
|
|
Creates, reads, and manages in-app notifications. Also schedules deadline-based alerts for contracts nearing expiration.
|
|
|
|
### Notification Types
|
|
|
|
| Type | Trigger |
|
|
|------|---------|
|
|
| `SUCCESS` | Contract analysis completed |
|
|
| `ERROR` | Analysis failed |
|
|
| `INFO` | Blockchain registration, general events |
|
|
| `WARNING` | Contract nearing expiry (30 days) |
|
|
| `DEADLINE` | Contract expires in < 7 days |
|
|
|
|
### Key Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `createNotification(userId, data)` | Creates an in-app notification |
|
|
| `getUnread(userId)` | Returns all unread notifications |
|
|
| `markAsRead(id, userId)` | Marks a notification as read |
|
|
| `markAllAsRead(userId)` | Marks all as read |
|
|
| `checkDeadlines(userId)` | Scans contracts nearing expiry and creates alerts |
|
|
| `deleteExpired()` | Purges expired notifications |
|
|
|
|
---
|
|
|
|
## 6. EmailService
|
|
|
|
**File:** `lib/services/email.service.ts`
|
|
|
|
### Purpose
|
|
Sends transactional emails using Nodemailer over SMTP. Falls back to Ethereal (test inbox) when running outside production and no SMTP credentials are configured.
|
|
|
|
### Configuration
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `EMAIL_HOST` | SMTP server hostname (e.g., `smtp-relay.brevo.com`) |
|
|
| `EMAIL_PORT` | SMTP port (`587` for STARTTLS, `465` for SSL) |
|
|
| `EMAIL_SECURE` | `true` for SSL/TLS, `false` for STARTTLS |
|
|
| `EMAIL_USER` | SMTP username |
|
|
| `EMAIL_PASS` | SMTP password |
|
|
| `MAIL_FROM` | From address, e.g., `LexiChain <no-reply@yourdomain.com>` |
|
|
|
|
### Email Types Sent
|
|
|
|
| Email | Trigger |
|
|
|-------|---------|
|
|
| Contract analysis complete | AI analysis finishes successfully |
|
|
| Analysis failed | AI analysis encounters an error |
|
|
| Contract expiry warning | Contract expires within 30 days |
|
|
| Contract expiry imminent | Contract expires within 7 days |
|
|
| Blockchain registration | Document hash registered on-chain |
|
|
|
|
### Dev Fallback
|
|
If `EMAIL_HOST` is not set and `NODE_ENV !== production`, the service creates an [Ethereal](https://ethereal.email/) test account automatically. The preview URL is printed to the server console.
|
|
|
|
---
|
|
|
|
## 7. StatsService
|
|
|
|
**File:** `lib/services/stats.service.ts`
|
|
|
|
### Purpose
|
|
Computes aggregated analytics for the dashboard. All queries run server-side via Prisma.
|
|
|
|
### Metrics Provided
|
|
|
|
| Metric | Description |
|
|
|--------|-------------|
|
|
| Total contracts | Count of all user contracts |
|
|
| By status | Breakdown: UPLOADED / PROCESSING / COMPLETED / FAILED |
|
|
| By type | Distribution across ContractType enum values |
|
|
| By month | Monthly upload trend (last 12 months) |
|
|
| Expiring soon | Contracts expiring within 30/90 days |
|
|
| Average premium | Average premium across completed contracts |
|
|
| Blockchain coverage | % of contracts with on-chain proof |
|
|
| Recent activity | Last N contracts with status |
|
|
|
|
---
|
|
|
|
## 8. CertificateService
|
|
|
|
**File:** `lib/services/certificate.service.ts`
|
|
|
|
### Purpose
|
|
Generates downloadable PDF certificates of document registration using PDFKit. The certificate includes:
|
|
- Contract metadata (title, type, dates, provider)
|
|
- Document SHA-256 hash
|
|
- Blockchain transaction hash and block number
|
|
- Registration timestamp (block timestamp)
|
|
- QR code linking to Etherscan (Sepolia)
|
|
|
|
### Key Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `generateCertificate(contract)` | Returns a PDF Buffer for a completed+blockchain contract |
|
|
| `generateCertificateStream(contract)` | Returns a Node.js stream for streaming response |
|
|
|
|
---
|
|
|
|
## 9. StorageService
|
|
|
|
**File:** `lib/services/storage.service.ts`
|
|
|
|
### Purpose
|
|
Thin wrapper around UploadThing. Provides utilities for:
|
|
- Deleting uploaded files (cleanup on contract delete)
|
|
- Building file access URLs
|
|
- Validating file constraints
|
|
|
|
### Configuration
|
|
UploadThing is configured in `lib/upload.ts` and exposed via `app/api/uploadthing/`.
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `UPLOADTHING_TOKEN` | UploadThing authentication token |
|
|
| `UPLOADTHING_APP_ID` | UploadThing application ID |
|