✨ Explore Live Portal • 🐛 Report An Issue • 💡 Request A Module

---

🎨 Tech Stack & Integrations

---

📚 Table of Contents

1. 🌍 System Overview & Problem Solved
2. 🧩 Architectural & System Workflow Blueprint
3. ✨ Key & Advanced Modules
4. 📁 Project Directory Map
5. 🔄 Core Execution Workflows
6. 🌐 Backend & ML API Reference
7. 🛡️ Security, Caching & Performance Engine
8. 🚀 Getting Started & Installation
9. 🤝 Contributing
10. 📜 License

---

🌍 System Overview & Problem Solved

The Problem
Coordinating travel remains fragmented. Planning a trip requires crossing dozens of hotel, flight, and booking websites, spending an average of 10-15 hours. Furthermore, collaborating with travelers online brings safety concerns, coordination group chats lack client-side privacy protection, and expense splitting gets complicated across users.

The Solution
AdventureNexus is an AI-powered travel planning and social web application. Using Groq, FastAPI Content Recommendation, and NaCl peer-to-peer encryption, users can instantly formulate plans, find matching travel companions, chat with zero-knowledge database relays, assess location safety in real time, and resolve debts seamlessly.

---

🧩 Architectural & System Workflow Blueprint

The following unified system blueprint maps the data paths, socket links, database logs, caching layers, and AI engines driving the travel ecosystem:

---

✨ Key & Advanced Modules

🧠 1. AI Planning & Itinerary Engine (Click to expand)

AdventureNexus creates complete itineraries in seconds. It constructs day-by-day routines consisting of detailed schedules, activities, timings, and coordinates.

• Hotel Integration: Dynamically assigns hotels with relative price structures, guest capacity ratings, and real-time reviews.
• Flight/Train Mapping: Recommends appropriate travel flights and train carriers based on selected regions.
• OsmMap Routing: Renders points of interest and paths interactively using leaf map nodes.

💬 2. End-to-End Encrypted (E2EE) Chat (Click to expand)

AdventureNexus secures all direct and group conversations. Peer-to-peer messaging uses key agreements where the server acts as a blind relay:

• TweetNaCl Protocol: Uses X25519 Elliptic-curve Diffie-Hellman key agreement + XSalsa20 stream cipher + Poly1305 MAC.
• Client-Side Key Generation: Private keys are generated on register/login and stored in IndexedDB (NexusE2EE database, keys store) instead of localStorage to block cross-site script (XSS) extraction.
• Per-Member Fan-out Group Encryption: For group rooms, messages are encrypted independently using the recipient's respective public keys.

💰 3. Expense Ledger & Debt Simplifier (Click to expand)

Keep track of group expenditures. AdventureNexus resolves debts by minimizing transactions:

• Custom Splits: Split by shares, percentage matrices, or unequal dollar amounts.
• Graph Minimization algorithm: Simplifies group netting (e.g., if A owes B $10 and B owes C $10, A pays C $10 directly).

🌦️ 4. Live Travel Intelligence Engine (Click to expand)

Fetches real-time environmental context for travelers:

• Live Weather: Connects to the Open-Meteo API for real-time climate telemetry (precipitation, UV index, relative humidity, wind speed).
• Crowd Density & Risk Scores: Combines booking statistics, weather indices, and crime rates to evaluate location safety indexes.
• Hotspot Advisor: Advises optimal visit times based on historical crowd levels.

🛡️ 5. Social Trust Shield & Toxicity Engine (Click to expand)

Keeps the platform clean and authentic:

• AI Toxicity Moderation: Groq model parses comments/posts to quarantine toxic, abusive, or spam material.
• Review Fraud Detection: Computes a Jaccard Text Similarity Index to check historical testimonials for duplicated phrasing or bot patterns.

📊 6. Admin Observability Control Center (Click to expand)

Provides system administrators with tools to monitor and manage the ecosystem:

• Traffic Simulator: Injects mock user behavior (likes, post updates, travel searches) to test UI rendering and socket reliability.
• Audit Log Trail: Logs all moderator events with severity indices (info, warning, quarantine).
• Telemetry Charts: Displays real-time API latency averages, CPU loads, and error distributions.

---

📸 Core UI Visuals

🖥️ Desktop Dashboard

Landing & Search Space

Itinerary Builder & Final Result Reviews

📱 Responsive Mobile Layouts

     

---

📁 Project Directory Map

Backend Layout (Express + TypeScript)

