Blurcle 🔵

A comprehensive audience analytics platform for Bluesky creators and professionals. Built on the AT Protocol, Blurcle analyzes your engagement metrics, interaction patterns, and social network to help you understand and grow your Bluesky presence.

✨ Features

🔐 Authentication (Optional)

• Sign in with Bluesky: Use your Bluesky credentials to unlock enhanced features
• Secure Sessions: Encrypted session tokens stored in HTTP-only cookies
• Quick Access: "My Analytics" button for instant access to your own stats
• Privacy Protected: Credentials sent directly to Bluesky, never stored by Blurcle

📊 Engagement Analytics

• Total Metrics: Track your total likes, reposts, replies, and quotes
• Averages: See your average engagement per post
• Engagement Rate: Understand your overall interaction rate

🔍 Network Insights

• Top Interactions: Discover your most mentioned connections
• Interactive Circle: Beautiful D3.js visualization of your network
• Force-Directed Graph: Drag and explore your connection network
• Network Size: Track followers, following, and mutual relationships
• Reach Estimation: Get an estimate of your potential audience size

⏰ Posting Patterns

• Hourly Activity: Visualize which hours of the day you're most active
• Daily Patterns: See your posting frequency across the week
• Top Posts: Identify your best-performing content

🎨 Beautiful Design

• Editorial-inspired design with a distinctive aesthetic
• Smooth animations and micro-interactions
• Fully responsive mobile experience
• Dark theme optimized for readability

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or pnpm

Installation

# Clone the repository
git clone <your-repo-url>
cd blurcle

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env

# Generate a secure session secret (required for auth)
# On Unix/Mac:
openssl rand -base64 32

# Add this to your .env file:
# NUXT_SESSION_PASSWORD=<your-generated-secret>

# Start development server
npm run dev

The app will be available at http://localhost:3000

Building for Production

# Build the application
npm run build

# Preview production build
npm run preview

🔧 How It Works

AT Protocol Integration

Bluesky Circle uses the official @atproto/api package to interact with Bluesky's decentralized AT Protocol:

1. Profile Fetching: Retrieves public profile information
2. Feed Analysis: Analyzes up to 100 recent posts
3. Engagement Calculation: Computes engagement metrics from post data
4. Network Analysis: Examines mentions and interactions
5. Pattern Recognition: Identifies posting patterns by time and day

Privacy-First Approach

• Public Data Only: Only accesses publicly available information
• No Authentication Required: Doesn't need your Bluesky credentials
• Local Caching: Results cached for 30 minutes to minimize API calls
• No Data Storage: Analytics are temporary and not permanently stored

Caching System

The app uses Nuxt's built-in storage system to cache analytics:

• Cache duration: 30 minutes
• Storage location: ./.data/cache
• Automatic expiration
• Reduces API load

📁 Project Structure

blurcle/
├── app.vue                    # Main application component
├── nuxt.config.ts            # Nuxt configuration
├── package.json              # Dependencies
├── tsconfig.json             # TypeScript configuration
│
├── assets/
│   └── css/
│       └── main.css          # Global styles with editorial design
│
├── components/
│   ├── ProfileHeader.vue     # Profile information display
│   ├── EngagementMetrics.vue # Engagement statistics
│   ├── TopInteractions.vue   # Top connections list
│   ├── PostingPatterns.vue   # Activity patterns visualization
│   └── AudienceInsights.vue  # Reach and network insights
│
├── composables/
│   └── useBlueskyAnalytics.ts # Analytics state management
│
├── server/
│   └── api/
│       └── analytics.get.ts   # AT Protocol integration endpoint
│
└── types/
    └── analytics.ts           # TypeScript type definitions

🎨 Design Philosophy

Blurcle features a distinctive editorial aesthetic inspired by premium publications:

• Typography: Newsreader serif for elegance, JetBrains Mono for code
• Color Palette: Deep navy blues with gold accents
• Layout: Asymmetric, magazine-style composition
• Effects: Atmospheric backgrounds, smooth animations, interactive D3 visualizations
• Motion: Smooth animations with staggered reveals

This design deliberately avoids generic "AI slop" aesthetics in favor of a memorable, refined visual identity.

🔒 Privacy & Security

What We Access

• Public profile information (avatar, bio, follower counts)
• Public posts and their engagement metrics
• Public interaction patterns (mentions in posts)

What We DON'T Access

• Private/protected accounts
• Direct messages
• Private lists or blocks
• Login credentials
• Any non-public data

Data Handling

• All data is fetched in real-time from Bluesky's public API
• Results are cached temporarily (30 minutes) for performance
• No permanent database storage
• No user tracking or analytics collection

🛠️ Technical Stack

• Framework: Nuxt 4 - The Intuitive Vue Framework
• Authentication: H3 Sessions - Secure encrypted session management
• AT Protocol: @atproto/api - Official Bluesky API
• TypeScript: Full type safety throughout the application
• Storage: Nitro's built-in filesystem caching
• Styling: Vanilla CSS with CSS custom properties

📊 Analytics Metrics Explained

Engagement Rate

Total interactions (likes + reposts + replies + quotes) divided by the number of posts analyzed. Higher rates indicate more engaging content.

Reach Estimate

A heuristic calculation based on:

• Follower count
• Engagement rate
• A multiplier to account for reposts and algorithmic discovery

Formula: followers × (engagement_rate / 100) × 2.5

Top Interactions

Users who are most frequently mentioned in your posts, ranked by frequency. Helps identify your key collaborators and conversation partners.

🚧 Limitations & Known Issues

• Analysis Depth: Currently analyzes up to 100 most recent posts
• Mutual Followers: Not yet implemented (requires fetching all follows/followers)
• Historical Trends: No time-series tracking across sessions
• Rate Limiting: Subject to Bluesky's API rate limits

🗺️ Roadmap

Future enhancements being considered:

• Export analytics as PDF/image reports
• Compare multiple profiles side-by-side
• Historical trend tracking with data persistence
• Advanced network graph visualization with D3.js
• Content analysis (hashtag trends, media types)
• Scheduled reporting and email notifications
• API for programmatic access

🤝 Contributing

Contributions are welcome! This is a personal project, but I'm open to:

• Bug reports and fixes
• Feature suggestions
• Performance improvements
• Documentation updates

Please ensure any PRs maintain:

• TypeScript type safety
• Accessibility standards (WCAG compliance)
• The existing design aesthetic
• Privacy-first principles

📝 License

MIT License - feel free to use this project for personal or commercial purposes.

🙏 Acknowledgments

• Built with Nuxt
• Powered by AT Protocol
• Inspired by analytics tools like Skircle
• Typography: Newsreader by Production Type

📧 Contact

For questions, suggestions, or issues:

• Open an issue on GitHub
• Find me on Bluesky: [your-handle]

---

Note: This is an independent project and is not officially affiliated with Bluesky or the AT Protocol team.