# GIGA.FORA - Complete Documentation

> GIGA.FORA is an open, anonymous forum platform where ideas connect. No login required. Users can share thoughts, spark discussions, and discover connections between ideas through linked posts and trending tags.

## About GIGA.FORA

GIGA.FORA is a modern web forum built for the new era of open discourse. The platform emphasizes:

1. **Accessibility**: No barriers to entry - start posting immediately
2. **Privacy**: Anonymous by design with auto-generated pseudonyms
3. **Connection**: Link posts together to show relationships between ideas
4. **Discovery**: Trending tags and multiple sort options help surface relevant content

### Why GIGA.FORA?

Traditional forums require registration, email verification, and profile setup. GIGA.FORA removes these friction points while maintaining quality through community moderation (voting and reporting).

## Features

### Posting
- Create posts with title (max 75 chars), body (max 2500 chars), and tags (up to 5)
- Rich text editing with Quill editor
- Markdown support for formatting
- Link to other posts to create idea connections

### Engagement
- Upvote/downvote posts and comments
- Threaded comments on posts
- Report inappropriate content
- Share posts via direct links

### Discovery
- **Hot**: Algorithmically ranked by engagement and recency
- **New**: Chronological, newest first
- **Top**: Highest voted posts
- **Tags**: Filter by topic tags
- **Search**: Full-text search across posts

### User Identity
- Auto-generated anonymous usernames stored in browser
- Consistent identity across sessions (same device)
- No tracking or personal data collection

### Multi-tenant Comments Product
- Hosted embed for external blogs via `https://giga.mobile/embed.js`
- Tenant-isolated sites, domains, threads, and billing plans
- **Direct-render mode** (default): Shadow DOM, no iframe, zero layout shift
- **Iframe mode** (legacy): available via `data-mode="iframe"`
- **CLI quickstart**: `npx create-fora` — anonymous, no auth, ~15 seconds, outputs framework snippet
- **Framework adapters**: Astro, Hugo, Jekyll, 11ty, Hakyll, HTML
- **SSR-safe comment count**: `GET /api/embed/count` — use at build time
- **JSON-LD structured data**: `GET /api/embed/structured-data` — DiscussionForumPosting schema
- **Webhooks**: `comment.created` events with HMAC-SHA256 signatures
- **Public JS API**: `Fora.mount()`, `Fora.update()`, `Fora.unmount()`, `Fora.count()`
- Plan packaging:
  - Free: core comments, comment voting, reply threads, moderation report actions
  - Pro ($49/mo): adds post actions (vote/reactions/share) + advanced branding controls + full analytics
  - Business ($199/mo): adds team/admin controls, higher quotas, priority support
  - Free add-ons: `feature_pack` (premium interactions) and `analytics_pack` (full analytics)
- Base plans are account-scoped; sites inherit account plan limits and entitlements.
- Publisher entry points:
  - Dashboard: `/publishers`
  - Terms: `/terms/`
  - Privacy: `/privacy/`
  - Sitemap: `/sitemap.xml`
  - Robots: `/robots.txt`
  - AI docs: `/ai`
  - Agent install guide: `/ai/comments-install`
  - Agent OpenAPI spec: `/openapi-agent.json`

### Framework Adapters

| Framework | Package | Install |
|-----------|---------|---------|
| Astro | `astro-fora` | `npm install astro-fora` |
| Eleventy (11ty) | `fora-eleventy-plugin` | `npm install fora-eleventy-plugin` |
| Jekyll | `jekyll-fora` | `gem install jekyll-fora` |
| Hakyll | template + module | see `/docs/hakyll` |
| Any HTML | `<script>` tag | No install needed |

**Plain HTML embed:**
```html
<div id="fora-comments"></div>
<script src="https://giga.mobile/embed.js" data-site-key="YOUR_KEY"></script>
```

**Astro:**
```astro
---
import { ForaComments } from 'astro-fora';
---
<ForaComments siteKey="YOUR_KEY" />
```

### Embed Data Attributes

