System Overview
Linkr is built as a three-tier distributed system connecting users, the central network, and community-operated hotspots. This document describes the high-level architecture and how the components interact.The Three-Lane Architecture
Component Details
User Lane
The user lane encompasses all client applications that interact with the Linkr Network.Mobile Applications
Native iOS and Android apps provide the primary interface for both users and operators:- Discovery: Browse the coverage map, search for hotspots
- Connection: Authenticate and connect to hotspots
- Operator Dashboard: Manage hotspots, view metrics, track rewards
- Account Management: Profile, settings, notifications
Web Application
Browser-based access to core functionality:- Coverage Map: Full-featured map with filtering and search
- Dashboard: Detailed analytics for operators
- Account Settings: Profile and configuration management
- Admin Tools: For internal operations (not public)
Third-party Clients
External applications built on the Linkr API:- Coverage data integrations
- Automated hotspot management
- Analytics and monitoring tools
Linkr Network Lane
The central coordination layer that processes all requests and maintains system state.API Gateway
All client requests pass through the API Gateway:| Function | Description |
|---|---|
| Authentication | Validates JWT tokens, API keys |
| Rate Limiting | Prevents abuse, ensures fair access |
| Request Routing | Directs requests to appropriate services |
| Response Caching | Caches frequently-requested data |
| Logging | Records all requests for audit and debugging |
Hotspot Registry
Maintains the authoritative record of all hotspots:- Registration and verification workflow
- Hotspot metadata (location, configuration, status)
- Operator associations and permissions
- Device linking and management
Coverage Engine
Computes and maintains the global coverage map:- Aggregates location data from all hotspots
- Calculates coverage estimates based on device specs and telemetry
- Generates map tiles for client rendering
- Updates coverage data in near-real-time
Rewards Engine
Handles all rewards-related logic:- Issues proof-of-availability challenges
- Validates challenge responses
- Calculates rewards based on performance metrics
- Maintains reward balances and settlement records
Session Manager
Tracks user connections to hotspots:- Issues session tokens for authenticated connections
- Monitors active sessions
- Records session metrics (duration, bandwidth)
- Handles session termination and cleanup
Telemetry Processor
Background service that ingests and processes data from hotspots:- Receives heartbeats and telemetry reports
- Validates and normalizes incoming data
- Updates hotspot status based on telemetry
- Feeds data to other services (Coverage, Rewards)
Hotspot Lane
The distributed network of community-operated hotspots. Each hotspot runs lightweight software (or uses standard protocols) to:- Respond to health checks and challenges
- Report telemetry data periodically
- Authenticate connecting users
- Apply access policies (bandwidth limits, session duration)
Core Flows
Hotspot Registration Flow
User Connection Flow
Rewards Loop
Infrastructure
Deployment
The Linkr Network runs on cloud infrastructure with:- Multiple regions: Services deployed across geographic regions for latency and redundancy
- Auto-scaling: Capacity adjusts based on load
- Database replication: Primary-replica setup for critical data stores
- CDN: Static assets and map tiles served from edge locations
Data Stores
| Store | Purpose | Type |
|---|---|---|
| Primary DB | Hotspots, users, sessions | PostgreSQL |
| Time-series DB | Telemetry, metrics | TimescaleDB |
| Cache | Sessions, rate limits, hot data | Redis |
| Object Storage | Map tiles, static assets | S3-compatible |
| Search | Hotspot discovery, geospatial | Elasticsearch |
Reliability
- Health monitoring: All services report health status
- Alerting: Automated alerts for anomalies and failures
- Incident response: On-call rotation for critical issues
- Disaster recovery: Regular backups, tested restore procedures