Project: Creative Apps - Runny

Track

Creative Apps (GitHub Copilot)

Project Name

Runny

GitHub Username

@mng-holacons

Repository URL

https://github.com/mng-holacons/runny.git

Project Description

Runny is a collaborative fitness-to-donation platform that turns every verified kilometer into tangible aid for NGOs. Runners log sessions through the PWA, earn “packs” (food parcels, school kits, medical routes), and watch their impact unfold in real time. The companion API handles authentication, quest logic, donation workflows, and never exposes secrets thanks to a local-first architecture.

The project tackles a common hurdle for cause-driven fitness challenges: trust and engagement. Traditional pledge systems rely on screenshots or manual reporting, which is slow and easy to game. Runny instead combines GPS validation, streak mechanics, and an agent-guided experience to keep communities motivated while providing NGOs with auditable, ready-to-claim resources.

Key features include:

Deterministic quests and streaks powered by a shared TypeScript library, so every participant sees meaningful goals aligned with their history.
Catalog-to-donation flow where users browse NGO packs, build a basket, and trigger delivery records that update the Impact Feed.
Agent guardrails that narrate progress, suggest solidarity “raids,” and match runners with causes—setting the stage for future LLM-powered coaching.
Offline-safe API built with Express, better-sqlite3, Zod, and secure secret loading, ensuring the project runs anywhere without leaking credentials.
Extensible integrations for Strava and Google Fit, keeping the door open for automated activity imports.
In short, Runny blends playful quests with transparent philanthropy, giving teams, wellness programs, and sports
communities a turn-key way to convert movement into measurable social good.

Demo Video or Screenshots

Demo video: https://youtu.be/hV1Z_9IFcz0
Live video: https://youtu.be/hV1Z_9IFcz0

Primary Programming Language

TypeScript/JavaScript

Key Technologies Used

Vite + React 18 + TypeScript for the progressive web app shell and routing.
Zustand for lightweight client state management (quests, sessions, auth context).
Supabase JavaScript client for guest/session scaffolding.
Express + better-sqlite3 + Zod + bcrypt + JWT on the API layer for auth, validation, and persistence.
Nodemailer/SendGrid adapters for email flows.
Shared TypeScript workspace (@runny/shared) powering deterministic quest logic.
Strava & Google Fit integrations (OAuth scaffolding + token storage).
GitHub Copilot + MCP tooling to accelerate UI scaffolding, API validation, and documentation.

Submission Type

Individual

Team Members

• teammate1 @mng-holacons

Submission Requirements

• My project meets the track-specific challenge requirements
• My repository includes a comprehensive README.md with setup instructions
• My code does not contain hardcoded API keys or secrets
• I have included demo materials (video or screenshots)
• My project is my own work with proper attribution for any third-party code
• I agree to the Code of Conduct
• I have read and agree to the Disclaimer
• My submission does NOT contain any confidential, proprietary, or sensitive information
• I confirm I have the rights to submit this content and grant the necessary licenses

Quick Setup Summary

Install dependencies: npm install.
Copy env templates: [.env.example] (optional secrets JSON if needed).
Start everything: npm run dev (web on [http://localhost:5173] API on [http://localhost:8787]packs, and /rewards to simulate donations.

Technical Highlights

Deterministic quest engine shared between API and PWA via the @runny/shared workspace for consistent goals.
Local-first Express API (better-sqlite3, Zod, JWT, secure secret loader) that runs entirely offline yet mirrors production patterns.
Catalog → basket → donation workflow with impact feed updates, giving NGOs traceable evidence.
Agent-ready UI architecture: quests, sessions, catalog, and rewards screens expose hooks the assistant can orchestrate.
Built-in Strava/Google Fit scaffolding plus on-demand Supabase guest auth, keeping future integrations straightforward.
Strong security posture: gitignored secrets, optional JSON vaults, and README guidance to prevent leaks.

Challenges & Learnings

Balancing immersion with reliability: building the GPS/session validation flow while keeping everything offline-safe forced us to rethink data models and create deterministic quests so demos never “break.”

Secret management in a public repo: designing the secrets.ts loader plus JSON vault workflow taught us how to keep local demos ergonomic without ever leaking credentials.

Catalog-to-donation storytelling: tying together sessions, packs, NGO deliveries, and the impact feed exposed edge cases (partial donations, manual sessions) and pushed us to document a full redemption flow.

Agent readiness: scoping an AI-guided experience revealed the importance of guardrails—prompt-friendly APIs, consistent copy, and clear user flows—so future LLM integrations can slot in safely.

Contact Information

mngoicoechea@gmail.com

Country/Region

Spain

This issue is a project submission and does not identify a contribution task, target file, failing test, or acceptance criteria. Read README.md and run npm install followed by npm run dev to understand the application, but no defined completion condition is provided.