Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

Engineering reference: For service contracts, EventBus events, and data-layer details see src/features/ai/ai.md.

​

AI Feature - GrantMaster

​

Overview

• GrantMaster Chat Interface — Full-featured AI chat with project context awareness
• Grant Assistant Sidebar — Embedded chat widget for contextual queries across the app
• Document Intelligence — RAG-based document analysis and metadata extraction
• AI-Generated Insights — Budget forecasts, compliance checks, expense eligibility, report narratives, and journal submission analysis
• Multi-Modal Analysis — Receipt OCR, document classification, and vision-based content extraction
• Conversation Memory — localStorage-backed chat session persistence with citations

​

Architecture

┌─────────────────────────────────────────────────────────────┐
│  UI Components (Chat, Sidebars, Pages)                      │
├─────────────────────────────────────────────────────────────┤
│  State Management (useGrantAssistantState, ChatHistoryService)│
├────────────────────┬────────────────────────────────────────┤
│  RAG Pipeline      │  Gemini Services                       │
│  - Retrieval       │  - Journal generation (Cloud Function) │
│  - Chunking        │  - Grant assistant queries             │
│  - Embedding       │  - Compliance analysis                 │
│  - Cache           │  - Report narratives                   │
│                    │  - Forecast generation                 │
│                    │  - Vision/OCR analysis                 │
├────────────────────┴────────────────────────────────────────┤
│  Document Processing                                         │
│  - Upload & chunking                                         │
│  - Embedding generation                                      │
│  - Metadata extraction (deadlines, activity rules)           │
├─────────────────────────────────────────────────────────────┤
│  External APIs                                               │
│  - Google Gemini (gemini-1.5-pro, gemini-1.5-flash, vision) │
│  - Genkit Cloud Functions (fallback for journal generation)  │
│  - Firebase Storage (document files)                         │
│  - Firestore (document metadata, processed-documents)        │
└─────────────────────────────────────────────────────────────┘

​

Data Model

​

Core Collections & Types

​

Key Types

// Chat Message (localStorage-backed)
interface Message {
  id: string;
  role: 'user' | 'model';
  text: string;
  timestamp: Date;
  citations?: DocumentCitation[];  // References to source documents
}

// Chat Session (localStorage-backed)
interface ChatSession {
  id: string;
  title: string;
  createdAt: Date;
  updatedAt: Date;
  messages: Message[];
  organizationId: string;
  userId: string;
  isArchived: boolean;
}

// Document Processed for RAG
interface ProcessedDocument {
  id: string;
  organizationId: string;
  projectId: string;
  filename: string;
  fileName: string;
  fileSize: number;
  storagePath: string;
  uploadedBy: string;
  uploadedAt: string;
  processingStatus: 'uploading' | 'processing' | 'completed' | 'failed';
  chunkCount: number;
  version: number;
  isLatest: boolean;
  metadata: {
    documentType: string;
    fileSize: number;
    mimeType: string;
  };
}

// RAG Query Response
interface RAGQueryResponse {
  answer: string;
  sources: DocumentChunk[];
  confidence: number;
  metadata: Record<string, unknown>;
}

// Prompt Template
interface PromptTemplate {
  id: string;
  title: string;
  description: string;
  promptText: string;
  category: 'budget' | 'compliance' | 'reporting' | 'general' | 'custom';
  isSystemTemplate: boolean;
  icon?: string;
}

​

Zod Schemas

• journalSchema — Journal entry validation
• geminiSchemas.* — Response validation for compliance checks, expense analysis, forecasts

​

Key Behaviors

​

1. Grant Assistant Chat Interface

• Full-screen AI chat with category-based quick prompts (Budget, Reporting, Documents, etc.)
• Smart Context Selection: When user is in a project, queries are routed to RAG for document-grounded responses
• Generic Fallback: Outside project context, uses general grant assistant for broad queries
• Message Persistence: Sessions saved to localStorage, sorted by updatedAt
• Citation Display: Sources from retrieved documents shown inline via CitationDisplay

​

2. Embedded Grant Assistant Sidebar

• Collapsible sidebar widget integrated into pages
• Shares state with full-page chat via useGrantAssistantState
• Same RAG/Assistant routing logic as full interface
• Quick actions: Create new session, delete conversations, clear history
• Responsive: Collapses on mobile, shows hover tooltip

​

3. Document Upload & RAG Processing

