#Tech4Good   #OpenSource   #Solidarity

Social.Income.explained.mp4

Social Income is a radically simple solution in the fight against poverty. The global open-source initiative converts donations into an unconditional basic income, which is sent directly to the mobile phones of people living in poverty in the Global South.

SDG 1    SDG 10

Social Income – Monorepo Overview

Welcome to the Social Income monorepo.

---

📁 Repository Structure

/
├─ recipients_app/        → Mobile app for recipients
├─ recipients_selection/  → Verifiable draw process for selecting recipients
├─ seed/                  → Firebase emulator seed data
├─ ui/                    → Legacy Storybook component library
└─ website/               → Next.js (public site, portal, dashboard, infra, backend services)

---

📱 recipients_app

Mobile app where recipients can:

• Log in
• View payment history
• Complete surveys

See /recipients_app/README.md for platform‑specific setup.

---

🎲 recipients_selection

Implements the cryptographically verifiable and bias‑proof recipient draw:

• Raw recipient lists → salted → hashed → committed to /lists
• GitHub Action triggers draw.sh
• Draw randomness comes from drand → https://drand.love
• Results written to /draws
• Draws are reproducible using dchoose → https://github.com/drand/dchoose
• Full transparency explanation: https://socialincome.org/transparency/recipient-selection

---

🌱 seed

Contains seed data for the local development environment:

Firebase authentication seeds

Automatically imported when running:

mise dev

PostgreSQL database seeds

Local development DB can be filled with sample data via:

npm run db:seed

This populates the local PostgreSQL instance with representative example data.

---

🎨 ui (Storybook Components)

Legacy UI component package using:

• Tailwind CSS
• shadcn/ui

📘 Storybook preview: http://design.socialincome.org

The long‑term plan is to phase this out and maintain all components inside /website.

---

🌐 website (Main Next.js Application)

A Next.js project containing:

1. Public Website

• Currently partly hardcoded
• Migration underway → Storyblok CMS
• Journal already uses Storyblok Docs: https://www.storyblok.com/docs

---

2. Portal

Internal operations tool:

• Program management
• Payments & transfers
• Recipients & contributor tools
• Admin functions

---

3. Dashboard

Contributor self‑service area:

• View payments
• Manage subscriptions
• Update personal details

---

4. Partner Space

Local Partner self‑service area:

• View own recipients / candidates
• Update personal details

---

5. Authentication Roles & Test Accounts (Local Dev)

We use hardcoded deterministic seed data for local development and tests. All local login users come from Firebase Auth emulator seed data.

To see which users can log in locally, open: http://localhost:4000/auth

---

6. Mobile API Used by Recipients App

The recipients_app communicates with Next.js API routes via OpenAPI‑documented endpoints:

📘 API docs:
https://socialincome.org/v1/api-docs

---

7. Infrastructure (/infra)

Infrastructure-as-code via Terraform:

• GCP Cloud Run
• GCP Cloud SQL (PostgreSQL)
• Networks, service accounts, secrets, etc.

Docs: https://developer.hashicorp.com/terraform/docs

---

8. Backend Services (website/lib/)

Shared backend modules using:

• Prisma ORM → https://www.prisma.io
• PostgreSQL
• Firebase Storage
• Misc. utilities and API integrations

---

9. E2E Testing

We use Playwright for end‑to‑end testing of the website.

Key principles

• Tests run against the real app in CI
• Visual regression screenshots are automatically updated in the pipeline and committed into the PR
• External Storyblok requests are mocked using a mockserver

Mock recording system

We use a record/replay mechanism for deterministic tests.

Record mode

1. Set STORYBLOK_MOCK_MODE in .env.development to 'record'
2. Restart dev server mise dev
3. run tests: STORYBLOK_MOCK_MODE=record npm run test:e2e

This:

• starts the mockserver as proxy
• records all outgoing Storyblok API requests
• stores them as JSON fixtures inside the repo

These recordings should be committed.

Replay mode (CI default)

In CI the environment runs in replay mode:

• mockserver serves recorded responses
• no external API calls are made
• tests are fully deterministic and fast

---

🛠 Local Development Setup (Simple & Minimal)

