"Connect people through shared interests, proximity, and real stories"
A hypermodern, emotion-driven social discovery platform that combines local news, intelligent matching, and real-time human connection.
- 📋 Project Roadmap - 7-week development plan
- 🏗️ Architecture Guide - System design & data flows
- 🎨 UI Style Guide - Design system & components
- 👨💻 Developer Guide - Getting started & best practices
- 📊 Executive Summary - Project overview for stakeholders
The News Plugin is a decentralized, real-time social platform that:
- 📰 Shows personalized news from your proximity (interest + location filtered)
- 👥 Connects you with like-minded people nearby (0-100% match score)
- 💬 Enables real-time chat and friendships
- ⚡ Works entirely P2P with Gun.js (no central server)
- 💝 Delivers Instagram-level polish with emotion-driven design
- Category Selection: Choose from 14 different news categories (Technology, Business, Politics, Science, Health, Sports, Entertainment, Environment, Education, Travel, Food, Fashion, Culture, Local News)
- Custom Tags: Add custom tags to filter news by specific topics
- Keywords: Define keywords to match against article content
- Real-time Filtering: Articles are filtered in real-time based on your preferences
- Geolocation Support: Automatically detect your current location
- Manual Location: Enter coordinates manually if geolocation is unavailable
- Radius Control: Set search radius from 1km to 500km
- Distance Display: See how far each article is from your location
- Priority Sorting: Articles closer to you appear first
- Seamless Loading: Articles load automatically as you scroll
- Performance Optimized: Paginated loading with 20 articles per page
- Smooth Experience: No page reloads or manual "Load More" buttons
- Gun.js Integration: All data stored in Gun.js decentralized database
- Real-time Sync: Changes sync automatically across all connected peers
- Offline Support: Works offline with local storage
- No Central Server: Fully decentralized data storage
- Frontend: Vue 3 (Composition API), TypeScript
- Styling: Tailwind CSS
- Icons: Heroicons
- P2P Database: Gun.js
- Build Tool: Vite
- Module Federation: Dynamic plugin loading
- Plugin SDK: @toplocs/plugin-sdk
news-plugin/
├── src/
│ ├── assets/
│ │ └── main.css # Global styles with Tailwind
│ ├── components/
│ │ ├── InterestsInput.vue # Interest management component
│ │ └── LocationInput.vue # Location settings component
│ ├── composables/
│ │ └── useNews.ts # Gun.js news operations composable
│ ├── types/
│ │ └── news.ts # TypeScript type definitions
│ ├── views/
│ │ ├── NewsView.vue # Main news feed view
│ │ └── SidebarView.vue # Settings sidebar
│ ├── gun.ts # Gun.js configuration
│ ├── Main.vue # Plugin entry component
│ └── main.ts # Application entry point
├── index.html # HTML entry point
├── vite.config.ts # Vite + Module Federation config
├── tailwind.config.js # Tailwind CSS configuration
├── tsconfig.json # TypeScript configuration
└── package.json # Dependencies and scripts
// News articles
gun.get('news_plugin').get(sphereId).get('articles').get(articleId)
// User interests
gun.get('news_plugin').get(sphereId).get('interests')
// User location
gun.get('news_plugin').get(sphereId).get('location')interface NewsArticle {
id: string
title: string
description: string
content: string
source: string
author?: string
url: string
imageUrl?: string
publishedAt: number // Unix timestamp
category: string
tags: string[]
location?: {
lat: number
lng: number
city?: string
country?: string
distance?: number // Calculated distance from user in km
}
createdAt: number
updatedAt: number
}interface UserInterests {
categories: string[] // Selected categories
tags: string[] // Custom tags
keywords: string[] // Search keywords
}interface UserLocation {
lat: number
lng: number
radius: number // Search radius in km
city?: string
country?: string
}The plugin exposes the following components via Module Federation:
./NewsView: Main news feed component./Main: Plugin main component./Sidebar: Settings and navigation sidebar
- ✅ Architecture documentation
- ✅ Design system & style guide
- ✅ Developer onboarding guide
- ✅ Performance strategy
- ✅ Gun.js schema design
- ⏳ Main layout integration
- ⏳ User profile editing
- ⏳ Notification system
- ⏳ Sample data generator
- Phase 3: Data & Intelligence (Week 5)
- Phase 4: Polish & Production (Week 6-7)
- Phase 5: Launch & Growth (Week 8+)
See Roadmap for full timeline.
- Node.js 20+
- npm (or pnpm)
- Git
- VS Code (recommended) with Volar extension
# 1. Install dependencies
npm install
# 2. Start development server
npm run dev
# 3. Open browser → http://localhost:3007# Development
npm run dev # Start dev server (http://localhost:3007)
# Build
npm run build # Production build
npm run preview # Preview production build
# Quality
npm run type-check # TypeScript type checking
npm run lint # ESLint + auto-fix
npm run test # Run tests (Vitest)
npm run test:e2e # E2E tests (Playwright)- Install dependencies:
npm install - Start dev server:
npm run dev - Open browser: http://localhost:3007
- Add sample data: See QUICKSTART.md
- Read docs: Start with Developer Guide
📖 Full guide: Developer Guide
// In TopLocs host application
import NewsView from 'news-plugin/NewsView'
import NewsSidebar from 'news-plugin/Sidebar'
// Use in your component
<NewsView :sphereId="currentSphereId" />
<NewsSidebar :sphereId="currentSphereId" />The useNews composable provides filtering capabilities:
import { useNews } from '@/composables/useNews'
const {
articles, // Paginated & filtered articles
filters, // Current filter settings
saveInterests, // Save user interests
saveLocation, // Save user location
loadMore // Load more articles (infinite scroll)
} = useNews(sphereId)
// Save interests
saveInterests({
categories: ['Technology', 'Science'],
tags: ['ai', 'machine-learning'],
keywords: ['innovation']
})
// Save location
saveLocation({
lat: 51.5074,
lng: -0.1278,
radius: 50,
city: 'London',
country: 'UK'
})Users can configure three types of interests:
- Categories: Predefined news categories with toggle selection
- Tags: Custom hashtags for specific topics
- Keywords: Free-form keywords for content matching
The plugin uses the Haversine formula to calculate distances between user location and article locations:
function calculateDistance(lat1, lng1, lat2, lng2): number {
const R = 6371 // Earth's radius in km
// ... Haversine calculation
return distance
}Articles are sorted by:
- Distance (closest first) if location filter is active
- Published date (newest first)
Uses Intersection Observer API for efficient infinite scrolling:
const observer = new IntersectionObserver((entries) => {
if (entry.isIntersecting && hasMore && !loading) {
loadMore()
}
}, {
rootMargin: '200px', // Trigger 200px before reaching bottom
threshold: 0.1
})- Integration with real news APIs (NewsAPI, Google News, etc.)
- Article bookmarking and saving
- Share articles with other users
- Push notifications for breaking news
- Article commenting and discussions
- Source credibility ratings
- Multi-language support
- Dark mode toggle
- Export reading history
- RSS feed integration
Contributions welcome! Areas of focus:
- News API integrations
- UI/UX improvements
- Performance optimizations
- Additional filtering options
- Accessibility improvements
MIT License - See the main TopLocs project for details.
This project is developed with:
- Product Lead: Reza
- AI Architecture: GPT-5 (strategic direction)
- AI Development: Claude (technical implementation)
Product Vision (Reza + GPT-5)
↓
Technical Architecture (Claude + GPT-5 Review)
↓
Implementation (Claude)
↓
Review & Iteration (All)
- Major decisions: Reviewed with GPT-5
- Technical changes: Documented by Claude
- Product pivots: Reza + GPT-5
- Code reviews: Before merge
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: docs/
- Email: support@toplocs.com
- ✅ Complete foundation documentation
- ⏳ Optimize Gun.js data structure
- ⏳ Build main 3-column layout
- ⏳ Generate sample data (100+ users)
- Complete all core features
- Implement notification system
- Add user profile editing
- Deploy beta version
- Launch to 1,000+ users
- Gather feedback & iterate
- Add AI recommendations
- Mobile app (React Native)
Full details: Roadmap v2.0
"We're not building just another news app—we're creating a human-centered platform where local information meets genuine connection. Fast like TikTok, authentic like BeReal, intelligent like Instagram, but decentralized and real."
Let's make it happen. 🚀
Version: 2.0.0 Status: Foundation Complete → Implementation Phase Last Updated: 2025-10-06