ImpactLink is a production-grade AI platform designed to bridge the resource gap for under-served NGOs. By combining Stateful Agentic Workflows with Deterministic Financial Logic, it transforms a complex 40-hour grant application cycle into a streamlined, high-quality output in minutes.

This repository demonstrates enterprise-level engineering, featuring Reflection Patterns, Graph Orchestration, and Localized RAG architecture.

All latency numbers below are real measurements captured via the built-in instrumentation layer (utils/metrics.py). Timings were recorded on a local development environment using Llama 3.3 70B on Groq LPU inference.

Key Insight — Self-Correction Cost: The budget_narrative section triggered 2 automatic retries (scored 70 → 70 → 92), adding ~6.3s. Sections passing on the first attempt average 2.5 – 3.5s each. The reflection loop is the primary latency variable.

Instead of a linear prompt chain, ImpactLink utilizes a LangGraph StateGraph to manage complex, multi-turn proposal drafting. This architecture enables Map-Reduce parallelism for section generation and iterative Self-Correction (Reflection).

graph TD
    A[User Prompt] --> B[VocabExtractor: init_slots]
    B --> C[slot_filling: Conversational Q&A]
    C -->|All slots filled| D[slot_confirm: Human Gate]
    D --> E[node_draft_sections: Parallel Orchestrator]

    subgraph "SectionSubgraph (×10 parallel)"
        E --> F[SectionDraftAgent]
        F --> G[SectionScoringAgent]
        G -->|score ≥ 75| H[Section Approved]
        G -->|score < 75| I[SectionRewriteAgent]
        I --> G
    end

    H --> J[draft_review: Human Gate]
    J --> K[final_save]
    K --> L[complete: PDF Export]

• Challenge: LLMs are probabilistic, but financial budgets require deterministic exactness.
• Solution: Built a Deterministic-Agentic Hybrid. The LLM only parses intent (e.g., "Add a Project Manager"). That intent is fed into a rigid Python engine that enforces real-world constraints like local minimum wage laws and proportional indirect cost caps. Math is always perfect; AI is only the interface.

• Challenge: Most RAG implementations fail on long documents, and NGOs need grants that match hard metadata (e.g., Region: "Kenya"), not just semantic similarity.
• Solution:
  • Tiered Retrieval: Uses SemanticChunker (percentile-based) to split documents contextually.
  • Unified Querying: Migrated to Supabase (PostgreSQL + pgvector). This enables SQL queries that filter by relational metadata first, then rank by semantic similarity in a single database round-trip.
  • Idempotent Lifecycle: Handled via PostgreSQL ON CONFLICT, ensuring grant updates or re-indexing operations are atomic and never duplicate data.

• Challenge: Zero-shot drafts often lack the nuance required for high-stakes grant writing.
• Solution: Every generated proposal section is audited by an autonomous Scoring Agent using a strict 100-point rubric assessing Alignment, Vocabulary, Specificity, and Persuasion. Sections scoring below 75 are automatically sent back to the Rewrite Node with targeted feedback.

• Challenge: Public LLM APIs have strict rate limits, and serverless architectures face cold-start/clock-skew issues.
• Solution:
  • Provider-Agnostic Failover: Architected a custom provider factory (utils/llm.py) that handles rate-limiting and service disruptions with exponential backoff, ensuring drafting sessions are highly available.
  • Auth Resilience: Custom verify_token middleware handles 1.5s clock-skew retries for Firebase JWTs, critical for cross-region serverless deployments.

impactlink/
├── impactlink-backend/
│   ├── agents/          # Multi-agent specialized logic (Draft, Build, Scoring)
│   ├── api/             # FastAPI routers and SSE implementations
│   ├── services/        # Core logic: Vector store, Budget engine, NGO matching
│   ├── utils/           # Provider failover, Retry logic, and formatting
│   ├── Data/            # Seed data and localization indices
│   └── main.py          # Application entry point
└── impactlink-frontend/
    └── src/
        ├── pages/       # Dashboard and feature-specific views
        ├── hooks/       # AI state management (SSE, Drafting, Budgets)
        └── services/    # Centralized API logic (Axios)

Prerequisites

• Node.js (v18+)
• Python (3.11+)
• Docker (Optional)
• Environment Variables: GROQ_API_KEY, DATABASE_URL, FIREBASE_STORAGE_BUCKET

Local Development

# 1. Start the Backend
cd impactlink-backend
pip install -r requirements.txt
python main.py

# 2. Start the Frontend
cd ../impactlink-frontend
npm install
npm run start

Automated Testing (E2E Pipeline) You can run the full integration test pipeline to verify the AI stack (PDF Parse -> RAG Search -> Scoring -> Budget Logic):

cd impactlink-backend
python testpipeline.py

[x] Production Migration: Transition from flat JSON/ChromaDB to Supabase + Cloud Run.
[x] API Resilience: Implemented robust failover handling for inference rate limits.
[ ] Database-Level RAG Execution: Migrating application-layer Python vector filtering into a unified Supabase RPC function to process hard metadata constraints (e.g., Region) and pgvector similarity in a single atomic database query.
[ ] Enterprise Data Security: Implementing Supabase Row Level Security (RLS) for cryptographic tenant isolation, alongside a custom PII Redaction Middleware to scrub sensitive NGO data before payloads reach the LLM inference layer.
[ ] Graph-Based RAG: Transitioning to Knowledge Graphs to map funder-to-NGO relationships visually.
[ ] Financial API Integrations: Direct integration with NGO-specific accounting software for real-time spend tracking.