CircleTime

A full-stack social networking platform designed to help people discover meaningful connections through shared interests and activities. Built with Next.js, FastAPI, and Supabase.

Table of Contents

• Overview
• Features
• Technical Architecture
• Project Structure
• Technology Stack
• Database Schema
• API Reference
• Authentication & Security
• Third-Party Integrations
• Getting Started
• Docker Deployment
• Environment Variables

---

Overview

CircleTime is a social networking application that emphasizes thoughtful matching, local community focus, and authentic relationships. The platform helps users:

• Discover nearby people with similar interests
• Create and join activities
• Build meaningful connections through shared experiences
• Track engagement through gamification features

---

Features

User Management & Authentication

• Email/password authentication via Supabase
• Comprehensive user profiles with interests, bio, and location
• Profile management and updates

Social Connections

• Friend System: Send, accept, and manage connection requests
• Nearby Discovery: Location-based user matching using Haversine formula
• Friend Suggestions: AI-powered recommendations based on interest similarity

Activities

• Create activities with location, duration, and participant limits
• Join and participate in community activities
• Complete activities with photos and notes
• Category-based organization

Activity Feed

• Social feed showing completed activities
• Photo galleries for activities
• Like, comment, and share functionality
• Engagement metrics

Gamification

• Badges: Achievement system with rarity levels (common, rare, epic, legendary)
• Streaks: Track consecutive activity participation
• Seasonal Challenges: Time-limited events with progress tracking

Notifications

• Push notifications via Firebase Cloud Messaging
• In-app notification center
• Activity invitations and friend request alerts

Analytics

• Personal activity dashboard
• Engagement metrics
• Streak and badge progress tracking

---

