Friendlink

Friendlink is a mobile-first social platform focused on helping people find real-world friends and activity partners — not dating. The app allows users to create and join interest-based meetups such as trips, hikes, study sessions, gym partners, and local activities, with a strong focus on commitment, safety, and accountability.

This project is being built as a long-term learning and portfolio project with production-grade architecture and engineering practices.

🎯 Product Vision

Friendlink is a real-world social coordination platform focused on helping people:

- Discover nearby activities - Find hikes, rides, trips, and meetups happening in your area
- Commit to plans - Only people who commit to showing up
- Actually show up - Designed to help you meet people in real life

#

Core Principles

- Real-world first: Every feature must map to offline action
- Commitment over engagement: We optimize for attendance, not time spent
- Trust before growth: Reliability beats virality
- AI assists, never replaces: AI suggests, ranks, moderates — never auto-publishes
- Backend-driven correctness: Mobile is thin; backend enforces rules

🏗️ Architecture

The project follows a production-grade, scalable architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Mobile App (React Native)                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Expo       │  │   Zustand    │  │   Axios      │      │
│  │   Router     │  │   (State)    │  │   (API)      │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│         │                  │                  │              │
└─────────┼──────────────────┼──────────────────┼──────────┘
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │
          ┌──────────────────▼──────────────────┐
          │      REST API (NestJS + TypeScript)  │
          │  ┌──────────────┐  ┌──────────────┐ │
          │  │   JWT Auth   │  │   Validation │ │
          │  │   + Refresh │  │   + Guards   │ │
          │  └──────────────┘  └──────────────┘ │
          └──────────────────┬──────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
    ┌─────▼─────┐    ┌───────▼───────┐  ┌──────▼──────┐
    │ PostgreSQL│    │    Redis     │  │   Docker    │
    │ (Sequelize)│    │  (Tokens,   │  │ (Container) │
    │            │    │ Blacklists)  │  │             │
    └───────────┘    └──────────────┘  └─────────────┘
                             │
                    ┌────────▼─────────┐
                    │  ML Scoring      │
                    │  (Python Runner) │
                    └──────────────────┘

🚀 Tech Stack

#

Mobile App

- React Native with Expo Router
- TypeScript for type safety
- Zustand for state management
- Axios for API communication
- Expo Secure Store for token storage
- Automatic refresh & retry queue for reliability

#

Backend

- NestJS + TypeScript
- PostgreSQL with Sequelize ORM
- Redis for tokens and blacklists
- JWT authentication with refresh rotation
- Soft deletes everywhere
- Transaction-safe participation logic
- Idempotent join/leave operations
- Pagination with hard limits
- Structured logging + request tracing
- Error codes contract
- Unit + E2E tests
- Dockerized deployment

#

Infrastructure

- Docker for containerization
- Versioned API (v1, frozen)
- Typed API contracts
- Mobile-aligned response formats

Machine Learning / AI Stack

- Logistic Regression (Scikit-learn): Predicts join probability for activity ranking
- StandardScaler (Scikit-learn): Normalizes numeric features for stable training
- Offline Python Training Pipeline: Reproducible model training outside the backend
- Feature Engineering: distance_km, popularity, user_activity_count, position bias, type encoding
- Versioned Model Artifacts: model.pkl, features.json, metrics.json, training_config.yaml, model_card.md
- Shadow Deployment: Safe evaluation without impacting production ranking
- Probabilistic Scoring: Calibrated probability outputs for ranking and thresholds
- Event-Based Learning Dataset: impression, click, join, dismiss
- Context-Aware Recommendation: geo distance, time proximity, popularity, user history
- Python Inference Runner: Backend calls a Python runner for scoring
- Feature Schema Validation: Validation using features.json to prevent mismatches
- SQL-Based Evaluation Metrics: CTR and join rate computed from logged events

✨ Key Features

#

Current Implementation (Phase 0 - ✅ Completed)

- Secure Authentication: JWT with refresh token rotation
- Activity Management: Create, discover, join, and leave activities
- Pagination & Refresh: Pull-to-refresh and infinite scroll
- State Management: Clean Zustand store with auth guards
- API Client: Automatic retry and refresh queue
- Production-Ready Backend: Hardened with tests and proper error handling

#

Planned Features (Phase 1+)

- Activity Discovery Quality: Tags, filters, location affinity
- Outcome Tracking: Track attendance and reliability
- Reputation System: Silent tracking of user reliability
- Activity Chat: One chat per activity with WebSockets
- AI-Based Ranking: Smart activity recommendations
- Smart Notifications: Context-aware notifications

📱 Platform Support

- iOS - Native iOS app (App Store - Coming Soon)
- Android - Native Android app (Google Play - Coming Soon)
- Web - Progressive Web App support

🎨 Design Philosophy

Friendlink follows a calm, trustworthy, and purposeful design:

- One Primary Action per Screen: Focus on clarity
- Vertical Rhythm: Use spacing, not borders
- Hero → Facts → Action: Consistent screen structure
- Bottom Actions: Sticky bottom action bars
- Text is UI: Human-readable, not raw values
- Material 3: Customized for premium feel

🔒 Security & Reliability

- Backend-driven correctness: All business logic on server
- Transaction-safe operations: Prevents race conditions
- Idempotent operations: Safe retries
- Soft deletes: Data recovery capability
- Structured error handling: Clear error codes
- Request tracing: Full audit trail

📊 Development Status

#

✅ Completed

- Backend API (Production-ready)
- Mobile app authentication
- Activities CRUD operations
- State management
- API contract (frozen v1)
- Docker setup
- Testing infrastructure

#

🚧 In Progress

- UI/UX polish
- Activity discovery improvements
- Reputation scoring system

#

📋 Planned

- Activity chat
- AI-based ranking
- Smart notifications
- Admin dashboard

🌐 Links

- Website: [friendlink-website.vercel.app](https://friendlink-website.vercel.app/)
- Status: In Active Development
- Platform: Mobile-First (iOS, Android, Web)