This repository contains the source code for Compass — a transparent platform for forming deep, authentic 1-on-1 connections with clarity and efficiency.
- 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).
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!
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!
The complete, official list of tasks is available here on ClickUp. If you are working on one task, just assign it to yourself and move its status to "in progress". If there is also a GitHub issue for that task, assign it to yourself as well.
To have edit access to the ClickUp workspace, you need an admin to manually give you permission (one time thing). To do so, use your preferred option:
- Ask or DM an admin on Discord
- Email [email protected]
- Raise an issue on GitHub
If you want to add tasks without creating an account, you can simply email
a.t.901810339879.u-276866260.b847aba1-2709-4f17-b4dc-565a6967c234@tasks.clickup.com
Put the task title in the email subject and the task description in the email content.
Here is a tailored selection 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)
- Cover with tests (unit, integration, e2e)
- Add Android mobile app
- Add iOS mobile app
- 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.)
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 fields (intellectual interests, cause areas, personality type, conflict style, timezone, etc.)
- Add filters to search through remaining profile fields (politics, religion, education level, etc.)
- 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.shrun automatically on push tomainbranch - 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
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
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.
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 CompassInstall yarn (if not already installed):
npm install --global yarnThen, install the dependencies for this project:
yarn installMake sure the tests pass:
yarn testIf they don't and you can't find out why, simply raise an issue! Sometimes it's something on our end that we overlooked.
Start the development server:
yarn devOnce 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.
Note: it's normal if page loading locally is much slower than the deployed version. It can take up to 10 seconds, it would be great to improve that though!
Now you can start contributing by making changes and submitting pull requests!
We recommend using a good code editor (VSCode, WebStorm, Cursor, etc.) with Typescript support and a good AI assistant (GitHub Copilot, etc.) to make your life easier. To debug, you can use the browser developer tools (F12), specifically:
- Components tab to see the React component tree and props (you need to install the React Developer Tools extension)
- Console tab for errors and logs
- Network tab to see the requests and responses
- Storage tab to see cookies and local storage
You can also add console.log() statements in the code.
If you are new to Typescript or the open-source space, you could start with small changes, such as tweaking some web components or improving wording in some pages. You can find those files in web/public/md/.
There is a lof of documentation in the docs folder and across the repo, namely:
- Next.js.md for core fundamentals about our web / page-rendering framework.
- knowledge.md for general information about the project structure.
- development.md for additional instructions, such as adding new profile fields.
- web for the web.
- backend/api for the backend API.
- android for the Android app.
There are a lot of useful scripts you can use in the scripts folder.
Add the original repo as upstream for syncing:
git remote add upstream https://github.com/CompassConnections/Compass.gitCreate 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.
Almost all the features will work out of the box, so you can skip this step and come back later if you need to test the following services: email, geolocation.
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 the service plans Compass paid for and run up the bill.
That's why we separate all those services between production and development environments, so that you can code freely without impacting the functioning of the deployed 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.
If you do need one of the few remaining services, you need to set them up and 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.
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.
