MyHearty

A one-stop charity website to fundraise, donate, volunteer and apply for aids

Website · Dashboard

---

About The Project

MyHearty is a one-stop, centralized charity website for people to fundraise, donate, volunteer and apply for aids. The motivation behind this project stems from the idea of integrating fundraising, donation, volunteering and aiding functions into a single platform with API access. This project aims to connect various parties that are involved in charity via a centralized platform and provide open charity data via an API.

Features

• Full-featured search UI (instant search, geosearch) for campaigns, volunteer events and aids
• Fundraising and donations
• Volunteering
• Receiving aids
• Managing organization/charity members
• API access

MyHearty Website Demo

MyHearty Dashboard Demo

Built With

• Next.js
• React
• Tailwind CSS
• Mantine
• React InstantSearch
• Typesense
• Stripe Checkout
• SWR

Development

To get a local copy up and running, read the following subsections.

Requirements

You need the following requirements to be able to run MyHearty locally.

• Node.js (Version: >=16.x)
• Yarn (recommended)

Note
If you want to enable any of the available integrations, you may want to obtain additional credentials and populate environment variables for the corresponding integration. Refer to the integrations section for more details.

Project Structure

This project is a Next.js monorepo that consists of 2 apps: MyHearty website and MyHearty dashboard. The detailed directory structure is shown below.

.
├── apps
│   ├── dashboard (MyHearty dashboard)
│   └── web       (MyHearty website)
├── packages
│   ├── hooks     (shared utility and query hooks)
│   ├── lib       (API client functions, shared constants and types)
│   ├── ui        (shared UI components)
│   └── utils     (shared utility functions)
└── static        (common assets: favicons, images, locales)

Note
Assets inside the static/ directory will be symlinked to public/ directories of both apps. Hence, you only need to add assets to the static/ directory once and they will be available for both apps. During deployment, the symlinks will be removed and the assets will be copied from the static/ directory to each app's public/ directory. Refer to apps/**/package.json for more detail.

Getting Started

1. Clone the repo.

   git clone https://github.com/myhearty-org/myhearty.git

2. Install dependencies with Yarn.

   yarn install

3. To run MyHearty website:
   • Create a .env.local file inside the apps/web/ directory by copying the environment variables from the .env.example file. For more information on populating environment variables, refer to the integrations section.
   • Run

     cd apps/web
     yarn dev

     Go to http://localhost:3001 to view the website.
4. To run MyHearty dashboard:
   • Create a .env.local file inside the apps/dashboard/ directory by copying the environment variables from the .env.example file. For more information on populating environment variables, refer to the integrations section.
   • Run

     cd apps/dashboard
     yarn dev

     Go to http://localhost:3002 to view the dashboard.

Integrations

MyHearty Backend API

A running local MyHearty API server is required to serve the content for both frontend website and dashboard. To integrate with the frontend apps:

1. Refer to the myhearty-api repository to learn how to set up a local API server. The API server should be running on port 3000.
2. In the apps/web/.env.local and apps/dashboard/.env.local files, assign http://localhost:3000 to the NEXT_PUBLIC_API_URL variables.

Typesense

Typesense is an open-source, typo-tolerant search engine that is optimized for instant search. It is an easier-to-use alternative for commercial search API like Algolia, which has high pricing, or open-source search engine like Elasticsearch, which can be complicated to tune. To enable the website's instant search feature:

1. Ensure that a Typesense instance has been running on your local API server. Refer to MyHearty Backend API section for more detail.
2. Create a search-only API key using your admin key with the following curl command:

   curl 'http://localhost:8108/keys' \
    -X POST \
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"description": "Search-only API key.", "actions": ["documents:search"], "collections": ["organizations", "fundraising_campaigns", "volunteer_events", "charitable_aids"]}'

   Refer to Typesense: Create an API key for more detail.
3. In the apps/web/.env.local file, populate the Typsense's related environment variables:

   NEXT_PUBLIC_TYPESENSE_HOST='localhost' # if the Typesense instance is running on your local API server
   NEXT_PUBLIC_TYPESENSE_PORT=8108 # default port on which Typesense is running
   NEXT_PUBLIC_TYPESENSE_PROTOCOL='http' # can be http or https
   NEXT_PUBLIC_TYPESENSE_API_KEY='' # your search-only API key

   You can replace the defaults with other values for your own changes.

Geoapify

Geoapify provides the Address Autocomplete API that is required for the website's geosearch feature. To enable the website's geosearch feature:

1. Go to Geoapify MyProjects to create an account and generate an API key for your project.
2. In the apps/web/.env.local file, populate the NEXT_PUBLIC_GEOAPIFY_API_KEY variable with your Geoapify API key.

Documentation

The full documentation for the MyHearty project can be found in the myhearty-documentation repository. The documentation repository contains technical documents and architecture information related to the implementation of this project.

Contributing

If you want to contribute, please fork the repo and create a pull request by following the steps below:

1. Fork the repo.
2. Create your feature branch (git checkout -b your-feature-branch).
3. Commit your changes and push to the branch (git push origin your-feature-branch).
4. Open a pull request.

Your changes will be reviewed and merged if appropriate.

References

• GitHub: Next.js Monorepo Template
• GitHub: Instant E-Commerce Store Experience, powered by Typesense + Next.js
• Geoapify: Get started with Maps API
• Stripe Checkout: Quickstart
• SWR Docs: Getting Started