| Attribute | Required | Description |
|-----------|----------|-------------|
| `data-site-key` | ✅ | Your Fora site key |
| `data-page-id` | — | Thread identifier (defaults to current path) |
| `data-page-title` | — | Page title |
| `data-theme` | — | `auto`, `light`, `dark` |
| `data-mode` | — | `direct` (default) or `iframe` (legacy) |
| `data-container-id` | — | DOM mount point (default: `giga-fora-comments`) |
| `data-features` | — | Comma-separated feature flags |
| `data-accent` | — | Accent color override |
| `data-bg` | — | Background color override |
| `data-surface` | — | Surface color override |
| `data-text` | — | Text color override |
| `data-font` | — | Font family override |
| `data-radius` | — | Border radius override |

## Technical Architecture

### Frontend
- Pure vanilla JavaScript (no framework dependencies)
- Responsive CSS with dark/light theme support
- Quill rich text editor for post composition
- Turndown for HTML-to-Markdown conversion
- Marked for Markdown-to-HTML rendering

### Backend (Cloudflare Workers)
- Serverless edge computing
- D1 SQLite database for persistence
- RESTful API design
- CORS-enabled for cross-origin requests

### Database Schema
- `posts`: id, title, body, author, tags, votes, created_at
- `comments`: id, post_id, parent_id, body, author, votes, created_at
- `post_links`: source_id, target_id (for linked posts)
- `reports`: id, content_type, content_id, reason, details, created_at
- Multi-tenant and SaaS tables:
  - `sites`, `site_domains`, `threads`
  - `site_billing`, `site_feature_flags`, `site_theme_settings`, `site_usage_daily`, `site_analytics_events`
  - `tenant_users`, `tenant_identities`, `tenant_sessions`, `magic_link_tokens`, `oauth_states`, `site_memberships`, `site_agent_tokens`

## API Reference

Base URL: `https://giga.fora/api/`

### Posts

#### List Posts
```
GET /api/posts?sort=hot&tag=tech&search=query&limit=20&offset=0
```

Response:
```json
{
  "posts": [
    {
      "id": "abc123",
      "title": "Post title",
      "body": "Post content...",
      "author": "AnonymousUser42",
      "tags": ["tech", "ideas"],
      "votes": 15,
      "comment_count": 3,
      "created_at": "2025-01-20T10:30:00Z"
    }
  ],
  "total": 100,
  "has_more": true
}
```

#### Get Single Post
```
GET /api/posts/:id
```

#### Create Post
```
POST /api/posts
Content-Type: application/json

{
  "title": "My Post Title",
  "body": "Post content in markdown",
  "tags": ["tag1", "tag2"],
  "author": "MyUsername",
  "linked_posts": ["other-post-id"]
}
```

#### Vote on Post
```
POST /api/posts/:id/vote
Content-Type: application/json

{
  "direction": 1,  // 1 for upvote, -1 for downvote
  "voter_id": "unique-voter-identifier"
}
```

### Comments

#### Add Comment
```
POST /api/posts/:id/comments
Content-Type: application/json

{
  "body": "Comment text",
  "author": "Username",
  "parent_id": null  // or comment ID for replies
}
```

#### Vote on Comment
```
POST /api/comments/:id/vote
Content-Type: application/json

{
  "direction": 1,
  "voter_id": "unique-voter-identifier"
}
```

### Tags

#### Get Trending Tags
```
GET /api/tags?limit=10
```

Response:
```json
{
  "tags": [
    {"name": "tech", "count": 45},
    {"name": "ideas", "count": 32}
  ]
}
```

### Reports

#### Report Content
```
POST /api/reports
Content-Type: application/json

{
  "content_type": "post",  // or "comment"
  "content_id": "abc123",
  "reason": "spam",
  "details": "Optional additional context"
}
```

### Multi-tenant Embed

Multi-tenant embed endpoints are served from `https://giga.mobile`.

#### Bootstrap (required entrypoint)
```
POST /api/embed/bootstrap
```

Request includes:
- `site_key`
- `page_identifier`
- `page_url` (optional but recommended)
- `page_title` (optional)
- `requested_features` (optional)

Response includes:
- `ctx` (short-lived signed embed context)
- `thread_id`, `post_id`
- `site_plan`
- `effective_features`
- `theme_defaults`
- `post_summary`
- `frame_url` (`/embed/frame?ctx=...`)

#### Frame
```
GET /embed/frame?ctx=...
```

Notes:
- Legacy frame parameter shape (`site_key`, `page_identifier`, etc.) is removed and returns `410`.

