🗂️ Table of Contents

1. About The Project
   • Authentication
   • Onboarding
   • Room Pairing
   • Home Page
   • Profile
   • Library
   • Entries
   • Real-time Chat
   • Google Calendar Integration
   • Database Structure
2. Tech Stack
3. What We Achieved
4. Getting Started
   • Prerequisites
   • Installation
   • Configuration Steps
5. Resources
6. Contributing
7. Team
8. License
9. Contact

About The Project

0-KM is a mobile app designed to help couples stay connected across any distance. Built with modern technologies, it offers a comprehensive platform for relationship building and maintenance.

🔐 Authentication

Sign up and login with email or Google OAuth

Our secure authentication system provides:

• Email and password sign-up/sign-in
• Google OAuth integration
• Secure session management with Clerk
• Email verification process
• Forgot password functionality

Onboarding

Smooth onboarding experience for new users

Smooth onboarding experience includes:

• User profile creation
• Partner information setup
• Relationship preferences configuration
• Getting started guide

👫 Room Pairing

Secure couple workspace creation and joining

Unique pairing system features:

• Secure room creation and joining
• Partner verification process
• Private couple workspace establishment
• Synchronized user experience

🏠 Home Page

Main dashboard with relationship milestones and quick access

The main dashboard provides:

• Real Time widgets updating your partner’s weather and time zone
• Notification on calendar booking
• Real Time Anniversary date
• Sharing and watching YouTube together
• Stream music on Spotify and control music of your partner

Note: Remember to keep your Spotify active (go to your Spotify, play a song and pause, navigate back to the app) before searching up a song in Spotify widget in 0km.

👤 Profile

Profile management - logout, leave room, and see partner details

Comprehensive profile management:

• Personal information editing
• Relationship status updates
• Account settings
• Privacy controls
• Logout functionality
• Leave room option
• Partner information viewing

📚 Library

Shared digital book collection and reading tracking

Shared digital library includes:

• Book collection management
• Reading progress tracking
• Shared reading experiences
• Book recommendations

📝 Entries

Interactive journaling and memory documentation

Interactive journaling system:

• Personal diary entries
• Shared memories documentation
• Photo, video, location and text entries
• Timeline organization
• Leaflet map integration for location-based memories
• Pagination fetch
• Cloudinary integration for media storage
• Dynamic photo + video grid

💬 Real-time Chat

Advanced messaging platform for couples

Advanced messaging platform features:

• Realtime messaging
• Media sharing (photos, videos)
• Message history
• Push notifications
• Online/offline status
• Edit / Delete messages
• Privacy Settings

Google Calendar Integration

Calendar synchronization for couples

Calendar synchronization includes:

• Google Calendar connection
• Mutual availability viewing
• Event scheduling
• Virtual date planning
• Calendar conflict resolution

💾 Database Structure

Sustainable and scalable data architecture

Robust data architecture using:

• 8 tables
• Supabase for structured data
• Real-time data synchronization
• Secure data management
• Efficient querying system

(back to top)

🛠️ Tech Stack

This project is built using modern technologies to ensure performance and scalability.

Frontend

Backend

Authentication & Database

Services & APIs

(back to top)

🏆 What We Achieved

Our team winning the Technical Titan Award at VTMP Demo Day!

• Hands-on Experience in Mobile & iOS Development: We built full-stack, feature-rich, cross-platform mobile application using React Natve, with all UI components developed from scratch. The app is integrated with Supabase as the backend, allowing for real-time data handling.
• Teamwork and Collaboration: We leveraged tools like ngrok to enable seamless cross-platform development with Expo CLI. Our development process involved consistent debugging, version control using Git, and detailed code reviews on pull requests. Beyond technical execution, we significantly improved our soft skills, particularly in clear and efficient team communication.
• Award-Winning Execution: Our commitment to high-quality design, robust functionality, and innovation earned us the Technical Titan Award, recognizing our app as a standout in both technical complexity and user experience.

(back to top)

🚀 Getting Started

To get a local copy up and running, follow these simple steps.

📋 Prerequisites

• Node.js (v16.0.0 or higher)
• npm (v7.0.0 or higher)
• Git
• Expo CLI
• ngrok (for exposing local backend to mobile device)
• iOS Simulator (for iOS development) or Android Emulator (for Android development)

