Data-driven social capital allocation. From emotional giving to quantifiable ROI.
Features • Quick Start • Architecture • Schema • Algorithms • Deployment
Altruist is an impact intelligence platform that standardises charitable impact with the rigor of a credit rating agency. Donors don't just "give" — they invest based on quantifiable social return on investment (SROI).
The platform scores charities across six dimensions, integrates ONS deprivation data to weight impact by need, and converts human outcomes into financial yield statements.
- Real-time overview of tracked charities with key metrics
- SROI bar charts and Impact/£ vs Transparency scatter plots
- Top-rated charities table with sortable columns
- Natural language search: "I want to fund reforestation in poverty-stricken areas of the UK Midlands"
- Sector-based filtering (Health, Education, Poverty Relief, Environment, Community)
- Example query suggestions for quick exploration
- Production architecture: Vector search via Vertex AI embeddings or Pinecone
Six-axis Unified Impact Score (0-100):
| Dimension | Weight | Description |
|---|---|---|
| SDG Alignment | 15% | Mapping to UN Sustainable Development Goals |
| Impact per £ | 25% | Efficiency of charitable spend |
| Social Impact | 20% | Qualitative-to-quantitative social good |
| ONS Poverty Linkage | 15% | Weighted by Index of Multiple Deprivation |
| Transparency | 10% | Data upload frequency and reporting quality |
| SROI | 15% | Social Return on Investment ratio |
- Social Value Bank with 10 outcome categories and fiscal values (sourced from MoJ, NHS, DWP)
- SROI calculator: input investment amount, see social value created
- Fundable Insights: human outcomes expressed as taxpayer savings
- "Prevention of one person entering prison saves £45,000/year"
- Converts raw metrics into human-readable stories
- "Your £50 didn't just fund GreenHeart Midlands — it directly enabled 10.4 trees in Birmingham."
- Configurable donation amounts with real-time narrative generation
- Production: Uses Firebase GenKit / Vertex AI for LLM-powered narratives
- Dynamic Firestore-backed survey builder
- 5 question types: text, number, scale, multiple choice, boolean
- Survey responses automatically feed into the Rating Engine
- Real-time response counts and status tracking
- Side-by-side comparison with sortable multi-column table
- Interactive scatter charts (Impact/£ vs Transparency)
- Radar charts for multi-dimensional score visualisation
- Filter charities in/out of comparison
- Built-in docs page covering Firestore schema, security rules, algorithms
- Vector search architecture strategy
- ONS API integration guide
- Deployment instructions
# Clone the repository
git clone https://github.com/YOUR_USERNAME/altruist.git
cd altruist
# Install dependencies
npm install
# Start the development server
npm run devThe app will be available at http://localhost:5173/altruist/
For Firebase integration, create a .env.local file:
VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-idThe app runs with demo mock data by default — Firebase is not required for local development.
npm run buildOutput is generated in the dist/ directory.
altruist/
├── .github/workflows/ # GitHub Actions CI/CD
│ └── deploy.yml # Auto-deploy to GitHub Pages
├── src/
│ ├── components/
│ │ ├── charts/ # Recharts visualisations
│ │ │ ├── ImpactRadar.tsx
│ │ │ ├── ImpactScatterChart.tsx
│ │ │ └── SROIChart.tsx
│ │ ├── dashboard/ # Dashboard-specific components
│ │ │ └── ImpactNarrative.tsx
│ │ ├── layout/ # App shell & navigation
│ │ │ ├── AppLayout.tsx
│ │ │ └── Sidebar.tsx
│ │ └── shared/ # Reusable components
│ │ ├── ScoreRing.tsx
│ │ └── SDGBadge.tsx
│ ├── data/
│ │ └── mock-data.ts # Realistic UK charity mock data
│ ├── lib/
│ │ ├── firebase.ts # Firebase configuration
│ │ └── rating-engine.ts # SROI & scoring algorithms
│ ├── pages/
│ │ ├── DashboardPage.tsx
│ │ ├── DiscoverPage.tsx
│ │ ├── ComparePage.tsx
│ │ ├── SurveysPage.tsx
│ │ ├── InsightsPage.tsx
│ │ └── DocsPage.tsx
│ ├── types/
│ │ └── index.ts # TypeScript domain types
│ ├── App.tsx # Router configuration
│ ├── index.css # Liquid Glass design system
│ └── main.tsx # Entry point
├── firestore.rules # Firebase security rules
├── FIREBASE_SETUP.md # Firebase configuration guide
└── README.md # This file
| Layer | Technology |
|---|---|
| Framework | React 18 + TypeScript |
| Build Tool | Vite 8 |
| Styling | Tailwind CSS v4 + Liquid Glass design tokens |
| Charts | Recharts |
| Animation | Framer Motion |
| Icons | Lucide React |
| Backend | Firebase (Auth, Firestore, Cloud Functions) |
| Search | Vector Search (Vertex AI / Pinecone) |
| AI/NLG | Firebase GenKit |
| Deployment | GitHub Pages |
| Collection | Purpose | Access |
|---|---|---|
charities |
Core charity profiles with impact metrics | Public read, owner write |
ons_regional_data |
ONS Index of Multiple Deprivation data | Public read, admin write |
impact_valuations |
SROI calculations and outcome valuations | Auth read, owner write |
surveys |
Dynamic survey definitions | Public read, owner write |
surveys/{id}/responses |
Beneficiary survey responses | Owner read, public create |
un_sdg_mappings |
SDG alignment evidence | Public read, admin write |
users |
Donor profiles and investment history | Self-access only |
See firestore.rules for the complete security rules implementation.
SROI = Total Social Value Created / Cost of InterventionThe Social Value Bank maps outcomes to fiscal values:
| Outcome | Annual Value | Source |
|---|---|---|
| Prison prevention | £45,000 | Ministry of Justice |
| Homelessness prevention | £26,000 | Crisis/DCLG |
| Youth gang diversion | £38,000 | Home Office |
| Employment transition | £12,500 | DWP |
| Mental health intervention | £5,400 | NHS |
| A&E prevention | £2,800 | NHS England |
Weighted composite of six dimensions:
Overall = SDG(15%) + Impact/£(25%) + Social(20%) + ONS(15%) + Transparency(10%) + SROI(15%)
Charities working in IMD Decile 1 (most deprived) areas receive the highest scores (~95/100). Charities in Decile 10 (least deprived) receive lowest scores (~15/100).
- Push your code to GitHub
- Go to Settings → Pages → Source → GitHub Actions
- The included workflow (
.github/workflows/deploy.yml) will auto-deploy on push tomain
npm run build
# Upload the contents of dist/ to any static hosting providerfirebase init hosting
# Set public directory to: dist
# Configure as single-page app: Yes
npm run build
firebase deploy --only hostingSee FIREBASE_SETUP.md for detailed instructions on:
- Creating a Firebase project
- Enabling Authentication and Firestore
- Deploying security rules
- Setting up Cloud Functions for ONS data sync
- Configuring Vector Search
- Setting up GenKit for AI narratives
The app uses a Liquid Glass design language:
- Glass morphism panels with backdrop blur and translucent borders
- Ambient background with animated gradient orbs
- Dark mode first with the Inter typeface
- Score rings with colour-coded thresholds (green ≥80, indigo ≥60, amber ≥40, rose <40)
- Micro-animations via Framer Motion for all transitions
- Responsive layout with collapsible sidebar for mobile
Instead of tracking donations alone, the database tracks Units of Change — measurable outcomes tied to fiscal value.
The platform fetches Index of Multiple Deprivation (IMD) data from the Office for National Statistics. This enables impact weighting: "Charity A is more impactful because they work in a region the ONS identifies as Decile 1 (most deprived)."
The Text-to-Filter system (powered by vector embeddings in production) removes traditional category friction, allowing donors to search for hyper-specific niches: "Mental health for elderly veterans in Wales".
MIT
Built with ❤️ for data-driven philanthropy