Schemes Reimagined

Schemesv3 is a modern reimagining of Singapore's social support system search, built using Firebase Cloud Functions and Next.js. The system leverages Azure OpenAI's GPT models to provide intelligent scheme recommendations and natural language interactions.

The core functionality is powered by a sophisticated search system that combines:

• Natural Language Search: Users can describe their situation in everyday language and receive relevant scheme recommendations
• Intelligent Chat Interface: Contextual conversations powered by Azure OpenAI to help users understand scheme eligibility and application processes
• Hybrid Search: Combines BM25 keyword matching with Firestore Vector Search for accurate scheme recommendations
• Serverless Architecture: Firebase Cloud Functions with Python runtime for scalable, maintainable backend operations
• Modern Web Interface: Responsive Next.js frontend with TypeScript for a seamless user experience

Prerequisites

Ensure you have the following installed:

• Node.js (v14 or later): Download Node.js
• npm (v6 or later): Comes with Node.js
• Python (v3.10): Download Python
• Firebase CLI: Install globally using npm install -g firebase-tools
• Docker: Install Docker
• Docker Compose: Included with Docker Desktop

Key branches

• main branch contains frontend and backend code - push to Schemes prod
• stg branch contains frontend and backend code - push to Schemes dev
• telegram_bot branch contains telegram bot code - push to GCP
• dataset-workflow branch contains files to update dataset and do webscraping adhoc
• v3-archive-021224 contains mix of old and prototype scheemes code for reference

Required Files Setup

1. Environment Variables Download the following required files from Google Drive (contact maintainers for access):

• .env → backend/functions/ (local development, uses local scheme-processor)
• .env.dev → backend/functions/ (dev deployment credentials for schemessg-v3-dev)
• .env.prod → backend/functions/ (prod deployment credentials for schemessg)

Note: These files contain sensitive configuration for Firebase, Azure OpenAI, and Slack services. Never commit them to version control.

Project Structure

Directory	Description
frontend/	Next.js application with TypeScript - see frontend/README.md
backend/	Firebase Functions + Cloud Run services - see backend/README.md
backend/functions/	Firebase Functions (Python 3.10) - API endpoints, triggers, Slack handlers
backend/scheme-processor/	Cloud Run service (Python 3.11) - web scraping, LLM extraction
backend/scripts/	Data management scripts - see backend/scripts/README.md
.github/workflows/	GitHub Actions for CI/CD deployment

URLs

Environment	Frontend	Backend
Production	https://schemes.sg	https://asia-southeast1-schemessg.cloudfunctions.net/
Development	https://schemessg-v3-dev.web.app/	https://asia-southeast1-schemessg-v3-dev.cloudfunctions.net/

Development Workflow

1. Frontend changes:

   • Branch from stg
   • Make changes
   • Test locally
   • Create PR to stg
   • When PR is merged, github action .github/workflows/firebase-hosting-staging.yml will be triggered to deploy to firebase hosting in Schemes dev
   • Then create PR to merge stg into main
   • When PR is merged, github action .github/workflows/firebase-hosting-production.yml will be triggered to deploy to firebase hosting in Schemes prod

2. Backend changes:

   • Test using Firebase emulator
   • When stg branch is pushed, the github action .github/workflows/deploy_functions_dev.yml will be triggered to deploy to Schemes dev
   • When main branch is pushed, the github action .github/workflows/deploy_functions_prod.yml will be triggered to deploy to Schemes prod

Note: For local frontend development to work, you must have the backend running via Docker. Please refer to backend/README.md for Docker setup and running instructions.

Link Check & Reindex

A scheduled batch job runs monthly (1st of each month at 9am) to:

1. Check all scheme links for dead links
2. Mark dead links as inactive in Firestore
3. Post summary to Slack
4. Reindex Firestore embeddings (excluding inactive schemes)

To trigger manually:

Option 1: Run locally

cd backend/functions
uv run python -c "from batch_jobs.run_link_check_and_reindex import run_link_check_and_reindex_core; run_link_check_and_reindex_core()"

Option 2: Trigger from Google Cloud Console

1. Go to Cloud Scheduler
2. Select the appropriate project (schemessg-v3-dev or schemessg)
3. Find the job: firebase-schedule-scheduled_link_check_and_reindex-asia-southeast1
4. Click "Run Now"

Contributing

We welcome contributions from the community! Here's how you can help:

1. Report Issues: Create issues for bugs or feature requests
2. Submit Pull Requests:
   • Fork the repository
   • Create a feature branch from stg
   • Make your changes
   • Submit a pull request to stg
   • Once approved and merged to stg, create another PR to merge into main

Please ensure your PR:

• Follows the existing code style
• Includes appropriate tests
• Updates documentation as needed
• Describes the changes made

Community

• Website: https://schemes.sg
• Issues: Please report bugs and feature requests through GitHub issues
• Discussions: Feel free to start discussions in the GitHub Discussions tab
• Contact: For other inquiries, reach out to the maintainers through GitHub

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with support from better.sg
• Powered by Azure OpenAI
• Special thanks to all contributors and maintainers