🛠️ Installation

1. Create required accounts and get API keys:

   • Clerk Account - For authentication
   • Supabase Account - For database
   • Google Cloud Console - For Calendar API
   • Cloudinary Account - For media storage
   • ngrok Account - For exposing local backend to mobile devices

2. Clone the repository:

   git clone https://github.com/ThanhDatVu111/0-KM.git
   cd 0km-app

3. Install dependencies:

   # Install root dependencies
   npm install
   
   # Or install separately
   cd frontend
   npm install
   
   cd ../backend
   npm install

4. Configure Environment Variables:

   # Copy environment files
   cp frontend/.env.example frontend/.env
   cp backend/.env.example backend/.env

5. Set up your environment variables:

   Frontend (.env):

   EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key
   EXPO_PUBLIC_API_HOST=localhost
   EXPO_PUBLIC_API_PORT=3001
   EXPO_PUBLIC_API_PUBLIC_URL=https://your-ngrok-url.ngrok-free.app
   EXPO_PUBLIC_CLOUDINARY_CLOUD_NAME=your_cloudinary_name
   EXPO_PUBLIC_CLOUDINARY_API_KEY=your_cloudinary_key
   EXPO_PUBLIC_CLOUDINARY_SIGN_URL=https://your-ngrok-url.ngrok-free.app/cloudinary-sign
   EXPO_PUBLIC_WEB_CLIENT_ID=your_google_web_client_id
   EXPO_PUBLIC_IOS_CLIENT_ID=your_google_ios_client_id
   EXPO_PUBLIC_CLIENT_SECRET=your_google_client_secret
   EXPO_PUBLIC_SUPABASE_URL=your_supabase_url
   EXPO_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

   Backend (.env):

   PORT=3001
   NGROK_URL=https://your-ngrok-url.ngrok-free.app
   SUPABASE_URL=your_supabase_url
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_key
   CLERK_SECRET_KEY=your_clerk_secret_key

6. Set up your Supabase database:

   • Create tables for users, rooms, chats, library, etc.
   • Set up authentication policies
   • Configure real-time subscriptions

7. Start the development servers:

   First, start ngrok to expose your backend:

   # Install ngrok if you haven't already
   npm install -g ngrok
   
   # Start ngrok tunnel for port 3001
   ngrok http 3001

   Copy the ngrok URL (e.g., https://abc123.ngrok-free.app) and update your environment variables.

   Backend:

   cd backend
   npm run dev

   Frontend:

   cd frontend
   npx expo start --clear

8. Run on device:

   • Scan QR code with Expo Go app (iOS/Android)
   • Or press i for iOS simulator
   • Or press a for Android emulator

(back to top)

🔧 Configuration Steps

1. Clerk Setup

• Create a new application in Clerk Dashboard
• Configure authentication methods (Email, Google OAuth)
• Add your application's domain to allowed origins
• Set up webhook endpoints for user management

2. Supabase Setup

• Create a new Supabase project
• Set up database tables using provided SQL schemas
• Configure Row Level Security (RLS) policies
• Enable real-time subscriptions for chat functionality

3. Google Calendar API Setup

• Create a project in Google Cloud Console
• Enable Calendar API
• Configure redirect URIs

4. Cloudinary Setup

• Create a Cloudinary account
• Get your cloud name and API credentials
• Configure upload presets for media files
• Set up transformation settings

5. ngrok Setup

• Create a free ngrok account at ngrok.com
• Install ngrok: npm install -g ngrok
• Authenticate: ngrok config add-authtoken YOUR_AUTHTOKEN
• Start tunnel: ngrok http 3001
• Copy the HTTPS URL and update your environment variables
• Important: Update both frontend and backend .env files with the ngrok URL

(back to top)

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

📚 Resources

Aggregated list of resources and assets, documenting our development process.

1. Design Doc
2. Figma Design
3. Project Demo Presentation

(back to top)

👥 Team

Meet the talented team behind 0-KM:

🎯 Project Leadership

Tech Lead Thanh Dat Vu Full-Stack Development & Architecture

Project Advisor Van Nguyen Technical Guidance & Mentorship

💻 Development Team

Chau Tran Software Engineer

Tuan-Anh Ngo Software Engineer

Quinxie Doan Software Engineer

(back to top)

📜 License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)