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/impact-portal/impact-portal.md.

​

Impact Portal

​

Overview

• Organization profile & impact showcase for external audiences
• Stakeholder access tokens with granular visibility controls
• Session tracking and engagement analytics
• Content management with AI coaching
• Stakeholder comments and report acknowledgments

​

Data Model

​

Firestore Collections

​

Key TypeScript Types

• StakeholderType — ‘funder’ | ‘partner’ | ‘board’ | ‘auditor’
• PortalVisibility — 14 flags controlling what data stakeholders see (budget, milestones, team, compliance, reports, impact metrics, etc.)

• PortalToken — Access token with stakeholder name/email, expiry, creation/revocation metadata, IP restrictions, visibility config, and usage tracking (access count, last accessed, IP addresses)
• PortalSession — Created when stakeholder accesses portal; tracks IP, user agent, pages viewed, and actions performed (view_dashboard, view_report, download_report, acknowledge_report, request_revision, post_comment, view_budget, view_milestones, submit_document)
• PortalSessionAction — Granular action record within a session with timestamp, target entity ID, and metadata

• PortalComment — Threaded discussion (supports parentId for nested replies), markdown content, read/unread status, optional attachments
• PortalCommentAttachment — File stored in Firebase Storage with size and MIME type
• PortalSubmission — Stakeholder document submission with review workflow (submitted → under_review → accepted/rejected)
• PortalReportAcknowledgment — Donor feedback on reports (received/approved/revision_requested) with optional revision notes and org resolution

• PortalAnalyticsModel — Daily visits, dwell time by section, engagement rows (per stakeholder), totals for visits/pageviews/downloads/comments/acknowledgments
• PortalShowcaseModel — Impact metrics (SDGs, beneficiaries, outcomes), geographies, key outcomes derived from M&E indicators
• PortalCoachModel — AI coaching with category scores, recommendations, total/potential scores

• PortalProjectData — Filtered project/org data returned after token validation (respects visibility flags), includes branding, project details, budget, milestones, team, compliance, impact, reports, comments

​

Key Behaviors

​

Token Lifecycle

1. Creation — Admin creates token for project; Firestore stores with unique ID, expiry (default 1 year), default visibility config
2. Validation — Stakeholder accesses portal URL with token ID; Cloud Function validates token (active, not expired, not revoked, rate limits via PortalSystemConfig)
3. Access — Token valid → stakeholder sees org branding + filtered project data (visibility controls what’s visible)
4. Session Tracking — Cloud Function creates PortalSession on first access; logs subsequent page views and actions
5. Revocation — Admin can revoke token; sets isActive=false, records revocation reason/timestamp/user

​

Visibility Control

• Financial: budget utilization (%), actual amounts (€), line-item breakdown
• Timeline: project dates, current phase
• Team: member names (no rates)
• Compliance: traffic-light status
• Reports: generated documents
• Impact: metrics (SDGs, beneficiaries, outcomes)
• Engagement: comments (optional), report acknowledgment (optional), document submission (optional)

​

Stakeholder Engagement

1. Commenting — Stakeholder posts comment on report/project; org staff can reply; threaded via parentId
2. Report Acknowledgment — Stakeholder marks report as received/approved or requests revision; org staff can resolve revision requests
3. Document Submission — If enabled, stakeholder uploads feedback/compliance docs; org staff reviews and accepts/rejects

​

Analytics & Insights

• Session Analytics — usePortalAnalyticsState loads sessions via PortalAnalyticsService.listSessionsByOrganization(), derives model (daily visits, dwell time, engagement rows) via buildPortalAnalyticsModel(), generates AI summary via buildPortalAnalyticsSummary()
• Engagement Metrics — Per-stakeholder: total visits, pageviews, avg session duration, reports viewed/acknowledged, comments posted
• Portfolio View — PortalShowcaseModel aggregates M&E indicator summaries to compute metrics (beneficiaries, outcomes), SDGs (from projects + indicators), geographies

​

Content & AI Coaching

• Content Blocks — Portal content organized as reusable blocks (impact_story, achievements, testimonial, media_gallery) with publish status
• AI Coach — computePortalCoachModel() evaluates portal completeness across 5 categories (profile, showcase, stakeholders, content, publishing), scores each, recommends improvements with effort/impact ratings
• Profile Draft — buildPortalProfileDraft() generates hero headline, mission tagline, impact tagline, org story from AI; org reviews and accepts edits

