Compass/README.md

Compass

This repository provides the source code for Compass, a web application for people to form deep 1-on-1 relationships in a fully transparent and efficient way. And it just got released!

We can’t do this alone. Whatever your skills—coding, design, writing, moderation, marketing, or even small donations—you can make a real difference. Contribute in any way you can and help our community thrive!

Features

• Extremely detailed profiles for deep connections
• Radically transparent: user base fully searchable
• Free, ad-free, not for profit (supported by donations)
• Created, hosted, maintained, and moderated by volunteers
• Open source
• Democratically governed

You can find a lot of interesting info in the About page and the FAQ as well. A detailed description of the early vision is also available in this blog post (you can disregard the parts about rationality, as Compass shifted to a more general audience).

To Do

No contribution is too small—whether it’s changing a color, resizing a button, tweaking a font, or improving wording. Bigger contributions like adding new profile fields, building modules, or improving onboarding are equally welcome. The goal is to make the platform better step by step, and every improvement counts. If you see something that could be clearer, smoother, or more engaging, please jump in!

Here are some examples of things that would be very useful. If you want to help but don’t know where to start, just ask us on Discord.

• Authentication (user/password and Google Sign In)
• Set up PostgreSQL in Production with supabase
• Set up web hosting (vercel)
• Set up backend hosting (google cloud)
• Ask for detailed info upon registration (location, desired type of connection, prompt answers, gender, etc.)
• Set up page listing all the profiles
• Search through most profile variables
• Set up chat / direct messaging
• Set up domain name (compassmeet.com)
• Add mobile app (React Native on Android and iOS)
• Add better onboarding (tooltips, modals, etc.)
• Add modules to learn more about each other (personality test, conflict style, love languages, etc.)
• Add modules to improve interpersonal skills (active listening, nonviolent communication, etc.)
• Add calendar integration and scheduling
• Add events (group calls, in-person meetups, etc.)

Secondary To Do

Everything is open to anyone for collaboration, but the following ones are particularly easy to do for first-time contributors.

• Clean up learn more page
• Add dark theme
• Add profile features (intellectual interests, cause areas, personality type, conflict style, etc.)
• Add filters to search through remaining profile features (politics, religion, education level, etc.)
• Cover with tests (very important, just the test template and framework are ready)
• Make the app more user-friendly and appealing (UI/UX)
• Clean up terms and conditions (convert to Markdown)
• Clean up privacy notice (convert to Markdown)
• Add other authentication methods (GitHub, Facebook, Apple, phone, etc.)
• Add email verification
• Add password reset
• Add automated welcome email
• Security audit and penetration testing
• Make deploy-api.sh run automatically on push to main branch
• Create settings page (change email, password, delete account, etc.)
• Improve financials page (donor / acknowledgments, etc.)
• Improve loading sign (e.g., animation of a compass moving around)
• Show compatibility score in profile page

Implementation

The web app is coded in Typescript using React as front-end. It includes:

• Supabase for the PostgreSQL database
• Google Cloud for hosting the backend API
• Firebase for authentication and media storage
• Vercel for hosting the front-end

Development

Below are the steps to contribute. If you have any trouble or questions, please don't hesitate to open an issue or contact us on Discord! We're responsive and happy to help.

Installation

Fork the repo on GitHub (button in top right). Then, clone your repo and navigating into it:

git clone https://github.com/<your-username>/Compass.git
cd Compass

Install opentofu, docker, and yarn. Try running this on Linux or macOS for a faster install:

./setup.sh

If it doesn't work, you can install them manually (google how to install opentofu, docker, and yarn for your OS).

Then, install the dependencies for this project:

yarn install

Environment Variables

We can't make the following information public, for security and privacy reasons:

• Database, otherwise anyone could access all the user data (including private messages)
• Firebase, otherwise anyone could remove users or modify the media files
• Email, analytics, and location services, otherwise anyone could use our paid plan

So, we separate all those services between production and local development, so that you can code freely without impacting the functioning of the platform. Contributors should use the default keys for local development. Production uses a separate environment with stricter rules and private keys that are not shared.

Most of the code will work out of the box. All you need to do is creating an .env file as a copy of .env.example:

cp .env.example .env

Then, most of you can skip the rest of the section. If you do need one of the few remaining services, you need to store your own secrets as environment variables. To do so, simply open .env and fill in the variables according to the instructions in the file.

Tests

Make sure the tests pass:

yarn test tests/jest/

TODO: make yarn test run all the tests, not just the ones in tests/jest/.

Running the Development Server

Start the development server:

yarn dev

Once the server is running, visit http://localhost:3000 to start using the app. You can sign up and visit the profiles; you should see a few synthetic profiles.

Contributing

Now you can start contributing by making changes and submitting pull requests!

See development.md for additional instructions, such as adding new profile features.

Submission

Add the original repo as upstream for syncing:

git remote add upstream https://github.com/CompassConnections/Compass.git

Create a new branch for your changes:

git checkout -b <branch-name>

Make changes, then stage and commit:

git add .
git commit -m "Describe your changes"

Push branch to your fork:

git push origin <branch-name>

Finally, open a Pull Request on GitHub from your fork/<branch-name> → CompassConnections/Compass main branch.

Acknowledgements

This project is built on top of manifold.love, an open-source dating platform licensed under the MIT License. We greatly appreciate their work and contributions to open-source, which have significantly aided in the development of some core features such as direct messaging, prompts, and email notifications. We invite the community to explore and contribute to other open-source projects like manifold.love as well, especially if you're interested in functionalities that deviate from Compass' ideals of deep, intentional connections.