# 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
- 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`
  - Agent install guide: `/ai/comments-install`
  - Agent OpenAPI spec: `/openapi-agent.json`

## 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.