Directory / File	Type	Description / Responsibilities
📂 Backend/src/	Root	Main Express + TypeScript application directory.
📄 ├── app.ts	File	Server entry point and HTTP middleware routing pipeline.
📂 ├── config/	Folder	Centralized server environment variables, API configurations, and keys.
📂 ├── jobs/	Folder	Background cron runner (handles metrics and automated rebuilder tasks).
📂 ├── modules/	Folder	Feature-domain modules:
📂 ├── admin/	Subfolder	Admin tools, logs auditing, and live traffic simulation.
📂 ├── ai/	Subfolder	Match Score calculators using cosine similarity parameters.
📂 ├── bookings/	Subfolder	Accommodations integration modules and search APIs.
📂 ├── expenses/	Subfolder	Ledger matching split algorithms and graph-minimization debt netting.
📂 ├── messaging/	Subfolder	Conversation routers, E2EE public key lookup, and Socket relays.
📂 ├── planning/	Subfolder	Manual and AI itinerary planners powered by Groq.
📂 ├── safety/	Subfolder	Location safety trackers and user-alert logs.
📂 └── travelIntel/	Subfolder	Weather forecast APIs, crowd indicators, and hotspots trackers.
📂 └── shared/	Root	Shared utility libraries:
📂 ├── database/	Subfolder	Database connectors, Mongo schema initializers, and Mongoose models.
📂 ├── middleware/	Subfolder	JWT validation guards, request sanitizers, and telemetry loggers.
📂 ├── redis/	Subfolder	Redis caching connections and session managers.
📂 └── socket/	Subfolder	Socket.io event list listeners and live socket registries.

Frontend Layout (React + Vite)

Directory / File	Type	Description / Responsibilities
📂 frontend/src/	Root	React frontend client application directory.
📄 ├── App.jsx	File	Main Router definition, page loading rules, and route guards.
📂 ├── admin/	Folder	Administrator dashboard pages, user tables, and metrics widgets.
📂 ├── components/	Folder	Reusable UI components, design layouts, and Framer Motion wrappers.
📂 ├── context/	Folder	Global context providers (Authentication, Socket connectors, Chat buffers).
📂 ├── features/	Folder	Feature modules:
📂 ├── community/	Subfolder	Chat interfaces, user boards, profiles, and group elements.
📂 ├── legal/	Subfolder	Terms of service, privacy policy, and usage disclaimer pages.
📂 ├── planning/	Subfolder	Itinerary creators, maps layers, hotel lists, and search screens.
📂 └── user/	Subfolder	Authentication portals (login, signup) and user configurations.
📂 └── lib/	Folder	Security protocols, TweetNaCl wrapper functions, and IndexedDB storage drivers.

ML Layout (FastAPI + Python)

Directory / File	Type	Description / Responsibilities
📂 ML/	Root	Python-based FastAPI machine learning server directory.
📂 ├── models/	Folder	Saved TF-IDF vectorizers and similarity models.
📂 └── src/	Folder	Recommender codebases:
📄 ├── main.py	File	FastAPI application setup, router declarations, and endpoint bindings.
📄 ├── recommender.py	File	Cosine Similarity recommendation matrix engines.
📄 └── train.py	File	Training pipelines (reads data from MongoDB, trains vectors, and saves models).

---

🔄 Core Execution Workflows

1. Firebase Authentication Sync

The Express backend verifies client JWTs from Firebase Auth:

Step	Source	Direction	Destination	Action / Payload Details
1	Client App	➔	Firebase Server	Requests IdToken for session setup.
2	Firebase Server	➔	Client App	Returns verified JWT IdToken.
3	Client App	➔	Express Gateway	POST /users/register containing JWT header.
4	Express Gateway	➔	Firebase Admin SDK	Authenticates JWT token credentials.
5	Firebase Admin SDK	➔	Express Gateway	Decodes verified User UID and Email.
6	Express Gateway	➔	MongoDB Atlas	Queries / Upserts user context matching firebaseUid.
7	MongoDB Atlas	➔	Express Gateway	Returns persistent database user document.
8	Express Gateway	➔	Client App	Returns session payload & initialized store context.

2. End-to-End Encrypted (E2EE) Chat

This workflow ensures that the database server never has access to the raw message payload:

