Community architecture, sentiment, and member publishing

Reading, search, comparisons, and citations remain public. Voting, commenting, reporting, and member-blog drafting require a Clerk session established exclusively through GitHub and a community account in good standing. GitHub is the external identity authority; Clerk is a temporary session broker. The transactional application database owns profiles, authorization, votes, comments, reports, drafts, moderation, and audit state. GitHub repositories own approved public Markdown.

Identity and authorization boundary

Every member receives an Observaloka-owned community UUID. The immutable numeric GitHub user ID is the durable external subject; Clerk and later Keycloak IDs are replaceable broker-account references. No vote, comment, blog, report, role, or audit record uses a Clerk ID as its owner or foreign key. Mutable GitHub usernames, email addresses, display names, and avatar URLs never establish or merge identity. Profiles expose only a unique handle, optional display name and biography, avatar choice, contribution history, and relevant disclosures. Every private read and mutation checks the broker session, matching GitHub subject, account state, role, action, and resource on the server. Proxy and hidden buttons are navigation aids, not authorization.

The normalized server contract is AuthenticatedCommunityUser: Observaloka community UUID, external_provider = github, immutable GitHub numeric subject, broker and broker subject, application-owned roles, and active/suspended/deleted status. Only the authentication adapter understands Clerk or Keycloak token shapes. A broker-to-provider mismatch is quarantined rather than merged by email.

Roles are member, trusted_contributor, moderator, editor, administrator, and automation, each least-privilege. Client input cannot grant roles. Sensitive role, suspension, poll-freeze, moderation, export, and deletion changes require reasoned audit events and stronger administrator checks. Development and production Clerk instances and secrets are separate.

Verified, idempotent webhooks synchronize only necessary profile fields. Handlers authenticate signatures, record event receipts, tolerate duplicate and out-of-order delivery, compare event time before update, and quarantine a conflicting Clerk/GitHub mapping. A reconciliation task repairs missed events. Users can end sessions, edit public profiles, export account data, request deletion, and understand how attribution and required safety records are treated.

Transactional records

Record	Essential constraints
community_users	Observaloka UUID; public profile; trust/status; disclosures; timestamps; no required Clerk key
external_identities	Unique immutable GitHub numeric subject mapped to one Observaloka UUID
auth_broker_accounts	Replaceable Clerk or Keycloak issuer and subject mapped to the same Observaloka UUID
community_roles	Application-owned least-privilege grants independent of broker metadata
technology_votes	Stable technology ID; unique user+technology; value; moderation; atomic upsert; idempotency key
poll_snapshots	Aggregate time series; methodology version; exclusions; no voter identity
comments / comment_revisions	Stable page and parent IDs; bounded depth; sanitized Markdown; status; edit history
blog_drafts	Private Markdown, sources, disclosures, locked review revision, workflow and eventual PR/page IDs
reports / moderation_cases	Reporter and target, reason/evidence, assignment, decision, appeal, conflict controls
audit_events	Tamper-resistant actor, target, action, reason, time, request and correlation identifiers

The migration path adds a Keycloak broker row after GitHub reauthentication, keeps the Observaloka UUID and GitHub numeric subject unchanged, invalidates Clerk sessions at cutover, quarantines unmatched records, and removes Clerk only after reconciliation and the approved retention period. Local passwords and every non-GitHub identity route remain disabled in both broker phases.

Stable Markdown technology_id and page_id values—not names or slugs—join community records to published content. Vote retries use transactions, uniqueness, and idempotency. Aggregates are recomputable. Migrations, retention, backups, restore tests, and portable exports are versioned.

Community Sentiment

Eligible technology pages offer upvote, downvote, or no active vote. Users may change or remove a vote. The UI shows both counts, total, net, percentage distribution, sample size, calculation time, methodology version, exclusions, and a table matching any chart. It is labeled Community Sentiment: voluntary, non-scientific audience opinion and never becomes an editorial score, product rating, comparison winner, or technical claim.

Global views filter by class, open-source status, operational region, time, volume, and minimum sample size. They emphasize change and participation context—not a “best” league table. Snapshots can be annotated with releases or incidents without claiming causation. Votes stay private from users, vendors, authors, and ordinary moderators. Frozen polls remain readable.

Rate and integrity controls combine account, session, request origin, and proportionate abuse signals. Suspicious velocity, campaigns, bots, and account farms may be held for review. Permanent action requires an understandable human decision and appeal. No demographic or location collection is required for weighting.

Comments and blogs

Native comments are authoritative on enabled pages; Giscus is not shown beside them as a competing primary system. Sanitization runs on input and output, executable HTML is forbidden, and user links receive ugc nofollow. Replies have bounded depth; edits show a marker and revision history; deletion, reports, moderation states, stable permalinks, and public reason notices are defined. States are pending, published, limited, hidden, removed, and appealed.

Member drafts collect title, summary, body, type, tags, sources, disclosures and conflicts, original-publication status, media rights, and contribution-license acceptance. Submission locks a revision and checks schema, links, citations, similarity/plagiarism risk, copyright, malicious URLs, spam, neutrality, disclosures, and instruction injection. Passing creates a draft GitHub PR; a human editor alone may merge. Public labels distinguish Community Blog, Opinion, Tutorial, and Field Report from neutral Observaloka research. Corrections and retractions retain PR provenance.

Moderation, privacy, and failure

Structured reports cover spam, harassment, hate, threats, doxxing, impersonation, undisclosed promotion, manipulation, copyright, privacy, dangerous content, and factual concerns. Policy moderation, editorial correction, and legal/rights workflows are separate but can escalate. Least-privilege queues expose only necessary data. Conflicted reviewers cannot decide their own cases. Material actions, reversals, appeals, role changes, poll exclusions, and restorations record actor and reason; periodic transparency reports reveal aggregates, never reporters or security controls.

State changes resist CSRF, replay, duplicate submission, broken-object authorization, mass assignment, and forged webhooks. Origins, content type, sizes, links, uploads, and idempotency are validated. Secrets and database access stay server-side; logs exclude tokens, email, message bodies, and unnecessary personal data. Transport and storage are encrypted; backups and incident response are tested.

Feature flags independently disable polls, comments, and blogs. A global read-only switch protects outages and attacks. Clerk or database failure leaves all approved research online, disables affected writes with a clear status, and never reports an unconfirmed success.

Acceptance suite

Tests cover anonymous denial; verified vote/create/change/remove and safe retry; concurrent uniqueness; aggregate recomputation; suspended users and frozen polls; cross-user object attacks; expired sessions, forged origins, replayed webhooks, and hidden-control bypass; hostile Markdown and links; complete moderation audit; merge-only blog publication; deletion/retention outcomes; read-only degradation; backup restoration; and portable reconstruction of identity mappings, valid votes, public comments, drafts, and moderation history.