# Community News Platform
> Decentralized, transparent community newsrooms where members draft, review, and publish articles together. AI-assisted local journalism with fair revenue sharing.

## What is Community News?
Community News is an open-source platform for community-driven local journalism. Communities create newsrooms where members collaboratively write, review, and publish articles. AI assists by drafting articles from government meeting transcripts using a Three Lenses Framework (Microscope for detail, Kaleidoscope for cross-meeting patterns, Telescope for broader context). Revenue is shared: 70% to authors, 10% to reviewers, 20% to the platform.

## Public Pages
- / -- Homepage with community listings and recent articles
- /communities -- Browse all community newsrooms
- /c/{slug} -- Community feed showing published articles
- /c/{slug}/{articleSlug} -- Individual article with full content

## Tech Stack
- Next.js 16 (App Router) + TypeScript
- Supabase (PostgreSQL, Auth, Storage, RLS)
- Effect v3 for server-side business logic
- Tiptap rich text editor
- Tailwind CSS v4

## Key Features
- Password, magic link, and Google OAuth authentication
- AI-assisted article drafting from livestream transcripts
- PBD (Principle-Based Distillation) for extracting atomic statements from meetings
- Three Lenses Framework for diverse article perspectives
- Community peer review with configurable approval thresholds
- Speaker registry with fuzzy name matching
- Pipeline orchestration (transcription, distillation, embedding, speaker matching, drafting, review)
- Revenue sharing (70/10/20 split)

## For AI Agents and Contributors
This is an open-source project welcoming contributions from both humans and AI agents.
- GitHub: https://github.com/geeks-accelerator/community-news
- Documentation: https://github.com/geeks-accelerator/community-news/tree/main/docs
- Architecture docs, implementation plans, and guides are in the docs/ directory

## Public REST API

All authenticated endpoints require: Authorization: Bearer cn_...
Create API keys at /profile/settings.

### Discovery
- GET /api/v1 -- API root with links to all resources (no auth required)

### Endpoints
- GET /api/v1/articles?community={slug}&limit=20 -- List published articles
- POST /api/v1/articles -- Create a draft article
- GET /api/v1/articles/{id} -- Get article by ID
- PUT /api/v1/articles/{id} -- Update a draft
- POST /api/v1/articles/{id}/submit -- Submit for peer review
- GET /api/v1/communities -- List communities (scoped to key)
- GET /api/v1/communities/{slug} -- Get community details
- GET /api/v1/communities/{slug}/articles -- List community articles
- GET /api/v1/communities/{slug}/members -- List community members
- GET /api/v1/memberships -- List your communities and roles
- POST /api/v1/memberships -- Join a community
- GET /api/v1/search?q=term&type=all|articles|communities -- Full-text search
- GET /api/v1/articles/{id}/reviews -- List reviews for an article
- POST /api/v1/articles/{id}/reviews -- Submit a review (approve/request_changes/reject)
- GET /api/v1/articles/{id}/comments -- List comments
- POST /api/v1/articles/{id}/comments -- Add a comment
- PUT /api/v1/articles/{id}/comments/{commentId} -- Edit comment (within 1 hour)
- DELETE /api/v1/articles/{id}/comments/{commentId} -- Delete own comment
- GET /api/v1/articles/{id}/reactions -- Get reaction counts
- POST /api/v1/articles/{id}/reactions -- Toggle emoji reaction
- POST /api/v1/articles/{id}/bookmarks -- Toggle bookmark

### Topics
- GET /api/v1/topics -- List all topics with stats (supports sort params)
- GET /api/v1/topics/{slug} -- Get topic details and articles (supports sort, limit, offset)

### Content Sources
- GET /api/v1/communities/{slug}/sources -- List content sources (supports type, status, limit, offset)
- POST /api/v1/communities/{slug}/sources -- Create a content source (body: { source_type, title?, source_url?, body_text?, body_html?, author_name? })
- GET /api/v1/communities/{slug}/sources/{id} -- Get source detail with transcript chunks and drafted articles
- POST /api/v1/communities/{slug}/sources/{id}/classify -- Trigger LLM classification (returns category, topics, entities, priority, newsworthiness)
- POST /api/v1/communities/{slug}/sources/{id}/draft -- Trigger article drafting (creates pipeline run)
  Source types: video, audio, email, web_scrape, rss, pdf, manual

### Co-authors
- GET /api/v1/articles/{id}/coauthors -- List co-authors for an article
- POST /api/v1/articles/{id}/coauthors -- Invite a co-author (body: { user_id })
- PUT /api/v1/articles/{id}/coauthors/{coauthorId} -- Accept or decline invitation (body: { status: "accepted" | "declined" })

### Content Reporting
- POST /api/v1/articles/{id}/report -- Report an article (body: { reason, description? })
- POST /api/v1/articles/{id}/comments/{commentId}/report -- Report a comment (body: { reason, description? })
  Valid reasons: spam, harassment, misinformation, off_topic, hate_speech, other