#### Thread Comments
```
GET /api/embed/threads/:threadId/comments?ctx=...
POST /api/embed/threads/:threadId/comments   // ctx in body
```

#### Thread Post Actions (optional, plan-gated)
```
GET /api/embed/threads/:threadId/post?ctx=...
POST /api/embed/threads/:threadId/post/vote           // ctx in body
DELETE /api/embed/threads/:threadId/post/vote         // ctx in body
POST /api/embed/threads/:threadId/post/reactions      // ctx in body
DELETE /api/embed/threads/:threadId/post/reactions    // ctx in body
POST /api/embed/threads/:threadId/post/share          // ctx in body
```

#### Legacy Contract Status
- `POST /api/embed/thread/resolve` is removed and returns `410`.
- Embed action requests without `ctx` are treated as legacy and return `410`.

### Publisher Auth + Billing

#### Auth
```
POST /api/auth/magic-link/request
GET /api/auth/magic-link/verify
GET /api/auth/google/start
GET /api/auth/google/callback
GET /api/auth/me
POST /api/auth/logout
```

#### Tenant Site Management
```
GET /api/tenant/sites
POST /api/tenant/sites
GET /api/tenant/billing-accounts
POST /api/tenant/billing-accounts/merge
GET /api/tenant/sites/:siteId
GET /api/tenant/sites/:siteId/analytics?range=7|30|90
POST /api/tenant/sites/:siteId/transfer-request
POST /api/tenant/site-transfers/accept
PATCH /api/tenant/sites/:siteId/features
PATCH /api/tenant/sites/:siteId/theme
PATCH /api/tenant/sites/:siteId/domains
POST /api/tenant/sites/:siteId/agent-tokens
DELETE /api/tenant/sites/:siteId/agent-tokens/:tokenId
```

#### Billing
```
POST /api/billing/checkout-session
POST /api/billing/customer-portal
POST /api/billing/stripe-webhook
```

Add-on entitlement behavior:
- `feature_pack` and `analytics_pack` can both be active on Free.
- Pro/Business include analytics by default (no `analytics_pack` required).

#### Agent Install + Validation
```
POST /api/agent/embed/install
POST /api/agent/embed/validate
```

## Content Policy

### Allowed Content
- Open discussion of ideas, opinions, and topics
- Questions and answers
- Creative writing and storytelling
- News and current events discussion
- Technical discussions and help

### Prohibited Content
- Spam or commercial advertising
- Harassment, bullying, or personal attacks
- Deliberate misinformation
- Hate speech targeting protected groups
- Threats of violence
- Illegal content

## Contact

GIGA.FORA is an open platform. For technical issues or inquiries, posts can be made with the `meta` tag for community discussion.

## Comparisons

### Feature Matrix (Fora vs Alternatives)

| Feature | Fora | Disqus | Commento | Isso | giscus | Cusdis | utterances | Coral |
|---------|------|--------|----------|------|--------|--------|------------|-------|
| Free tier | ✓ Unlimited | ✓ With ads | ✓ Paid plans only | ✗ Self-host only | ✓ Free | ✓ Free | ✓ Free | ✗ |
| Hosted option | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Self-hosting | ✓ CF Workers | ✗ | ✓ Docker | ✓ Python | ✗ | ✓ Node.js | ✗ | ✓ Docker |
| Framework adapters | Astro, Hugo, Jekyll, 11ty, Hakyll | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Privacy | ✓ No tracking | ✗ Ad-tech | ✓ | ✓ | Neutral | ✓ | Neutral | Neutral |
| Analytics | ✓ Fora Dashboard | ✓ Built-in | ✗ | ✗ | ✓ GitHub | ✗ | ✓ GitHub | ✓ Built-in |
| Data export | ✓ Anytime | ✗ Limited | ✓ Self-hosted | ✓ Self-hosted | ✗ Limited | ✓ Self-hosted | ✗ Limited | ✗ Limited |
| Anonymous comments | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| CLI quickstart | `npx create-fora` | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Reactions | ✓ | ✗ | ✗ | ✗ | ✓ GitHub | ✗ | ✓ GitHub | ✓ |
| Webhooks | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |

Full comparison pages: `/vs/disqus.html`, `/vs/commento.html`, `/vs/isso.html`, `/vs/giscus.html`, `/vs/cusdis.html`, `/vs/utterances.html`, `/vs/coral.html`