Skip to content

SOCIAL_FEEDS_IMPLEMENTATION.md

Latest commit

 

History

History
284 lines (223 loc) · 8.54 KB

SOCIAL_FEEDS_IMPLEMENTATION.md

File metadata and controls

284 lines (223 loc) · 8.54 KB

Social Media Feeds Implementation

Overview

This implementation adds a comprehensive social media section to the OpenAdapt landing page, displaying real-time social proof and community engagement across multiple platforms.

Features Implemented

1. GitHub Activity Component

  • Location: /components/GitHubActivity.js
  • Features:
    • Real-time repository statistics (stars, forks, watchers, issues)
    • Direct link to GitHub repository
    • Automatic data fetching from GitHub API
    • Loading and error states
    • Responsive grid layout
  • API: GitHub REST API v3 (no authentication required for public repos)

2. Reddit Feed Component

  • Location: /components/RedditFeed.js
  • Features:
    • Latest 5 Reddit posts mentioning "OpenAdapt"
    • Displays post title, subreddit, score, and comments
    • Filters out stickied posts
    • Direct links to Reddit discussions
    • Fallback message when no posts found
  • API: Reddit JSON API (no authentication required)

3. Hacker News Feed Component

  • Location: /components/HackerNewsFeed.js
  • Features:
    • Latest HN stories mentioning "OpenAdapt"
    • Displays story title, points, comments, and author
    • Filters out stories with no engagement
    • Direct links to stories and discussions
    • Fallback message when no stories found
  • API: Algolia HN Search API (free, no authentication)

4. Twitter/X Feed Component

  • Location: /components/TwitterFeed.js
  • Features:
    • Embedded Twitter timeline for @OpenAdaptAI
    • Shows latest 3 tweets
    • Native Twitter widget with dark theme
    • Follow button/link
  • Technology: Twitter embedded timeline widget (free, official)

5. Social Section Component

  • Location: /components/SocialSection.js
  • Features:
    • Integrates all social feed components
    • Responsive grid layout
    • Call-to-action section with Discord and GitHub links
    • Clean, modern design matching OpenAdapt branding

6. API Route for Caching

  • Location: /pages/api/social-feeds.js
  • Features:
    • Server-side data fetching
    • 5-minute cache with stale-while-revalidate
    • Aggregates data from GitHub, Reddit, and HN
    • Error handling for failed API calls
    • Reduces client-side API requests

Design Philosophy (80/20 Rule)

This implementation follows the 80/20 principle to maximize impact while minimizing complexity:

High Impact, Low Complexity:

  1. GitHub Stats - Shows active development and community support
  2. Reddit Discussions - Shows real community conversations
  3. Hacker News - Shows engagement from tech community
  4. Twitter Feed - Shows official updates and brand presence

Technologies Used:

  • Free APIs only - No paid services or API keys required
  • Native embed widgets - Twitter widget for official, maintained solution
  • Direct JSON endpoints - Reddit and HN provide free JSON access
  • Server-side caching - Improves performance and reduces API calls

File Structure

/components
  ├── GitHubActivity.js
  ├── GitHubActivity.module.css
  ├── RedditFeed.js
  ├── RedditFeed.module.css
  ├── HackerNewsFeed.js
  ├── HackerNewsFeed.module.css
  ├── TwitterFeed.js
  ├── TwitterFeed.module.css
  ├── SocialSection.js
  └── SocialSection.module.css

/pages
  ├── index.js (updated to include SocialSection)
  └── /api
      └── social-feeds.js

Integration

The SocialSection has been added to the landing page (/pages/index.js) between the IndustriesGrid and EmailForm sections:

<IndustriesGrid ... />
<SocialSection />
<EmailForm />

Styling