### Moderation (Admin Only)
- GET /api/v1/communities/{slug}/moderation/reports?status=pending -- List content reports
- PUT /api/v1/communities/{slug}/moderation/reports/{id} -- Resolve a report (body: { status, note? })
  Valid statuses: reviewed, action_taken, dismissed

### User Profile
- GET /api/v1/me -- Get authenticated user's profile with memberships
- PUT /api/v1/me -- Update profile (body: { display_name?, bio?, location?, latitude?, longitude?, news_radius_miles?, timezone?, website_url?, social_links?, is_public? })
- GET /api/v1/me/bookmarks -- List bookmarked articles (supports offset, limit)

### API Keys
- POST /api/v1/api-keys -- Create a new API key (body: { name, community_ids?, expires_at? }). Full key returned only once.

### Notifications
- GET /api/v1/notifications -- List user notifications (supports ?unread=true)
- PATCH /api/v1/notifications/{id} -- Mark a notification as read
- POST /api/v1/notifications/mark-all-read -- Mark all notifications as read

### Voice Profiles
- GET /api/v1/voice-profile -- Get active voice profile + version history
- POST /api/v1/voice-profile -- Calibrate new version from writing samples (body: { sample_texts: string[] })
- PUT /api/v1/voice-profile/{id} -- Activate (body: { action: "activate" }) or manual update (body: { voice_summary, dimensions })
- DELETE /api/v1/voice-profile/{id} -- Delete a non-active version

### Citizen Worker Endpoints (Worker App)
- GET /api/v1/worker/profile -- Get worker profile and stats
- GET /api/v1/worker/jobs/available -- Get next available job
- POST /api/v1/worker/jobs/{id}/claim -- Claim a job
- POST /api/v1/worker/jobs/{id}/heartbeat -- Send progress heartbeat (body: { progress, message })
- POST /api/v1/worker/jobs/{id}/chunks -- Upload audio chunk (multipart form: file, chunk_index)
- POST /api/v1/worker/jobs/{id}/complete -- Mark job complete
- POST /api/v1/worker/jobs/{id}/fail -- Report job failure (body: { error })
- GET /api/v1/worker/jobs/{id}/live-status -- Get livestream status
- POST /api/v1/worker/jobs/{id}/transcript -- Submit partial transcript (body: { text, timestamp })

### Admin: Workers (Platform Admin)
- GET /api/v1/workers?status=approved -- List workers
- GET /api/v1/workers/{id} -- Worker details
- POST /api/v1/workers/{id}/approve -- Approve pending worker
- POST /api/v1/workers/{id}/suspend -- Suspend worker (body: { reason })
- POST /api/v1/workers/{id}/reinstate -- Reinstate suspended worker

### Admin: Jobs (Platform Admin)
- GET /api/v1/jobs?status=pending -- List transcription jobs
- POST /api/v1/jobs -- Create job (body: { community_id, url, priority, job_type })
- GET /api/v1/jobs/{id} -- Job details with chunks
- PATCH /api/v1/jobs/{id} -- Update priority (body: { priority })
- POST /api/v1/jobs/{id}/cancel -- Cancel job (body: { message? })
- POST /api/v1/jobs/{id}/retry -- Retry failed job

All list endpoints support pagination: ?offset=0&limit=20

### Sorting
Article and community list endpoints support sorting via query parameters:
- sort -- Sort mode: hot (default), new, nearby, top, rising, controversial, foryou
- t -- Time window for "top" sort: today, week (default), month, all
- lat -- Latitude for "nearby" sort (required for nearby)
- lng -- Longitude for "nearby" sort (required for nearby)
- r -- Radius in miles for "nearby" sort (default: 50, min: 5, max: 500)

Sort modes:
- hot -- Trending articles ranked by engagement + recency (default)
- new -- Newest articles first
- top -- Most engagement within time window (use t param)
- nearby -- Geographically closest (requires lat, lng; optional r)
- rising -- Recent articles gaining traction quickly
- controversial -- High engagement but mixed/polarized reactions
- foryou -- Personalized feed; excludes already-read articles, boosts engaged communities. Does not require community param.

Examples:
- GET /api/v1/articles?community=slug&sort=new -- Newest articles first
- GET /api/v1/articles?community=slug&sort=top&t=month -- Top articles this month
- GET /api/v1/articles?community=slug&sort=nearby&lat=61.2&lng=-149.9&r=100 -- Articles within 100 miles
- GET /api/v1/communities?sort=nearby&lat=61.2&lng=-149.9 -- Communities near coordinates
- GET /api/v1/articles?community=slug&sort=rising -- Rising articles
- GET /api/v1/articles?community=slug&sort=controversial -- Controversial articles
- GET /api/v1/articles?sort=foryou -- Personalized feed (community param optional)

### API Documentation
- /docs/api -- Full API reference

## Contact
- Domain: alaskanews.news
- Organization: Geeks Accelerator