Inttrest - AI-Powered Event Discovery Platform¶

Welcome to the comprehensive documentation for Inttrest, an innovative AI-powered event discovery platform that combines advanced artificial intelligence, interactive mapping, and Model Context Protocol (MCP) integration to revolutionize how users find and explore events.

🌟 Platform Overview¶

Inttrest is a cutting-edge web application that leverages the power of AI to help users discover, explore, and interact with events in an intuitive and intelligent way. Built with modern technologies including the Vercel AI SDK, Next.js, and Mapbox, the platform provides a seamless experience for event discovery.

graph TB
    subgraph "User Interface"
        A[Next.js Frontend] --> B[AI Chat Interface]
        A --> C[Interactive Map]
        A --> D[Event Discovery]
    end

    subgraph "AI Layer"
        E[Vercel AI SDK] --> F[OpenAI Integration]
        E --> G[Natural Language Processing]
        E --> H[Intelligent Search]
    end

    subgraph "Data Sources"
        I[MCP Servers] --> J[Eventbrite MCP]
        I --> K[Instagram MCP]
        I --> L[LinkedIn MCP]
        I --> M[Meetup MCP]
    end

    subgraph "Infrastructure"
        N[MongoDB Database] --> O[Event Storage]
        P[Mapbox API] --> Q[Location Services]
        R[Geocoding] --> S[Address Resolution]
    end

    A --> E
    E --> I
    A --> N
    A --> P
    I --> N

    style A fill:#e3f2fd
    style E fill:#e8f5e8
    style I fill:#fff3e0
    style N fill:#f3e5f5

🚀 Key Features¶

🤖 AI-Powered Discovery¶

Natural Language Chat: Interact with an intelligent AI assistant to find events using conversational queries
Smart Recommendations: Get personalized event suggestions based on your interests and preferences
Contextual Understanding: AI understands complex queries like "tech events near me this weekend"

🗺️ Interactive Mapping¶

Real-time Visualization: View events on an interactive Mapbox-powered map
Geolocation Features: Find events based on your current location or any specified area
Clustering & Filtering: Organize events by category, date, and location with smart clustering

🔗 MCP Integration¶

Multi-Source Data: Aggregate events from multiple platforms through MCP servers
Real-time Synchronization: Keep event data fresh with automated updates
Extensible Architecture: Easily add new event sources through the MCP framework

💻 Modern Tech Stack¶

Frontend: Next.js 15+ with React 19, TypeScript, and Tailwind CSS
AI/ML: Vercel AI SDK with OpenAI integration
Mapping: Mapbox GL JS for interactive maps
Database: MongoDB for scalable event storage
Architecture: Model Context Protocol (MCP) for data integration

📁 Repository Structure¶

inttrest/
├── frontend/                   # Next.js React application
│   ├── app/                   # Next.js App Router
│   │   ├── api/              # API routes
│   │   ├── layout.tsx        # Root layout
│   │   ├── page.tsx          # Main page
│   │   └── globals.css       # Global styles
│   ├── components/           # React components
│   │   ├── Chat.tsx         # AI chat interface
│   │   └── Map.tsx          # Interactive map
│   ├── public/              # Static assets
│   ├── package.json         # Dependencies
│   └── next.config.ts       # Next.js configuration
├── mcp_servers/             # MCP server implementations
│   ├── eventbrite-mcp/      # Eventbrite integration
│   ├── instagram-server-next-mcp/  # Instagram integration
│   ├── linkedin-mcp-server/ # LinkedIn integration
│   ├── mcp-meetup/         # Meetup integration
│   └── unified_server.py   # Unified MCP server
├── .qwen/                   # AI model configuration
├── requirements.txt         # Python dependencies
├── prompt.xml              # AI prompt configuration
└── repomix-output.xml      # Project documentation

🛠️ Technology Stack¶

Frontend Technologies¶

Technology	Version	Purpose
Next.js	15.5.2	React framework with App Router
React	19.1.0	UI component library
TypeScript	^5	Type-safe JavaScript
Tailwind CSS	^4	Utility-first CSS framework
Mapbox GL	^3.14.0	Interactive mapping
React Map GL	^7.1.1	React wrapper for Mapbox

AI & ML Stack¶

Technology	Version	Purpose
Vercel AI SDK	^5.0.28	AI framework and utilities
@ai-sdk/openai	^2.0.23	OpenAI integration
@ai-sdk/react	^2.0.28	React hooks for AI
Zod	^4.1.5	Schema validation

MCP & Integration¶

Technology	Version	Purpose
@modelcontextprotocol/sdk	^1.17.4	MCP protocol implementation
@vercel/mcp-adapter	^1.0.0	Vercel MCP integration
MongoDB	^6.19.0	NoSQL database

🎯 Getting Started¶

Prerequisites¶

Before you begin, ensure you have the following installed:

Node.js 18+ with npm/yarn/pnpm
MongoDB (local or Atlas)
API Keys:
OpenAI API key
Mapbox access token
Event platform API keys (Eventbrite, etc.)

Quick Start¶

Clone the repository:

git clone https://github.com/FilippTrigub/inttrest.git
cd inttrest

Install dependencies:

cd frontend
npm install
# or
pnpm install

Configure environment variables:

cp .env.example .env.local
# Edit .env.local with your API keys