Technical Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Client Layer                             │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Next.js 15 Frontend                       ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ ││
│  │  │  Pages   │  │Components│  │  Hooks   │  │  Middleware  │ ││
│  │  │ (App     │  │(Shadcn/  │  │(API,Auth,│  │(Security,    │ ││
│  │  │  Router) │  │ Radix UI)│  │Notifs)   │  │ Rate Limit)  │ ││
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────────┘ ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         API Layer                                │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    FastAPI Backend                           ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ ││
│  │  │   REST   │  │ Security │  │   ML     │  │ Notification │ ││
│  │  │Endpoints │  │(Validation│  │(Sentence │  │  (Firebase   │ ││
│  │  │          │  │ Sanitize)│  │Transform)│  │    FCM)      │ ││
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────────┘ ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Data Layer                                │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                      Supabase                                ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ ││
│  │  │PostgreSQL│  │   Auth   │  │ Storage  │  │  Real-time   │ ││
│  │  │  (RLS)   │  │  (JWT)   │  │ (Photos) │  │(Subscriptions│ ││
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────────┘ ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Key Architectural Patterns

Pattern	Description
Client-Server	Frontend communicates with backend via REST API
Component-Driven UI	54+ reusable Shadcn/ui components
Hook-Based State	Custom React hooks for API and state management
Database-First Security	Row Level Security (RLS) at PostgreSQL level
ML-Enhanced Recommendations	Sentence Transformers for semantic matching

---

Project Structure

circletime/
├── frontend/                          # Next.js 15 frontend
│   ├── app/                          # App Router pages
│   │   ├── page.tsx                  # Landing page
│   │   ├── login/                    # Authentication
│   │   ├── register/                 # User registration
│   │   ├── dashboard/                # User dashboard
│   │   ├── activities/               # Activity management
│   │   ├── feed/                     # Social feed
│   │   └── join/                     # Join activities
│   ├── components/                   # React components
│   │   ├── ui/                       # Shadcn/ui components
│   │   ├── ActivityFeed.tsx
│   │   ├── ActivityRecommendations.tsx
│   │   ├── FriendSuggestions.tsx
│   │   ├── NotificationBell.tsx
│   │   └── ...
│   ├── hooks/                        # Custom React hooks
│   │   ├── api.ts                    # API functions
│   │   ├── useAuth.tsx               # Authentication hook
│   │   └── useNotifications.ts       # Notifications hook
│   ├── lib/                          # Utilities
│   │   ├── supabaseClient.ts
│   │   └── firebase.ts
│   └── middleware.ts                 # Security middleware
│
├── backend/                          # FastAPI backend
│   ├── src/                          # Core application code
│   │   ├── main.py                   # Main FastAPI application
│   │   ├── security.py               # Security utilities
│   │   └── start_server.py           # Server startup script
│   ├── migrations/                   # SQL migration files
│   │   ├── supabase_schema.sql       # Core database schema
│   │   ├── create_feed_schema.sql    # Activity feed tables
│   │   ├── create_gamification_schema.sql
│   │   └── ...
│   ├── scripts/                      # Utility & debug scripts
│   │   ├── setup_recommendations.py
│   │   ├── generate_embeddings.py
│   │   └── ...
│   ├── requirements.txt              # Python dependencies
│   └── .env                          # Environment variables
│
├── docs/                             # Documentation
│   ├── API_EXAMPLES.md
│   ├── FIREBASE_SETUP.md
│   ├── NOTIFICATION_SYSTEM_DOCUMENTATION.md
│   └── ...
│
├── supabase/                         # Supabase configuration
├── docker-compose.yml                # Docker orchestration
├── Dockerfile                        # Multi-stage build
└── README.md                         # This file

---

Technology Stack

Frontend

Technology	Version	Purpose
Next.js	15.2.4	React framework with App Router
React	19	UI library
TypeScript	-	Type safety
Tailwind CSS	3.4.17	Styling
Shadcn/ui	-	Component library (54 components)
Radix UI	-	Accessible primitives
React Hook Form	-	Form management
Zod	-	Schema validation
Framer Motion	-	Animations
Recharts	-	Data visualization

Backend

Technology	Version	Purpose
FastAPI	0.104.1	Python web framework
Uvicorn	-	ASGI server
Supabase	-	Database client
Sentence Transformers	-	ML embeddings
Scikit-learn	-	Similarity calculations
Pillow	-	Image processing
Firebase Admin	-	Push notifications
Pandas/NumPy	-	Data processing

Infrastructure

Technology	Purpose
PostgreSQL (Supabase)	Primary database
Supabase Auth	Authentication
Firebase Cloud Messaging	Push notifications
Docker	Containerization
Supervisor	Process management

---

Database Schema

Core Tables

user_profiles

Column	Type	Description
id	UUID (PK)	References auth.users
email	TEXT	Unique email address
name	TEXT	Display name
username	TEXT	Unique username
age	INTEGER	User age
lat, lon	DOUBLE PRECISION	Geographic coordinates
bio	TEXT	User biography
interests	TEXT[]	Array of interest tags
created_at	TIMESTAMP	Account creation time

activities

Column	Type	Description
id	UUID (PK)	Activity identifier
name	TEXT	Activity name
description	TEXT	Activity description
location	TEXT	Location name
location_lat, location_lon	DOUBLE PRECISION	Coordinates
duration	INTEGER	Duration in minutes
creator_id	UUID (FK)	Activity creator
category	TEXT	Activity category
people	UUID[]	Participant IDs
max_participants	INTEGER	Maximum participants
status	TEXT	active/completed/cancelled
start_time	TIMESTAMP	Scheduled start
completed_at	TIMESTAMP	Completion time

connection_requests

Column	Type	Description
id	UUID (PK)	Request identifier
from_user_id	UUID (FK)	Sender
to_user_id	UUID (FK)	Recipient
status	TEXT	pending/accepted/rejected

user_friends

Column	Type	Description
id	UUID (PK)	Friendship identifier
user_id	UUID (FK)	First user
friend_id	UUID (FK)	Second user
created_at	TIMESTAMP	Friendship date

Social Interaction Tables

• activity_feed - Completed activities for display
• activity_photos - Photos attached to activities
• feed_likes - Like interactions
• feed_comments - Comment interactions
• feed_shares - Share interactions

Gamification Tables

• badges - Badge definitions with criteria
• user_badges - Awarded badges with progress
• user_streaks - Activity streaks by category
• seasonal_events - Time-limited challenges
• user_challenges - User challenge participation

Notification Tables

• notifications - In-app notifications
• user_devices - FCM device tokens

---

API Reference

Authentication

Method	Endpoint	Description
POST	/register	Register new user
POST	/login	Login with credentials

Profile Management

Method	Endpoint	Description
POST	/update-profile	Create/update profile
GET	/my-profile	Get current user profile
GET	/user-names	Get user names by IDs
GET	/all-usernames	Get all usernames

Social Discovery

Method	Endpoint	Description
GET	/nearby-users?lat=&lon=&radius_km=	Find nearby users
GET	/users-by-interest?interest=	Find users by interest
GET	/friend-suggestions?user_id=	AI-powered suggestions

Connections

Method	Endpoint	Description
POST	/connect	Send connection request
GET	/connection-requests?user_id=	Get incoming requests
POST	/connection-requests/{id}/respond?response=	Accept/reject
GET	/my-friends	Get friends list
POST	/remove-friend	Remove a friend

Activities

Method	Endpoint	Description
POST	/create-activity?creator_id=	Create activity
GET	/activities	List all activities
POST	/activities/{id}/complete	Mark as complete
POST	/activities/{id}/upload-photo	Upload photos
POST	/activities/{id}/edit	Edit activity
POST	/activities/{id}/delete	Delete activity

Activity Feed

Method	Endpoint	Description
POST	/feed/{id}/like	Like feed item
DELETE	/feed/{id}/like	Unlike feed item
POST	/feed/{id}/comments	Add comment
GET	/feed/{id}/comments	Get comments
POST	/feed/{id}/share	Share feed item

Recommendations

Method	Endpoint	Description
GET	/recommend-activities?user_id=	Get activity recommendations
POST	/track-activity-interaction	Track interactions
GET	/analytics	User analytics dashboard

Gamification

Method	Endpoint	Description
GET	/users/{id}/badges	Get user badges
GET	/users/{id}/streaks	Get user streaks

Notifications

Method	Endpoint	Description
POST	/store-device-token	Store FCM token
POST	/send-notification	Send notification
GET	/notifications/{user_id}	Get notifications
PATCH	/notifications/{id}	Update notification
POST	/notifications/{id}/mark-all-read	Mark all as read
GET	/notifications/{id}/unread-count	Get unread count

---

Authentication & Security

Authentication Flow

1. Registration: User signs up via Supabase Auth
2. JWT Issuance: Supabase issues JWT token on login
3. Token Storage: Token stored in localStorage
4. API Requests: Token passed in Authorization header
5. Validation: Backend validates token on protected endpoints

Security Features

Password Requirements

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number

Input Validation

• Email format validation (regex)
• Username: alphanumeric + underscore only
• Bio: 500 character limit
• Interests: 10 maximum
• XSS pattern detection and sanitization

Database Security (Row Level Security)

-- Users can only update their own profile
CREATE POLICY "Users can update own profile"
ON user_profiles FOR UPDATE
USING (auth.uid() = id);

-- Users can view all profiles
CREATE POLICY "Users can view all profiles"
ON user_profiles FOR SELECT
USING (true);

API Security Headers

• Content-Security-Policy (CSP)
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: enabled
• Strict-Transport-Security (HSTS)
• Referrer-Policy: strict-origin-when-cross-origin

Rate Limiting

• 100 requests per minute per IP
• Applied via middleware on both frontend and backend

---

Third-Party Integrations

Supabase

• Authentication: User registration, login, JWT management
• Database: PostgreSQL with Row Level Security
• Real-time: Built-in real-time subscriptions
• Storage: File storage for activity photos

Firebase

• Cloud Messaging (FCM): Push notifications
• Admin SDK: Server-side notification management

AI/ML Services

• Sentence Transformers: Semantic embeddings for recommendations
• OpenAI/Gemini: Vibe classification for activities

Google Maps

• Geocoding: Location services
• Maps Display: Activity location visualization

---

Getting Started

Prerequisites

• Node.js 20+
• Python 3.11+
• Supabase account
• Firebase project (for notifications)

Installation

1. Clone the repository

git clone https://github.com/pavan2184/Circletime.git
cd circletime

2. Set up the backend

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Set up the frontend

cd frontend
npm install

4. Configure environment variables (see Environment Variables)

5. Run the development servers

Backend:

cd backend/src
python start_server.py

Frontend:

cd frontend
npm run dev

The application will be available at:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000

---

Docker Deployment

Using Docker Compose

# Build and run
docker-compose up --build

# Run in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Docker Configuration

The Dockerfile uses a multi-stage build:

• Base image: python:3.11-slim
• Node.js: 20.x
• Process manager: Supervisor

Services are exposed on:

• Frontend: Port 3000
• Backend: Port 8000

---

Environment Variables

Frontend (frontend/.env.local)

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Firebase
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your_vapid_key

# Google Maps
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your_google_maps_key

# AI (optional)
NEXT_PUBLIC_GEMINI_API_KEY=your_gemini_key

Backend (backend/.env)

# Supabase
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_KEY=your_supabase_service_key

# OpenAI (optional)
OPENAI_API_KEY=your_openai_key

Additionally, place your Firebase service account JSON file at backend/firebase-service-account.json.

---

Key Components

Frontend Components

Component	Purpose
ActivityFeed	Display completed activities with photos
ActivityRecommendations	ML-powered activity suggestions
FriendSuggestions	Recommend users to connect with
NotificationBell	Notification indicator with unread count
NotificationInbox	Full notification management
BadgesGrid	Display earned badges and progress
StreaksCard	Show activity streaks
MobileNavigation	Mobile-optimized navigation
EditActivityModal	Edit activity details
EndActivityModal	Complete activity workflow

Frontend Pages

Route	Description
/	Landing page
/login	User authentication
/register	User registration with interests
/dashboard	User home with analytics
/activities	Activity management and discovery
/feed	Social activity feed
/join	Browse and join activities

---

Notable Technical Features

• Haversine Formula: Accurate geospatial distance calculation for nearby user discovery
• HEIC to JPEG Conversion: Automatic image format conversion for iOS photos
• Lazy Model Loading: Sentence Transformers loaded on-demand to reduce startup time
• Graceful Degradation: App functions without Firebase/FCM if unavailable
• Embedding Cache: Reuse semantic embeddings for efficiency
• Async Notification Delivery: Non-blocking notification processing

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
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