# Groar — Full Documentation

> Turn your metrics into shareable visuals in 10 seconds

Groar is a web application that transforms social media analytics and business metrics into beautiful, shareable images. It's built for creators, founders, indie hackers, and makers who build in public and want to showcase their growth without design skills.

## Core Product

Groar solves a simple problem: turning raw analytics data into visual content that drives engagement on social media. Users select a template, enter or auto-fill their metrics, customize the appearance, and export a high-quality image ready to share.

The entire flow takes about 10 seconds. No Canva. No design skills. No complicated tools.

---

## Visual Editor

### Templates

Groar offers 4 templates:

1. **Metrics** (free) — The core template. Display 1-5 key performance indicators with values, optional deltas (gain/loss), and a customizable heading. Perfect for weekly or monthly growth recaps.

2. **Milestone** (Pro) — Celebrate achievements like hitting 10K followers or $1K MRR. Features large centered number with emoji decorations above and below. Customizable emoji selection.

3. **Progress** (Pro) — Show progress toward a goal with a visual progress bar. Set current value, target, and watch the bar fill. Great for fundraising, follower goals, or revenue targets.

4. **List** (Pro) — Announce features, updates, or achievements as a bullet-point list. Supports 1-10 items with custom text.

### Supported Metrics (34+ types)

**X (Twitter)**:
- followers, verified followers, followings
- posts, impressions
- replies, likes, reposts, bookmarks
- engagement rate, engagement (total interactions)
- profile visits

**SaaS / Business**:
- MRR (Monthly Recurring Revenue)
- ARR (Annual Recurring Revenue)
- revenue (total)
- valuation
- churn rate, LTV (lifetime value)
- new customers, total customers
- sales, visitors
- domain rating

**GitHub**:
- stars, commits, forks
- contributors
- PRs closed, issues resolved

**Reddit**:
- karma, upvotes, upvote ratio

**Other**:
- builders (community metric)

Each metric has a dedicated icon and supports custom prefixes (e.g., "+", "$"). Currency metrics (MRR, ARR, revenue, LTV) are automatically formatted with "$" prefix. Metrics can be reordered via drag-and-drop.

### Auto-Fill

When a user connects their X account, metrics like followers, followings, and posts are automatically populated in the editor. If the user has TrustMRR data, MRR, ARR (calculated as MRR x 12), and total revenue are also auto-filled.

Auto-filled metrics show a green dot indicator. If the user manually changes the value, the indicator turns grey and becomes clickable to restore the auto-fetched value.

### Headings & Date Formatting

- **Period mode**: "Week 1", "Week 1-4", "Month 3", etc.
- **Last N**: "Last 7 days", "Last 4 weeks", "Last 3 months"
- **Custom date range**: calendar picker for specific date ranges
- **Quote/headline**: free-text heading for announcements
- Auto-formatted labels based on selected period

### Visual Customization

**Backgrounds**:
- 25+ curated backgrounds across categories: dark, noisy, premium, nature, urban
- Solid color option with full color picker
- Free users: 5 backgrounds
- Pro users: all backgrounds

**Fonts** (6 families):
- Free: DM Mono, Bricolage Grotesque
- Pro: Inter, Space Grotesk, Averia Serif Libre, DM Serif Display

**Other**:
- Custom text color picker
- Custom branding with logo upload (Pro, max 5 logos)
- Logo positioning: left, center, or right
- Logo size adjustment (20-60px)

### Aspect Ratios

- **Post** (16:9, 1200x675px) — free, optimized for X/Twitter posts
- **Square** (1:1, 1200x1200px) — Pro, for Instagram or general use
- **Banner** (3:1, 1500x500px) — Pro, for X/Twitter headers or profile banners

### Export & Sharing

- High-quality PNG export (3x pixel ratio)
- Automatic download + auto-copy to clipboard
- Direct "Share to X" button with pre-filled tweet intent
- Export history with ability to re-import and edit past exports (Pro)
- Watermark on free exports, removed for Pro
- 5-second cooldown between exports
- Keyboard shortcut: Cmd+S to export, Cmd+Z / Cmd+Shift+Z for undo/redo

---

## Dashboard

### Main Dashboard
- Current plan status and billing period
- Total exports counter
- Connected accounts (X, Google)
- Weekly export limit tracker (free users)
- Login streak counter (Pro users)
- Recent exports gallery (last 4)

### Analytics Dashboard (Pro)
**X Analytics**:
- Daily snapshots of followers, following, tweet count
- 30-day trends with deltas
- Impressions, likes, reposts, replies, bookmarks
- Average engagement rate calculation
- Connected X account analytics
- Manual refresh (3x/day) + automatic daily cron fetch (4x/day)

**Revenue Analytics (via TrustMRR)**:
- MRR with daily delta tracking
- Active subscriptions count
- Revenue last 30 days
- Total revenue
- Growth rate (30d)
- Expandable history rows grouped by source (X metrics / Revenue)
- Automatic daily fetch for all Pro users
- Data synced from TrustMRR API using the user's X handle

### Export History
- Browse all past exports with infinite scroll
- Re-import any export to edit and re-export
- 12 exports loaded per batch