1. User uploads file → uploadAndProcessDocument() creates ProcessedDocument record
2. File stored in Firebase Storage (project-documents/{org}/{project}/{filename})
3. Status tracked: uploading → processing → completed / failed
4. Cloud Function chunks document, extracts metadata (deadlines, activity rules), generates embeddings
5. Chunks stored in Firestore with vector embeddings for retrieval
6. User can query document context via RAG

• uploadAndProcessDocument(file, projectId, orgId, userId) — Initiates upload
• getDocumentStatus(documentId) — Check processing progress
• subscribeToDocumentStatus(documentId, callback) — Real-time updates
• listProjectDocuments(projectId, orgId) — List all documents in a project
• retryDocumentProcessing(documentId) — Retry failed documents
• deleteDocument(documentId) — Remove document and chunks
• getAllProcessedDocuments(organizationId) — Full org document list

​

4. RAG Query & Retrieval

1. User query → queryRAGAuto(projectId, organizationId, userId, queryText)
2. Embedding generated for user query
3. Vector search retrieves top-K relevant chunks from document corpus
4. Chunks + user query → Gemini context window
5. Response includes citations (document source metadata)

• queryRAG(query, documents) — Core RAG pipeline (client-side)
• queryRAGAuto(projectId, orgId, userId, queryText) — Intelligent routing (client + Cloud Function fallback)
• queryRAGCloudFunction(...) — Server-side RAG (Genkit)
• retrieveRelevantChunks(query, documents) — Vector retrieval
• storeDocumentChunks(projectId, chunks) — Persist chunks
• chunkText(text) — Split documents into overlapping chunks
• generateEmbedding(text) — Get vector representation
• extractDeadlines(text) — Metadata extraction
• extractActivityRules(text) — Grant eligibility rules from documents

​

5. AI-Powered Insights

​

Journal Entry Generation

• Trigger: Journal submission flow (end-of-month reflection)
• Input: User notes, notable events, project assignments
• Output: Auto-generated JournalEntry[] with time allocations
• Implementation: Cloud Function via generateJournalEntries(input, projects, user, org)
• Fallback: Client-side Gemini if Cloud Function unavailable
• Tracking: Usage tracked via trackAiGeneration() for billing

​

Compliance Analysis

• Service: analyzeCompliance(organizationId, projects)
• Checks: Policy violations, missing documentation, audit readiness
• Output: Structured compliance alerts with severities

​

Expense Eligibility

• Service: checkExpenseEligibility(expense, grantTerms)
• Logic: Validates expense against grant agreement restrictions
• Output: Eligibility verdict + explanation

​

Budget Forecasts & Narratives

• Service: generateProjectForecast(project, expenses) — Predict burn rate, runway
• Service: generateReportNarrative(project, data) — Narrative summary of progress
• Output: Structured text for reports

​

Receipt & Document Analysis

• Service: analyzeReceipt(file) — OCR + metadata extraction
• Service: analyzeDocumentContent(file) — Vision-based content extraction
• Output: Extracted fields, amount, vendor, date

​

Proposal Impact Analysis

• Service: generateProposalSection(proposal, section) — Draft grant proposal sections
• Service: suggestMEIndicators(project) — Recommend impact metrics
• Service: generateMENarrative(indicators, data) — Impact narrative
• Service: detectMEAnomalies(data) — Anomaly detection in measurement data

​

6. Prompt Library

• System Prompts: Built-in templates across 5 categories (budget, compliance, reporting, general, custom)
• User Prompts: Custom prompts saved per organization/user
• Methods:
  • getAllPrompts(userId, orgId) — System + user combined
  • getPromptsByCategory(category, userId, orgId) — Filter by category
  • getUserPrompts(userId, orgId) — Custom only
  • savePrompt(title, desc, text, category, userId, orgId) — Create custom
  • deletePrompt(promptId) — Remove custom prompt

​

Service Contract

​

Events

​

Emitted Events

​

Consumed Events

​

Dependencies

​

Features That Depend on AI

• projects — Project context for RAG queries
• grants — Grant data for assistant queries, proposal generation
• users — User context for journal generation, chat sessions
• expenses — Expense eligibility checks
• documents — Document classification, upload handling (integrates with Document Brain)
• reports — Report generation, narrative composition
• billing — Tracks AI usage for credit/quota management
• compliance — Compliance analysis inputs/outputs
• impact — M&E indicator suggestions, anomaly detection

​

AI Feature Dependencies