We use:

• mise-en-place → https://mise.jdx.dev
• Docker (for PostgreSQL)
• Firebase Emulators
• Node.js + npm
• Terraform (infra work only)

---

1. Install mise

brew install mise

---

2. Install all required tool versions

mise install

---

3. Prepare environment variables

Inside /website, copy the sample file:

cp website/.env.local.sample website/.env.local

Edit values as necessary.

---

4. Start the complete local dev environment

mise dev

This starts:

• Local PostgreSQL via Docker Compose
• Firebase Emulators (Auth + Firestore + Storage)
• Next.js website (public site, portal, dashboard)

---

🧪 pg_dump / pg_restore

Useful commands for copying local DB → staging (or vice versa).

Dump your local database:

pg_dump -Fc --no-owner "postgresql://social-income:social-income@localhost:5432/social-income" > local.dump

Restore into staging:

pg_restore   --clean --if-exists   --no-owner   -d "postgresql://staging-website_google_sql_user:xxxx@yyyy:5432/staging-website-google-sql-database"   local.dump

---

🧩 Storyblok Development

1. Read the Storyblok docs → https://www.storyblok.com/docs
2. Set env vars in website/.env.local:
   • STORYBLOK_PREVIEW_TOKEN
   • STORYBLOK_PREVIEW_SECRET
   • STORYBLOK_WEBHOOK_SECRET (must match the Secret key on the Storyblok webhook; used to verify the webhook-signature header)
3. Optional: start local dev with HTTPS for live preview

mise run dev-ssl

Storyblok webhook (ISR revalidation)

To refresh cached pages when editors publish in Storyblok, add a webhook in the space (Settings → Webhooks):

• URL: https://<your-production-domain>/api/revalidate
• Secret key: set a value and put the same value in STORYBLOK_WEBHOOK_SECRET (Storyblok signs the raw body; we verify the webhook-signature header per Storyblok’s webhook signature docs)
• Method: POST
• Triggers: Story published, Story unpublished, Story deleted, Story moved

The handler calls Next.js revalidatePath for the affected routes (see website/src/lib/services/storyblok/revalidation.ts) and invalidates /sitemap.xml.

---

Storyblok Type Generation

We use the Storyblok CLI to generate TypeScript types from the CMS schema.

If you have made changes to the Storyblok schema, you can regenerate the types:

1. Set these env vars in website/.env.local:
   • STORYBLOK_PERSONAL_ACCESS_TOKEN
   • STORYBLOK_SPACE_ID
2. Run:

npm run storyblok:generate

This command:

1. Logs into Storyblok using your personal access token
2. Pulls component schemas from the space
3. Generates TypeScript types to src/generated/storyblok/types/

Usage in components:

import type { Page } from '@storyblok/types/{SPACE_ID}/storyblok-components';

---

🙋 Troubleshooting

Translations not updating?

rm -rf website/.next
mise dev

Firebase seed not updating?

npm run firebase:export

---

Financial Contributions

Donate 1 Percent of Your Income

Become a contributor of Social Income (tax-deductible in Switzerland).

Sponsor Dev Community

Become a sponsor and help ensure the development of open source software for more equality and less poverty. Donations through the GitHub Sponsor program are used for building a strong developer community.

Social Income (NGO)

Non-Profit Organization

Social Income is a non-profit association (CHE-289.611.695) based in Zurich, Switzerland. Connect with us X, Insta, LinkedIn, Facebook or by email.

Radical Transparency

We believe that transparency builds trust and trust builds solidarity. This is why we disclose our finances to the public.

Open Source Community

Open Source isn’t an exclusive club. It’s made by people just like you. These individuals, amongst many others, have made significant contributions to Social Income's success:

Software and IP Contributions

We receive in-kind donations from Google Nonprofit, GitHub, Codemagic, Linktree, Twilio, Algolia, JetBrains, Storyblok, 1Password, Mux, Sentry and Lineto. Our tools also leverage other open-source technologies, including solutions like FireCMS, Storybook and Tailwind CSS.

Licensing Information

This project is licensed under MIT, with the exception of the Unica77 font, which is exclusively licensed to Social Income.