### Connections
- Connect X (Twitter) account for analytics auto-fetch
- Connect your X account for analytics auto-fetch
- Account management and disconnection

### Leaderboard (https://groar.app/public)
Community gamification system:

**Point System**:
- +20 points for daily login
- +10 points per export (max 5/day = 50 points)
- +50 points for using a new template
- +20 points for using a new background

**Badges** (11 total):
- First Roar — first export
- Template Explorer — use all templates
- Background Hunter — use 10+ backgrounds
- Week Warrior — 7-day login streak
- Month Master — 30-day login streak
- Legend — 100-day login streak
- Rising Star — reach top 10
- GROAR Elite — reach top 3
- Night Owl — export between 12am-5am
- Early Bird — export between 5am-8am
- King of the Jungle — reach rank #1

**Display**: medals (gold, silver, bronze) for top 3, ranking, avatar, username, total score

### Notifications
- Milestone achievement alerts (e.g., "You hit 10,000 followers!")
- Badge earned notifications
- System announcements
- Direct links to create milestone visuals from notifications

### Settings
- Profile information display
- Email preferences: milestone emails, trial reminders, product updates

### Plan Management
- Current plan display with status
- Upgrade paths (free → Pro monthly, monthly → lifetime)
- Early adopter spot tracking with tier progress
- Billing portal access (Creem or Polar)

---

## Pricing

### Free Tier
- Full editor access (metrics template only)
- 1 export per week
- 5 backgrounds
- Watermark on exports
- Post aspect ratio (16:9) only
- 2 font families
- No account connections
- No analytics dashboard

### Pro Monthly — $5/month
- Unlimited exports
- All 25+ backgrounds
- No watermark
- All 4 templates
- All 3 aspect ratios
- All 6 font families
- Custom branding with logo
- Connect your X account
- Full analytics dashboard
- Export history with re-import

### Pro Lifetime — Early Adopter Pricing
Same features as Pro Monthly, forever. Price increases as spots fill:
- Tier 1: $9 (15 spots)
- Tier 2: $12 (20 spots)
- Tier 3: $15 (35 spots)
- Tier 4: $19 (50 spots)
- Tier 5: $24 (80 spots)
- Final: $29 (unlimited)

Monthly pricing also increases with lifetime tiers: $5 → $6 → $7 → $8 → $9.

### Trial
- 3-day free Pro trial
- No credit card required
- Full Pro access during trial
- Email reminders before expiration

---

## API

Groar offers a REST API to generate card images programmatically. Users design their card visually in the editor, save it as an API template, then call the endpoint with dynamic values to get a PNG image back.

### How It Works

1. Design a card in the visual editor
2. Save it as an API template (stores layout, background, font, colors, metric types)
3. Call the API endpoint with your API key and dynamic values
4. Receive a PNG image

### Endpoint

`GET /api/card`

**Required parameters:**
- `key` — Your API key (generated in the dashboard)
- `s` — Base64-encoded template settings (generated when saving a template)

**Dynamic value parameters (depend on template type):**
- **Metrics template**: `v1`, `v2`, `v3`... — values for each metric slot. Prefix with `+` for growth indicator (e.g. `v1=+250`)
- **Milestone template**: `v1` — the milestone value
- **Progress template**: `v1` — current value, `goal` — target value
- **Announcement template**: `a1`, `a2`... — text for each item, `e1`, `e2`... — emoji for each item

**Optional override parameters:**
- `bg` — Background preset ID or "random"
- `font` — bricolage | inter | space-grotesk | dm-mono | averia-serif-libre | dm-serif-display | random
- `color` — Hex text color (e.g. `%23ffffff`)
- `size` — post | square | banner
- `handle` — Display name shown top-left
- `heading` — Custom heading text
- `date` — Date label shown top-right
- `layout` — stack | columns (metrics template only)
- `emoji` — Emoji character or "random" (milestone template only)
- `emojiCount` — 0-10 (milestone template only)
- `watermark` — true | false (paid tiers only, off by default)
- `branding` — true | false (show/hide logo)

### API Tiers & Pricing

| Tier | Monthly Limit | Rate Limit | Price | Watermark |
|------|--------------|------------|-------|-----------|
| Free | 500 | 30 req/min | Included with Pro | Forced |
| Growth | 5,000 | 30 req/min | $9/mo | Off (opt-in) |
| Scale | 50,000 | 50 req/min | $29/mo | Off (opt-in) |
| Enterprise | 500,000+ | 100 req/min | Custom | Off (opt-in) |

- All Pro users (monthly or lifetime) get the Free API tier (500 calls/month) included
- 20% grace buffer on all limits before hard block
- Email notifications at 80%, 100%, and 120% usage
- API keys can be created, renamed, revoked, and regenerated from the dashboard

### Use Cases
- Automated social media posts with live stats
- Embed dynamic stats cards in GitHub READEs or documentation
- Dashboard widgets and reports
- Scheduled milestone announcements
- Integration with AI agents and automation tools

---

## Integrations