• core — BaseService, eventBus, Firebase (Firestore, Storage, Functions), logger
• types — DocumentCitation, JournalEntry, ProcessedDocument, Project, Organization, User
• Google Gemini API — LLM inference
• Firebase Cloud Functions — Genkit-powered journal generation, RAG (cloud variant)
• Firebase Storage — Document file persistence
• Firestore — Document metadata (processed-documents collection)

​

File Structure

src/features/ai/
├── components/
│   ├── GrantAssistant.tsx            # Embedded sidebar widget (global)
│   ├── AIAssistantSidebar.tsx        # Sidebar layout wrapper
│   ├── ChatMessage.tsx               # Message rendering with citations
│   ├── WelcomeScreen.tsx             # Onboarding/empty state
│   ├── SidebarContent.tsx            # Sidebar navigation content
│   ├── tabs/                         # AI sub-feature tabs
│   │   ├── DigestTab.tsx
│   │   ├── DocumentQATab.tsx
│   │   └── PredictionsTab.tsx
│   └── pages/
│       ├── AIAssistantPage.tsx       # Main chat + tabbed AI interface
│       └── AIInsightsPage.tsx        # AI insights routing page
│
├── services/
│   ├── geminiService.ts              # Main export facade
│   ├── geminiServiceFacade.ts        # BaseService wrapper for DI
│   ├── geminiServiceCore.ts          # Journal generation + core endpoints
│   ├── geminiServiceProposalImpact.ts # Proposal/M&E AI functions
│   ├── geminiClient.ts               # Gemini API initialization, model config
│   ├── geminiRetry.ts                # Exponential backoff retry logic
│   ├── geminiJsonParser.ts           # JSON extraction from LLM responses
│   ├── geminiSchemas.ts              # Zod schemas for validation
│   ├── geminiAssistant.ts            # General assistant query handler
│   ├── geminiCompliance.ts           # Compliance analysis, expense eligibility
│   ├── geminiDocuments.ts            # Receipt/vision analysis
│   ├── geminiForecast.ts             # Budget forecast, report narratives
│   ├── responseSafety.ts             # Input validation, output sanitization
│   │
│   ├── ragService.ts                 # RAG export facade
│   ├── ragServiceFacade.ts           # BaseService wrapper for DI
│   ├── ragPipeline.ts                # Core RAG orchestration
│   ├── ragRetrieval.ts               # Vector retrieval, chunk ranking
│   ├── ragDocumentProcessing.ts      # Chunking, embedding generation
│   ├── ragDocumentManagement.ts      # Upload, status tracking, CRUD
│   ├── ragMetadata.ts                # Deadline/rule extraction
│   ├── ragCache.ts                   # Embedding caching
│   ├── ragTypes.ts                   # RAG type definitions
│   ├── ragShared.ts                  # Shared utilities
│   ├── ragLogging.ts                 # Debug logging for RAG
│   │
│   ├── chatHistoryService.ts         # Chat session persistence (localStorage)
│   ├── promptLibraryService.ts       # Prompt templates (localStorage)
│   ├── reportGeneration.ts           # Report template, PDF/Excel export
│   ├── roleChangeRecommendations.ts  # (utility)
│   ├── (visionService.ts removed — dead code, April 2026)
│   │
│   └── __tests__/
│       ├── contextAssembler.test.ts
│       ├── geminiRetry.test.ts
│       ├── geminiJsonParser.test.ts
│       ├── ragPipeline.test.ts
│       └── ranking.test.ts
│
├── hooks/
│   └── useGrantAssistantState.ts    # Chat panel visibility, input state
│
├── data/
│   └── defaultPrompts.ts            # Built-in prompt templates (budget, compliance, reporting, etc.)
│
├── index.ts                          # Public API barrel export
└── public.ts                         # (alternate public API)

​

Integration Points

​

With Other Features

• Projects: Provides project context for RAG; AIAssistantPage extracts projectId from route
• Grants: Grant data used in assistant queries, proposal generation
• Expenses: Feeds expense data to eligibility checker, forecaster
• Documents: Uploads integrated with document storage; RAG documents share Firebase Storage
• Reports: AI generates report narratives; powered by reportGeneration service
• Billing: AI usage tracked via trackAiGeneration() for credit/token counting
• Compliance: AI analyzes compliance status; outputs feed compliance alerts

​

With External APIs

