Before You Go

Help people make smarter decisions before leaving home — especially when time, money, and access to public services matter.

Overview

Before You Go is an open-source decision-support platform that helps people determine whether it is a good time to visit a public service office. Instead of promising real-time accuracy, the system provides probability-based guidance:

• Is the office likely open today?
• How risky is a visit right now?
• When is the best time window to go?
• What have recent visitors experienced?

The goal is simple: reduce wasted trips, time, and money.

Core Principles

1. Probability, Not Promises
   Outputs are confidence-based, not guarantees.

2. Low Friction
   No login required to browse. Contributions are optional and anonymous.

3. Signal Over Noise
   Structured inputs are preferred over free-form comments.

4. Country-Agnostic by Design
   Regions, districts, services, and rules are configurable per country.

5. Open & Transparent
   Logic, assumptions, and heuristics are documented and inspectable.

What It Does

For each public service office, the platform displays:

• Availability Status: Likely Open / Uncertain / Likely Closed
• Peak Risk Index: Low / Medium / High
• Recommended Time Window: Based on historical and contextual signals
• Contextual Warnings: Public holidays, declared closures, weather impact, end-of-month congestion
• Recent Experience Summary: Aggregated anonymous outcomes and common issue tags

What It Doesn't Do

• ❌ Not an official government platform
• ❌ Not a real-time monitoring system
• ❌ Not a complaint or whistleblowing channel
• ❌ Not a guarantee of service availability

This distinction is intentional and central to the project's sustainability.

Technology Stack

• Framework: Next.js 14+ (App Router)
• Language: TypeScript
• Database: Supabase (PostgreSQL)
• Styling: Tailwind CSS
• Maps: Leaflet or Google Maps
• Deployment: Vercel (recommended)

Getting Started

Prerequisites

• Node.js 18+ and npm/yarn/pnpm
• Supabase account (free tier works)
• Git

Installation

1. Clone the repository

   git clone https://github.com/blingyplus/before-you-go.git
   cd before-you-go

2. Install dependencies

   npm install
   # or
   yarn install
   # or
   pnpm install

3. Set up environment variables

   cp .env.example .env.local

   Fill in your Supabase credentials:

   NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
   

4. Set up the database

   # Run migrations
   npm run db:migrate
   
   # Seed initial data (Ghana)
   npm run db:seed

5. Run the development server

   npm run dev

   Open http://localhost:3000 in your browser.

Project Structure

before-you-go/
├── app/                    # Next.js App Router
│   ├── (public)/          # Public routes
│   └── api/               # API routes
├── components/             # React components
├── lib/                   # Core libraries
│   ├── db/               # Database client
│   ├── risk-scoring/     # Risk scoring engine
│   └── aggregation/      # Data aggregation
├── scripts/               # Utility scripts
│   ├── seed/             # Data seeding
│   └── migrations/       # Database migrations
└── docs/                  # Documentation
    ├── ARCHITECTURE.md
    ├── ER_DIAGRAM.md
    ├── FLOWS.md
    └── PHASES.md

Documentation

• Architecture: System architecture and design decisions
• ER Diagram: Database schema and relationships
• User Flows: User and system flow diagrams
• Development Phases: Roadmap and implementation phases
• Project Description: Detailed project overview

Development

Running Tests

npm run test

Database Migrations

# Create a new migration
npm run db:migrate:create

# Run migrations
npm run db:migrate

# Rollback last migration
npm run db:migrate:rollback

Seeding Data

# Seed Ghana data
npm run db:seed:ghana

# Seed specific region
npm run db:seed:region -- --region="Greater Accra"

Risk Score Calculation

# Calculate risk scores for all offices
npm run calculate-scores

# Calculate for specific office
npm run calculate-scores -- --office-id="uuid"

Contributing

We welcome contributions! Please see our Contributing Guide for details.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Standards

• Follow TypeScript best practices
• Write clear, self-documenting code
• Add tests for new features
• Update documentation as needed
• Follow the project's design principles (see description.md)

Adding a New Country

The platform is designed to be country-agnostic. To add a new country:

1. Define Geography

   • Add country record
   • Add regions, districts, and cities
   • Use the seeding scripts as templates

2. Define Service Types

   • Add service types specific to the country
   • Configure metadata as needed

3. Populate Offices

   • Add offices with location data
   • Set up schedules and holidays

4. Configure Risk Rules

   • Create risk rule version for the country
   • Define scoring logic in JSON format

No core code changes are required!

License

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

Acknowledgments

• Built for communities that need better access to public services
• Inspired by real problems faced by people in Ghana and beyond
• Designed to be transparent, open, and community-driven

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: your-email@example.com

Roadmap

See Development Phases for the detailed roadmap.

Current Phase: Foundation (Phase 0)

Upcoming:

• Core data model implementation
• Risk scoring engine
• User interface
• Feedback system

---

Remember: This is a probabilistic guidance tool, not a guarantee. Always verify with official sources when possible.