​

Service Contract

• usePortalAnalyticsState — Manages analytics state: loads sessions, derives model, generates AI summary, tracks date range (30/90 days)

• buildPortalAnalyticsModel(sessions, tokens, days) — Aggregates engagement metrics from sessions
• buildPortalAnalyticsSummary(analytics, days) — Generates human-readable AI summary
• buildPortalShowcaseModel(org, projects, indicators, summaries, reports) — Computes impact metrics, SDGs, geographies, outcomes
• buildPortalProfileDraft(org, projects, indicators) — AI-generated org profile copy
• computePortalCoachModel(showcase, tokens, contentBlocks) — Scores portal completeness and recommends improvements

​

Events

​

Emitted

​

Consumed

​

Dependencies

• projects — Portal showcases projects; reads Project data (milestones, SDGs, team, budget)
• impact (M&E) — Portal aggregates M&E indicator data for showcase metrics; reads MEIndicator, MEIndicatorSummary
• grantors — Portal reads grantor/foundation data for context (if integrated)
• reports — Portal displays GeneratedReport documents for stakeholder viewing/acknowledgment

• BaseService — PortalAnalyticsService extends BaseService for Firestore operations
• eventBus — Portal analytics emits engagement events
• Firebase Firestore, Storage, Functions — Backend data storage, document uploads, serverless token validation

• Standard PageLayout, PageHeader, PageTabs patterns
• shadcn Card, Button, Badge, StatusBadge
• Lucide icons
• React Query (server state), Context (app state)

​

File Structure

src/features/impact-portal/
├── components/
│   ├── pages/
│   │   ├── ImpactPortalPage.tsx          # Main portal hub (Overview, Profile, Showcase, Notifications, Settings tabs)
│   │   ├── PortalCMSPage.tsx             # Content management (Content Studio, AI Coach, Publishing tabs)
│   │   └── PortalStakeholdersPage.tsx    # Stakeholder management (Stakeholders, Analytics tabs)
│   └── tabs/
│       ├── PortalOverviewTab.tsx         # Dashboard with activity feed and stat cards
│       ├── PortalProfileTab.tsx          # Edit org profile visible to stakeholders
│       ├── PortalShowcaseTab.tsx         # Impact showcase (metrics, outcomes, SDGs, geographies)
│       ├── PortalNotificationsTab.tsx    # Portal notification preferences
│       ├── PortalSettingsTab.tsx         # Portal configuration (domain, branding, visibility defaults)
│       ├── PortalContentStudioTab.tsx    # Create/edit content blocks (stories, testimonials, gallery)
│       ├── PortalAICoachTab.tsx          # AI-powered content recommendations
│       ├── PortalPublishingTab.tsx       # Publish and schedule content
│       ├── PortalStakeholdersTab.tsx     # Manage stakeholder tokens and access
│       └── PortalAnalyticsTab.tsx        # Detailed engagement analytics
├── hooks/
│   └── usePortalAnalyticsState.ts        # State management for analytics (sessions, model, summary)
├── lib/
│   ├── portalInsightTypes.ts             # TypeScript interfaces for analytics, showcase, coach models
│   ├── portalInsightUtils.ts             # Helper functions (formatting, aggregation)
│   ├── portalInsights.ts                 # Barrel export of model builders and type definitions
│   ├── portalAnalyticsModel.ts           # Derives PortalAnalyticsModel from sessions/tokens
│   ├── portalShowcaseModel.ts            # Builds PortalShowcaseModel from org/projects/indicators
│   ├── portalCoachModel.ts               # Scores and recommends portal improvements
│   ├── portalContentBlocks.ts            # Content block normalization and defaults
│   └── portalInsights.test.ts            # Model builder tests
├── index.ts                              # Public API exports (page components, hooks)
└── public.ts                             # Version + public exports

• src/features/projects/services/PortalAnalyticsService.ts — Queries PortalSession Firestore collection
• src/features/portal/contracts.ts — Centralized portal type definitions

• docs/product/features/impact-portal.md — Product-level feature overview
• docs/product/features/portal-system.md — Legacy portal architecture
• docs/engineering/api-reference/public-api/impact-portal.md — Public API reference