All components use CSS Modules for scoped styling, matching the existing OpenAdapt design:

  • Color scheme: Purple/blue accents (#560DF8, #60a5fa)
  • Background: Dark theme with semi-transparent overlays
  • Typography: Clean, modern fonts with proper hierarchy
  • Responsive: Mobile-first design with breakpoints at 768px and 480px

Performance Considerations

  1. Lazy Loading: Twitter widget loads asynchronously
  2. Server-Side Caching: API route caches responses for 5 minutes
  3. Parallel Fetching: All API calls made in parallel using Promise.all/Promise.allSettled
  4. Error Handling: Graceful degradation when APIs fail
  5. Stale-While-Revalidate: Serves cached content while fetching fresh data

API Rate Limits

All APIs used have generous free tiers:

  • GitHub API: 60 requests/hour (unauthenticated), 5000/hour (authenticated)
  • Reddit JSON: No documented rate limit for reasonable use
  • HN Algolia: No documented rate limit
  • Twitter Embed: No rate limit (client-side widget)

With server-side caching (5 minutes), the site will make:

  • GitHub: ~12 requests/hour
  • Reddit: ~12 requests/hour
  • HN: ~12 requests/hour

All well within free tier limits.

Testing

Manual Testing Steps:

  1. Install dependencies:

    npm install

  2. Run development server:

    npm run dev

  3. Open browser:

    http://localhost:3000

  4. Verify:

    • Scroll to "Join the Community" section
    • Check that GitHub stats load correctly
    • Verify Reddit feed shows recent posts (if any exist)
    • Verify HN feed shows stories (if any exist)
    • Check that Twitter timeline loads
    • Test responsive design by resizing browser
    • Verify all links open correctly in new tabs

API Endpoint Testing:

Test the caching API:

curl http://localhost:3000/api/social-feeds

Should return JSON with GitHub, Reddit, and HN data.

Future Enhancements (Optional)

If you want to add more features later (following the 80/20 rule):

Easy Wins:

  1. LinkedIn Company Page - Embed official widget
  2. YouTube Videos - Embed playlist or latest video
  3. Discord Widget - Show online member count
  4. GitHub Contributors - Show top contributors with avatars

More Complex:

  1. Sentiment Analysis - Analyze social mentions for positive/negative sentiment
  2. Trending Topics - Extract and display trending keywords from discussions
  3. Historical Charts - Show growth of stars, followers over time
  4. Real-time Updates - WebSocket connections for live feed updates

Troubleshooting

Issue: GitHub API rate limit exceeded

Solution: Add GitHub personal access token to environment variables:

// In components/GitHubActivity.js
fetch('https://api.github.com/repos/OpenAdaptAI/OpenAdapt', {
  headers: {
    Authorization: `token ${process.env.GITHUB_TOKEN}`
  }
})

Issue: Reddit feed not loading

Solution: Check if Reddit JSON endpoint is accessible. Reddit may block certain user agents. Add headers:

fetch('https://www.reddit.com/search.json?q=openadapt', {
  headers: {
    'User-Agent': 'OpenAdapt-Website/1.0'
  }
})

Issue: Twitter timeline not showing

Solution:

  1. Check that Twitter widget script loads (check browser console)
  2. Verify @OpenAdaptAI Twitter account exists and is public
  3. Try clearing browser cache
  4. Check Twitter's widget documentation for any changes

Issue: No social mentions found

Solution: This is expected if OpenAdapt hasn't been mentioned on these platforms yet. The components show appropriate fallback messages with search links.

Deployment

When deploying to production (Vercel/Netlify):

  1. Build the project:

    npm run build

  2. Test production build:

    npm run export

  3. Environment Variables (optional):

    • GITHUB_TOKEN - Personal access token for higher rate limits

  4. Verify:

    • All API routes work (/api/social-feeds)
    • Caching headers are set correctly
    • Twitter widget loads on production domain
    • All external links work

Maintenance

Weekly:

  • Monitor API rate limits in server logs
  • Check for any failed API calls

Monthly:

  • Verify all social feed APIs still work
  • Update any deprecated API endpoints
  • Review and optimize cache duration if needed

As Needed:

  • Update Twitter account handle if changed
  • Add new social platforms if they become relevant
  • Adjust styling to match brand updates

Credits

Implementation follows the 80/20 principle for maximum impact with minimal complexity. All components use free APIs and services, ensuring zero ongoing costs.

Questions?

For questions or issues with this implementation, please:

  1. Check this documentation first
  2. Review the component code and comments
  3. Test the API endpoints directly
  4. Submit a GitHub issue if problems persist

Implementation Date: January 2026 Version: 1.0.0 Status: Complete and ready for production