Skip to main content

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/documents/documents.md.

​
Documents

​
Overview

Document Brain is an organization-wide intelligent document management system for NGOs and grant-dependent entities. It provides centralized document library management with folder hierarchies, AI-powered classification, version history tracking, approval workflows, and extraction of metadata (deadlines, budgets, contacts, compliance rules) from documents. Key capabilities:
  • Drag-and-drop file upload with automatic AI classification
  • Folder hierarchy with system (by-funder, by-project, templates, compliance) and custom folders
  • Status-based approval workflow: Draft → Pending Review → Approved/Rejected/Archived
  • Version history timeline with audit trail
  • Template library for common NGO documents
  • Metadata extraction: deadlines, budget items, contacts, compliance rules
  • Real-time subscriptions for documents and folders
  • Recommendation engine for document gaps and suggestions

​
Data Model

​
Firestore Collections

CollectionDocument TypeDescription
document-libraryLibraryDocumentCore documents stored by organization; includes metadata, classification, approval status, version history
document-foldersDocumentFolderFolder hierarchy with parent references, system folder keys, document counts, permissions

​
Key TypeScript Types

LibraryDocument (from documents-brain.schema)
  • id, organizationId, title, description, fileSize, mimeType, filePath (Storage reference)
  • folderId? - Parent folder reference
  • documentType - Extended taxonomy (grant_agreement, invoice, progress_report, etc.; 40+ types)
  • sensitivity - public | internal | confidential | restricted
  • status - draft | pending_review | approved | rejected | archived | superseded
  • classification - AI-extracted tags, compliance areas (governance, financial, personnel, etc.)
  • approvalHistory[] - ApprovalAction records with userId, timestamp, status transitions
  • currentReviewerId?, reviewRequestedAt? - Approval workflow state
  • versions[] - DocumentVersion objects (uploadedBy, uploadedAt, checksum, fileSize, reason)
  • usageRecords[] - UsageRecord objects for citation/provenance tracking (viewedAt, downloadedAt, citedInDocId)
  • extractedMetadata? - ExtractedDeadline, ExtractedBudgetItem, ExtractedContact, ExtractedComplianceRule
  • createdBy, updatedBy + timestamps
DocumentFolder (hierarchy)
  • id, organizationId, parentId? - null = root
  • name, type - “system” | “custom”
  • systemFolderKey? - One of: by-funder, by-project, templates, compliance, policies, archive, uncategorized
  • documentCount - Running count of documents in folder
  • createdBy, timestamps
DocumentTemplate
  • id, organizationId, category - org_description, budget, narrative, theory_of_change, policy, etc.
  • name, description, content (template text or Markdown)
  • tags[], createdBy, timestamps
ApprovalAction
  • id, actionType - “submitted” | “approved” | “rejected” | “restored”
  • fromStatus, toStatus - Status transitions
  • userId, userName, timestamp
  • notes? - Reason for approval/rejection
DocumentVersion
  • id, uploadedBy, uploadedAt, checksum, fileSize, reason?
UsageRecord
  • viewedAt?, downloadedAt?, citedInDocId?

​
Key Behaviors

​
Upload & Classification

  1. User selects file and metadata (title, description, sensitivity, tags, optional folder)
  2. File uploaded to Firebase Storage with progress tracking
  3. DocumentBrainService creates document record with status=“draft”
  4. AI classification service (Gemini) extracts tags, compliance areas, deadlines, budgets, contacts if enabled
  5. DOCUMENT_UPLOADED event emitted (INFO severity, persisted)
  6. Document available for review by authorized users

​
Approval Workflow

Draft State (Initial)
  • Document editable by creator
  • Can update metadata (title, description, tags)
  • Can submit for review
Pending Review
  • Assigned to reviewer (currentReviewerId)
  • Reviewer can approve or reject
  • DOCUMENT_REVIEW_REQUESTED event emitted (INFO)
Approved
  • Document locked, read-only
  • Available for organization-wide use
  • Citation/provenance tracked in usageRecords
  • DOCUMENT_APPROVED event emitted (HIGH severity, persisted)
Rejected
  • Returns to draft or archived
  • Reason and reviewer feedback captured in approvalHistory
  • Can resubmit
  • DOCUMENT_REJECTED event emitted (HIGH severity)
Archived/Superseded
  • Marked obsolete; hidden from default views
  • Retained for audit trail

​
Folder Management

  • System folders auto-created on organization init
  • Custom folder hierarchy with drag-drop move support
  • Parent folder permissions inherited by child documents
  • documentCount auto-incremented on upload, decremented on delete
  • Breadcrumb navigation for folder traversal

​
Version History

  • New version created when document reuploaded (e.g., amended grant)
  • Previous versions retained in versions[] array with upload metadata
  • Checksum prevents identical file duplicates
  • Version reason stored for audit trail (e.g., “Corrected typo”, “Updated budget”)

​
Metadata Extraction & Gap Analysis

  • Genkit-powered extraction of deadlines, budget items, contacts, compliance rules from uploaded documents
  • RecommendationEngine analyzes document gaps (missing compliance docs, templates needed)
  • GapAnalysisWidget displays recommended actions
  • Suggestions contextual to organization’s active grants and projects

​
Service Contract