### X (Twitter)
- OAuth authentication
- Automated analytics fetch (followers, tweets, impressions, engagement)
- Cron job: 4 fetches/day (1am, 7am, 1pm, 7pm UTC)
- Manual refresh: up to 3x/day
- X account analytics integration

### TrustMRR
- Revenue data integration via API
- Fetches MRR, revenue, customers, subscriptions, growth rate
- Auto-fill MRR, ARR, and Revenue in the editor
- Daily automated fetch for all Pro users (2am UTC)
- Rate-limited: 4-second delay between users (respects 20 req/min API limit)

### Google
- OAuth authentication (sign-in only)

### Payments
- **Creem** (primary): checkout, subscriptions, webhooks, customer portal
- **Polar** (legacy): maintained for existing subscribers, fallback billing portal

### PostHog
- Event tracking: exports, checkouts, subscription changes
- User identification and properties

---

## Technical Stack

- **Framework**: Next.js 14+ (App Router)
- **Language**: TypeScript
- **Auth**: Better Auth (Google + Twitter OAuth)
- **Database**: PostgreSQL (Neon)
- **Payments**: Creem SDK + Polar SDK
- **Background Jobs**: Inngest (cron functions for analytics, trial reminders, TrustMRR)
- **Analytics**: PostHog
- **Image Export**: html-to-image with SVG foreignObject
- **UI**: Tailwind CSS, Radix UI, shadcn/ui components
- **Icons**: Hugeicons
- **Drag & Drop**: dnd-kit
- **Hosting**: Vercel

---

## Milestone Templates

Groar offers 180 programmatic SEO pages for milestone celebrations (30 base + 150 platform-specific). Each page targets a specific milestone value, category, and optionally a platform, and includes:

- SEO-optimized title, description, and keywords
- A card preview with a unique background
- Tips for crafting the milestone post (platform-specific when applicable)
- 3 ready-to-copy post ideas adapted to the platform's tone
- FAQ section with structured data (JSON-LD FAQPage)
- Article JSON-LD schema
- Internal linking (prev/next, cross-category, cross-platform)

### Categories & Values

**Followers**: 100, 500, 1K, 2K, 5K, 10K, 25K, 50K, 100K
- URLs: https://groar.app/milestone/100-followers through https://groar.app/milestone/100k-followers

**MRR** (Monthly Recurring Revenue): $100, $500, $1K, $5K, $10K, $50K, $100K
- URLs: https://groar.app/milestone/100-mrr through https://groar.app/milestone/100k-mrr

**Revenue** (Total Revenue): $1K, $10K, $100K, $1M
- URLs: https://groar.app/milestone/1k-revenue through https://groar.app/milestone/1m-revenue

**GitHub Stars**: 100, 500, 1K, 5K, 10K
- URLs: https://groar.app/milestone/100-github-stars through https://groar.app/milestone/10k-github-stars

**Customers**: 10, 50, 100, 500, 1K
- URLs: https://groar.app/milestone/10-customers through https://groar.app/milestone/1k-customers

### Platform-Specific Pages

Every milestone above is also available with platform-specific content for 5 platforms:
- **X (Twitter)**: tips for X's algorithm, build-in-public style captions
- **LinkedIn**: professional storytelling format, B2B tips
- **Instagram**: carousel and Reel tips, visual-first captions
- **TikTok**: authentic video content tips, casual tone captions
- **Bluesky**: open web community tips, genuine conversation format

URL pattern: https://groar.app/milestone/{milestone}-on-{platform}
Examples: https://groar.app/milestone/1k-followers-on-linkedin, https://groar.app/milestone/10k-mrr-on-tiktok

**Hub page**: https://groar.app/milestone — lists all milestones grouped by category and platform.

---

## Rewards Program

Groar offers a rewards program for users who share and promote the tool on X (Twitter).

### 1. Affiliate Program
- 30% commission on every sale (monthly and lifetime plans)
- Apply by emailing yannick@groar.app

### 2. Repost Reward
- Create a visual with a Pro account or free trial
- Post it on X and tag @yannick_ferire
- Guaranteed repost, no conditions, no minimum followers

### 3. Dedicated Post Rewards
Write a post on X about your experience with GROAR and how it helps boost engagement. Tag @yannick_ferire. Rewards scale with reach:

- **Any dedicated post**: repost to @yannick_ferire's audience
- **5,000+ impressions**: full refund (lifetime users) or 1 month free (monthly users)
- **50,000+ impressions**: $50 cash reward on top

**How to claim**: DM @yannick_ferire with a screenshot once you hit the impressions threshold. Verified and paid within 48h.

Page: https://groar.app/rewards

---

## Links

- Website: https://groar.app
- API: https://groar.app/dashboard/api
- Milestones: https://groar.app/milestone
- Rewards: https://groar.app/rewards
- Compare: https://groar.app/vs
- Comparisons: https://groar.app/vs/screenshots, https://groar.app/vs/canva, https://groar.app/vs/piktochart, https://groar.app/vs/image-charts, https://groar.app/vs/spreadsheets, https://groar.app/vs/build-in-public
- Leaderboard: https://groar.app/public
- Creator: Yannick Ferire
- X: https://x.com/yannick_ferire