Step	Source	Direction	Destination	Action / Encryption Details
1	Alice Client	➔	Alice Client	Generates secure X25519 elliptic curve keypair.
2	Alice Client	➔	IndexedDB	Saves local private SecretKey to secure client sandbox.
3	Alice Client	➔	Express Gateway	Publishes public key to backend directory.
4	Alice Client	➔	Express Gateway	Queries public key matching destination (Bob's profile).
5	Express Gateway	➔	Alice Client	Returns Bob's X25519 public key.
6	Alice Client	➔	Alice Client	Encrypts payload with Bob's public key and local secret key (using TweetNaCl).
7	Alice Client	➔	Express Gateway	Transmits raw E2EE cipher packet + 24-byte unique Nonce.
8	Express Gateway	➔	Bob Client	Emits chat:message event via Socket.io relay.
9	Bob Client	➔	Bob Client	Decrypts socket packet using Alice's public key + Bob's local secret key.

---

🌐 Backend & ML API Reference

🔐 User & Profile Routes

• POST /api/v1/users/register - Registers a session verifying Firebase tokens.
• GET /api/v1/users/profile - Fetches authenticated user data.
• POST /api/v1/users/e2ee/public-key - Uploads user X25519 public key.
• GET /api/v1/users/e2ee/public-key/:firebaseUid - Retrieves a target user's public key.

🗺️ AI Travel Itineraries

• POST /api/v1/plans/search/destination - Triggers Groq AI travel generation.
• POST /api/v1/plans/ - Saves a manually constructed plan.
• GET /api/v1/plans/my-plans - Lists active plans.
• GET /api/v1/plans/recommendations - Personalized recommendation matches.
• POST /api/v1/plans/:planId/save - Saves a public plan.

💬 Secure Messaging

• POST /api/v1/messaging/conversation - Retrieves/creates a 1-to-1 conversation node.
• POST /api/v1/messaging/message - Relays encrypted payload.
• GET /api/v1/messaging/messages/:conversationId - Fetches paginated encrypted logs.

💰 Expense Splitter

• POST /api/v1/expenses/groups - Creates a new expense group.
• POST /api/v1/expenses/groups/:id/expenses - Registers an expense.
• GET /api/v1/expenses/groups/:id/balances - Returns netting debt simplified transactions.

🤖 FastAPI Machine Learning

• GET /recommend/{user_id} - Cosine similarity recommendation list.
• POST /retrain - Re-fits models on MongoDB dataset.

---

🛡️ Security, Caching & Performance Engine

1. IndexedDB Security Vector

By saving private key hashes directly to IndexedDB, keys are isolated from variables stored in localStorage, protecting them from third-party scripts and cross-site script (XSS) extraction attacks.

2. High-Performance Caching Layer

• Redis Key Namespaces: Caches use unique namespaces (e.g., search:<to>:<from>... or recommendations:<user>) and normalizes key segments to prevent duplicate cache allocations.
• Fallback Safety: If the Redis server experiences downtime, the Express server falls back to direct database queries without crashing.

3. API Resilience & Rate Limits

• Email Dispatch Queue: Enforces a sequential queue dispatch with a 500ms delay between iterations, preventing rate limit errors when using Resend API.
• Input Sanitization: Global Express sanitizers clean input objects recursively to prevent MongoDB Query Injection and XSS payloads.

---

🚀 Getting Started & Installation

Prerequisites

• Node.js v18+ & npm
• Python 3.9+ & pip
• MongoDB connection URI (Atlas or Local)
• Redis Server (Optional, falls back to db if disconnected)

System Setup

1. Setup Backend Server

cd Backend
npm install

# Create environment configuration file
cp .env.example .env

Update .env with your system configurations:

PORT=8080
DB_URI=mongodb+srv://...
REDIS_URL=redis://localhost:6379
GROQ_API_KEY=gsk_...
RESEND_API_KEY=re_...
FIREBASE_PROJECT_ID=...
FIREBASE_CLIENT_EMAIL=...
FIREBASE_PRIVATE_KEY=...

Start the backend server in development mode:

npm run dev

2. Setup Frontend Client

cd ../frontend
npm install

# Create environment configuration file
cp .env.example .env.local

Update .env.local to point to the local backend:

VITE_BACKEND_URL=http://localhost:8080
VITE_CURRENCY=INR
VITE_FIREBASE_API_KEY=...
VITE_FIREBASE_AUTH_DOMAIN=...
VITE_FIREBASE_PROJECT_ID=...

Start Vite development server:

npm run dev

3. Setup ML Recommendation Microservice

cd ../ML
pip install -r requirements.txt

# Train content models
python3 -m src.train

# Start the FastAPI engine
uvicorn src.main:app --port 8001 --reload

---

🤝 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.

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

---

📜 License

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

---

Made with ❤️ by the AdventureNexus Team