ServiceOwnsKey Methods
DocumentBrainServiceDocument CRUD, lifecycle, approval workflowsuploadDocument, deleteDocument, moveToFolder, updateDocumentMetadata, submitForReview, approveDocument, rejectDocument, listDocuments(organizationId, folderId?, filters?), subscribeToFolder(orgId, folderId, onDocumentsUpdate)
DocumentFolderServiceFolder hierarchy, tree operations, path resolutioncreateFolder(request, orgId, userId), deleteFolder(folderId, force), updateFolder(folderId, { name }), moveFolder({ folderId, newParentId }), listFolders(orgId, parentId?), getFolderTree(orgId), getBreadcrumbs(folderId, orgId), subscribeToFolders(orgId, parentId, onFoldersUpdate)
DocumentClassificationServiceAI classification and metadata extractionclassifyDocument(documentId, orgId), confirmClassification(documentId, classification, orgId)
RecommendationEngineGap analysis and suggestionsanalyzeGaps(organizationId): GapAnalysisResult, getRecommendations(context): DocumentRecommendation[]
All service methods return ServiceResult<T> with .success, .data, .error fields.

​
Events

​
Emitted

EventTriggerSeverityPersisted
DOCUMENT_UPLOADEDFile uploaded, document createdINFOYes
DOCUMENT_REVIEW_REQUESTEDsubmitForReview() calledINFOYes
DOCUMENT_APPROVEDapproveDocument() calledHIGHYes
DOCUMENT_REJECTEDrejectDocument() calledHIGHYes
DOCUMENT_VERSION_CREATEDNew version uploadedINFONo
DOCUMENT_CLASSIFIEDAI classification completedINFONo
DOCUMENT_DEADLINE_EXTRACTEDDeadline metadata extracted from docINFONo
All document events include documentId, documentTitle, organizationId, userId, timestamp, and relevant contextual payload (reviewer info, reason for rejection, extracted metadata).

​
Consumed

None explicitly. Document Brain does not subscribe to or react on system events; it is a primary event emitter.

​
Dependencies

  • Firebase: Firestore (document-library, document-folders collections), Cloud Storage (file storage), Auth (user context)
  • React Query: For server state management via tRPC queries
  • Genkit/Gemini API: AI classification and metadata extraction
  • EventBus: Centralized event emission for cross-feature coordination
  • BaseService: Audit logging (AuditAction), service patterns
  • TenantContext: Multi-org isolation via organizationId
  • UserContext: Current user profile for audit trail

​
File Structure

src/features/documents/
├── DocumentBrainContext.tsx          # React context + provider (state management via reducer)
├── contracts.ts                       # Type re-exports from documents-brain.schema
├── index.ts                           # Public API barrel export
│
├── components/
│   ├── DocumentBrowser.tsx            # Main library UI (grid/list view, filters, sort)
│   ├── DocumentCard.tsx               # Document grid/list item
│   ├── FolderCard.tsx                 # Folder representation
│   ├── DocumentDetailPanel.tsx        # Read-only detail sidebar
│   ├── UploadDropzone.tsx             # Basic drag-drop upload
│   ├── SmartUploadDropzone.tsx        # Enhanced upload with classification preview
│   ├── CreateFolderDialog.tsx         # New folder creation
│   ├── ClassificationConfirmModal.tsx # AI classification review before apply
│   ├── GapAnalysisWidget.tsx          # Gap analysis + recommendations
│   ├── OrganizationDocumentsTab.tsx   # Library tab in org settings
│   ├── MyDocumentsTab.tsx             # Personal document vault tab
│   ├── PersonalDocumentVault.tsx      # User's personal docs (separate org context)
│   ├── PersonalDocumentCard.tsx       # Personal doc item
│   ├── PersonalUploadDialog.tsx       # Personal doc upload
│   └── document-shared.ts             # Shared component utilities
│
├── pages/
│   └── DocumentBrainPage.tsx          # Full page layout (sidebar nav, main browser)
│
├── services/
│   ├── DocumentBrainService.ts        # Document CRUD, lifecycle (extends BaseService)
│   ├── DocumentFolderService.ts       # Folder operations (extends BaseService)
│   ├── DocumentClassificationService.ts  # AI classification via Genkit
│   ├── RecommendationEngine.ts        # Gap analysis algorithm
│   ├── documentBrainApproval.ts       # Approval workflow functions (submitForReview, approve, reject)
│   ├── documentBrainMutations.ts      # Upload, delete, move mutations
│   └── documentBrainQueries.ts        # Firestore read queries
│
├── document-brain/
│   ├── state.ts                       # DocumentBrainState, reducer, initial state
│   ├── useDocumentBrainInitialLoad.ts # Initial data load hook
│   └── [composition hooks]            # useDocumentBrainLoader, useDocumentBrainDocumentActions, etc.
│
├── hooks/
│   └── useDocumentBrainPageState.ts   # Computed state for page (filters, selection, UI)
│
└── __tests__/
    └── DocumentBrainContext.test.ts   # Context + reducer tests
Composition Pattern: DocumentBrainContext exports multiple specialized hooks (useDocumentBrainLoader, useDocumentBrainDocumentActions, useDocumentBrainFolderActions, useDocumentBrainNavigation, useDocumentBrainSelection, useDocumentBrainFilters, useDocumentBrainUI) that are composed into the main useDocumentBrain() hook for clean separation of concerns.