TopLocs Ecosystem Overview
This document provides a high-level overview of the entire TopLocs ecosystem, including all repositories and their relationships.
Repository Overview
TopLocs is organized as a collection of independent repositories that work together to create a decentralized community platform:
toplocs/ (workspace managed by toplocs-workspace repository)
├── 📋 Workspace Management
│ ├── docs/ # 📚 Centralized documentation hub
│ ├── CLAUDE.md # 🤖 AI development context
│ └── automation/ # 🔄 GitHub Actions workflows
├── 🏛️ Core Platform
│ ├── tribelike/ # Main community platform & plugin host
│ ├── locations/ # Location-based mobile app (Ionic)
│ └── tribelike.wiki/ # Documentation wiki
├── 🔌 Plugin Ecosystem
│ ├── event-plugin/ # Plugin: Real-time chat & event management
│ ├── wiki-plugin/ # Plugin: Knowledge sharing & documentation
│ ├── location-plugin/ # Plugin: Location management & mapping
│ └── link-plugin/ # Plugin: Link sharing & bookmarking
└── 🛠️ Development Tools
└── demo-plugin/ # Plugin development framework
Core Architecture
TopLocs (Topic + Location) is a decentralized peer-to-peer community platform built on Gun.js:
Key Principles
- No Central Authority: No single server controls the data
- User-Owned Data: Users control their data through cryptographic keys
- Offline-First: Works without internet connectivity
- Real-Time Sync: Changes propagate instantly between connected peers
- Plugin-Based: Extensible through Module Federation
Technology Stack
- Frontend: Vue.js 3 + TypeScript + Gun.js
- Backend: Minimal Express relay (Gun.js only)
- Authentication: WebAuthn/Passkeys + Gun SEA
- Plugins: Module Federation for dynamic loading
- Mobile: Ionic + Capacitor for native apps
Repository Categories
🏛️ Production Repositories
These are the main repositories for the production platform:
- tribelike - Core community platform and plugin host
- locations - Mobile application for location-based interactions
- tribelike.wiki - Project documentation and specifications
🔌 Plugin Repositories
All repositories ending in -plugin
are plugins for the platform:
- event-plugin - Real-time chat and event management
- wiki-plugin - Collaborative knowledge sharing
- location-plugin - Location management and mapping
- link-plugin - Link sharing and bookmarking
🛠️ Development Tools
- demo-plugin - Template and framework for plugin development
Plugin Architecture
The platform uses Module Federation to load plugins dynamically:
// Plugin configuration
federation({
name: 'your-plugin',
filename: 'plugin.js',
exposes: {
'./Main': './src/components/Main.vue',
'./Settings': './src/components/Settings.vue'
},
shared: ['vue', 'tailwindcss']
})
Plugins integrate through:
- Gun.js shared data layer - All plugins access the same decentralized database
- Component federation - Runtime loading without rebuilding core
- Standard interfaces - Main, Settings, Sidebar components
- Universal relations - Connect any entities through typed relationships
Data Architecture
Gun.js Namespaces
gun.get('credentials').get(email) // Authentication
gun.get('profile/{id}') // User profiles
gun.get('location/{id}') // Geographic locations
gun.get('topic/{id}/{space}') // Topics (local/global)
gun.get('sphere/{id}/{space}') // Community spheres
gun.get('relations/{from}/{type}/{to}') // Universal relations
gun.get('plugins') // Plugin registry
Relationship System
- Profile-Interest:
favorite
,doing
,expert
,learning
,curious
- Profile-Location:
living
,working
,traveling
,visiting
,current
- Profile-Profile:
following
,friend
,family
,partner
- Content relationships: Categories, tags, hierarchies
Development Workflow
1. Core Platform Development
cd tribelike
pnpm install
pnpm dev # Starts client and server
2. Plugin Development
cd demo-plugin
pnpm install
pnpm dev # Starts plugin development environment
3. Mobile Development
cd locations
npm install
npm run dev # Web development
ionic cap run ios # Native iOS
Repository Relationships
Data Flow
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Plugins │◄──►│ tribelike │◄──►│ locations │
│ (federated) │ │ (core) │ │ (mobile) │
└─────────────┘ └─────────────┘ └─────────────┘
▲ ▲ ▲
│ │ │
└────────────────────┼────────────────────┘
▼
┌─────────────┐
│ Gun.js │
│ (P2P data) │
└─────────────┘
Development Dependencies
- Plugins depend on tribelike for core types and components
- demo-plugin provides templates for all plugin development
- locations is independent but may integrate with core platform
Getting Started
For Core Development
- Start with tribelike - the main platform
- Follow
tribelike/CLAUDE.md
for detailed guidance - Use
tribelike/docs/
for comprehensive documentation
For Plugin Development
- Use demo-plugin as your starting template
- Follow the plugin development guide in
tribelike/docs/plugin-development.md
- Test integration with the demo framework
For Mobile Development
- Work in locations repository
- Use Ionic/Capacitor for cross-platform development
- Consider integration points with the core platform
Documentation Structure
Central Documentation
- tribelike/docs/ - Complete ecosystem documentation
- tribelike/CLAUDE.md - AI development context
- tribelike/README.md - Core platform overview
Repository-Specific Documentation
- Each repository has its own README.md
- Plugin repositories link back to central docs
- PoC repositories document experimental findings
Maintenance Strategy
Documentation Updates
- Primary: Update tribelike/docs/ for ecosystem changes
- Secondary: Update individual repository READMEs
- Links: Maintain cross-references between repositories
Version Management
- Each repository is independently versioned
- Plugin compatibility is managed through shared interfaces
- Core platform changes may require plugin updates
Contributing
- Understand the ecosystem - Review this document and tribelike/docs/
- Choose your area - Core platform, plugins, mobile, or research
- Follow the patterns - Use existing repositories as guides
- Test thoroughly - Use appropriate development environments
- Document changes - Update relevant documentation
This ecosystem approach allows for:
- Independent development of different components
- Flexible deployment of only needed parts
- Experimental features without affecting core stability
- Community contributions through the plugin system