• Google Gemini (gemini-1.5-pro, gemini-1.5-flash) — Main LLM inference
• Gemini Vision — Document/receipt image analysis
• Firebase Cloud Functions (Genkit) — Server-side journal generation, RAG fallback
• Firebase Storage — Document file hosting
• Firestore — Document metadata, processed-document collection

​

Configuration

​

Environment Variables

• VITE_GEMINI_API_KEY — Google Gemini API key (required)

​

Feature Flags / Constants

• USE_CLOUD_FUNCTIONS (geminiClient.ts) — Route journal generation to Cloud Function (Genkit)
• MODEL_NAME (geminiClient.ts) — Active Gemini model (defaults to gemini-1.5-flash)
• MAX_SESSIONS (chatHistoryService.ts) — Max chat sessions per user (default: 50)
• STORAGE_KEY (chatHistoryService.ts) — localStorage key for sessions

​

Models & Limits

• Primary Model: gemini-1.5-flash (speed, cost-optimized)
• Fallback: gemini-1.5-pro (for complex reasoning if configured)
• Vision Model: gemini-1.5-pro-vision-128k (receipt/document analysis)
• Token Limits: Context windows respect Gemini tier limits; large documents chunked to stay within limits

​

Testing

​

Unit Tests (Vitest)

• geminiRetry.test.ts — Retry logic validation
• geminiJsonParser.test.ts — JSON extraction from LLM responses
• ragPipeline.test.ts — RAG orchestration flow
• ranking.test.ts — Chunk ranking/relevance scoring
• contextAssembler.test.ts — Context building for prompts

​

E2E Tests (Playwright)

• AI chat flow (message send/receive, context switching)
• Document upload & processing
• RAG query with citations
• Session persistence across page reloads

​

Common Development Tasks

​

Adding a New AI-Powered Feature

1. Create service function in services/gemini*.ts or services/rag*.ts
2. Add to GeminiService facade (geminiServiceFacade.ts) if using BaseService DI
3. Export via index.ts public API
4. Add tests to services/__tests__/
5. Integrate UI in components that need the feature

​

Adding Document Types / RAG Metadata

1. Extend extraction logic in ragMetadata.ts (deadlines, rules, etc.)
2. Update CloudFunction (if using server-side processing)
3. Test extraction with sample documents
4. Document type mappings in defaultPrompts.ts or feature config

​

Adding Prompt Templates

1. Update defaultPrompts.ts — Add to defaultPrompts[] array
2. Category: Choose from 'budget', 'compliance', 'reporting', 'general', 'custom'
3. Icon: Optional emoji or Lucide icon name
4. Test: Via UI category navigation

​

Performance Considerations

• Chunking: Large documents split with overlaps (default: ~1000 tokens) to stay within context windows
• Caching: RAG embeddings cached in-memory to avoid regeneration
• Lazy Loading: Components use React.lazy() for code splitting
• Streaming (future): Consider streaming Gemini responses for real-time UX
• Rate Limiting: Implement backoff for API rate limits (see geminiRetry.ts)
• Session Limit: Max 50 chat sessions per user (localStorage optimization)

​

Security & Privacy

• No Sensitive Data in Context: Credentials, passwords, financial account numbers excluded from prompts
• Response Filtering: responseSafety.ts validates outputs
• Storage: Chat sessions stored in browser localStorage (client-side, not synced)
• PII Handling: User/project data anonymized in bulk AI operations if applicable
• API Keys: Gemini key stored in .env.local, never exposed to client (via Cloud Function in production)

​

Known Limitations

1. Chat Sessions: Stored client-side (localStorage) — not synced across devices/browsers
2. Document Size: Very large PDFs may require chunking tuning; OCR accuracy depends on image quality
3. Context Window: Gemini context limits may truncate very long document sets in RAG
4. Real-time Collaboration: Chat is single-user; no multi-user chat synchronization
5. Prompt Customization: Limited to text; no template variables or conditional logic yet

​

Related Documentation

• Intelligence Platform (docs/product/features/intelligence-platform.md) — Cross-org anonymized benchmarks, separate from AI feature
• Document Brain (docs/product/features/document-brain.md) — Document classification, versioning, workflow; integrates with AI for analysis
• EventBus Architecture (docs/engineering/architecture/base-service-and-eventbus.md) — Service coordination (GeminiService/RAG extend BaseService)
• Firebase Integration (docs/engineering/architecture/firebase.md) — Storage, Firestore, Cloud Functions setup
• API Reference (docs/engineering/api-reference/) — Service method signatures

​

Version History