Start the development server:
```
npm run dev
# or
pnpm dev
```
Open your browser: Visit http://localhost:3000 to see the application.

Environment Configuration¶

Create a .env.local file in the frontend directory:

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

# Mapbox Configuration
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_mapbox_token_here

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017/inttrest
# or for MongoDB Atlas:
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/inttrest

# MCP Server URLs
MCP_EVENTBRITE_URL=http://localhost:3001
MCP_INSTAGRAM_URL=http://localhost:3002
MCP_LINKEDIN_URL=http://localhost:3003
MCP_MEETUP_URL=http://localhost:3004

# Application Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

🏗️ Architecture Overview¶

System Architecture¶

graph TB
    subgraph "Client Layer"
        A[Web Browser] --> B[Next.js Application]
    end

    subgraph "Application Layer"
        B --> C[AI Chat Component]
        B --> D[Map Component]
        B --> E[Event Discovery]

        C --> F[Vercel AI SDK]
        D --> G[Mapbox GL]
        E --> H[Event Management]
    end

    subgraph "AI & Processing Layer"
        F --> I[OpenAI API]
        F --> J[Natural Language Processing]
        H --> K[Event Aggregation]
        K --> L[Data Processing]
    end

    subgraph "Data Sources Layer"
        M[MCP Servers] --> N[Eventbrite MCP]
        M --> O[Instagram MCP]
        M --> P[LinkedIn MCP]
        M --> Q[Meetup MCP]

        L --> M
    end

    subgraph "Storage Layer"
        R[MongoDB] --> S[Events Collection]
        R --> T[Users Collection]
        R --> U[Sessions Collection]

        L --> R
        H --> R
    end

    subgraph "External APIs"
        V[Eventbrite API]
        W[Instagram API]
        X[LinkedIn API]
        Y[Meetup API]
        Z[Mapbox API]

        N --> V
        O --> W
        P --> X
        Q --> Y
        G --> Z
    end

    style B fill:#e3f2fd
    style F fill:#e8f5e8
    style M fill:#fff3e0
    style R fill:#f3e5f5

AI-Powered Interaction Flow¶

sequenceDiagram
    participant User
    participant Chat as AI Chat Interface
    participant AI as Vercel AI SDK
    participant OpenAI as OpenAI API
    participant MCP as MCP Servers
    participant DB as MongoDB
    participant Map as Map Component

    User->>Chat: "Find tech events in San Francisco"
    Chat->>AI: Process natural language query
    AI->>OpenAI: Generate structured search parameters
    OpenAI-->>AI: Return search criteria
    AI->>MCP: Request events with criteria

    par Eventbrite Search
        MCP->>Eventbrite: Search tech events in SF
        Eventbrite-->>MCP: Return event data
    and Instagram Search
        MCP->>Instagram: Search tech events in SF
        Instagram-->>MCP: Return event data
    and LinkedIn Search
        MCP->>LinkedIn: Search tech events in SF
        LinkedIn-->>MCP: Return event data
    end

    MCP->>DB: Store/update events
    MCP-->>AI: Return aggregated results
    AI->>Chat: Format response
    Chat-->>User: Display events & update map
    Chat->>Map: Update markers with new events
    Map-->>User: Show events on interactive map

� Development Workflow¶

Component Development¶

Create React Components in frontend/components/
Implement AI Features using Vercel AI SDK
Add Map Functionality with Mapbox integration
Connect MCP Services for data sources

Testing Strategy¶

Unit Tests: Component testing with Jest/React Testing Library
Integration Tests: AI SDK and MCP integration testing
E2E Tests: Full user journey testing
Performance Tests: Map rendering and AI response optimization

Deployment Process¶

Build Optimization: Next.js production build with Turbopack
Environment Configuration: Production environment variables
Database Migration: MongoDB schema updates
MCP Server Deployment: Deploy and configure MCP servers
CDN Deployment: Static asset optimization

📚 Documentation Sections¶

This documentation is organized into several key sections:

🏗️ Architecture ¶

Detailed system architecture, AI integration patterns, and MCP framework implementation.

🧩 Components ¶

In-depth documentation of React components, AI chat interface, and interactive mapping.

🤖 AI & ML ¶

AI SDK integration, OpenAI configuration, and natural language processing implementation.

🔗 MCP Servers ¶

Model Context Protocol server implementations for various event platforms.

💻 Frontend ¶

Next.js setup, React components, styling, and frontend architecture.

🛠️ Setup & Deployment ¶

Installation guides, configuration, and deployment instructions.

📖 API Reference ¶

Complete API documentation for all endpoints and data models.

👨‍💻 Development ¶

Developer guides, contributing guidelines, and testing strategies.

🤝 Contributing¶

We welcome contributions to Inttrest! Please read our Contributing Guide to get started.

Quick Contribution Steps¶

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

� License¶

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

🔗 Links¶

Repository: github.com/FilippTrigub/inttrest
Issues: Report bugs and request features
Discussions: Community discussions
Wiki: Additional documentation

🆘 Support¶

Need help? Here are the best ways to get support:

Documentation: Start with this comprehensive documentation
Issues: Create an issue for bugs or feature requests
Discussions: Join the discussion for questions and ideas
Email: Contact the maintainers directly

Ready to discover events with AI? Start with our Getting Started Guide or dive into the Architecture Overview! 🚀