Review & Data Use

This page describes the Review & Data Use model, defining User roles and how review actions are logged.

1. User & Role Concepts

• USER: Base entity for all users (human or technical).
• TECHNICAL_USER: Strictly technical identities (services, federation components, background jobs).
• CONTRIBUTING_USER: Users that can contribute content (claims, scenarios, evidence).
  • TRUSTED_CONTRIBUTOR: Additional trust / certification properties.
  • REVIEWER: Can perform review actions on versioned entities.
  • EXPERT: Contributor with domain‑specific expertise / higher authority.
• FEDERATION_NODE: Technical entity representing a participating node in the federation.
• FEDERATION_ADMIN: Administers one or more federation nodes; not necessarily a content contributor.

2. Review Actions

The system logs every significant action:

• REVIEW_ACTION logs *who* did *what* on *which* versioned entity.
• Fields: ``ReviewActionID``, ``UserID``, ``EntityType``, ``EntityVersionID``, ``ActionType``, ``Timestamp``.
• Each entry targets a specific VERSIONED entity (e.g., ClaimVersion, ScenarioVersion).
• Claim Clusters may also be targets of review actions (e.g., curation or moderation).

3. Review & Data Use ERD

3.1 User Roles

graph TD
 READER[Reader] --> |Registers| CONTRIBUTOR[Contributor]
 CONTRIBUTOR --> |Earns Reputation| TRUSTED[Trusted Contributor
substantial reputation]
 CONTRIBUTOR --> |Appointed by
Governing Team| MODERATOR[Moderator]
 READER --> |Can| R1[Browse/Search]
 READER --> |Can| R2[Flag Issues]
 READER --> |Can| R3[Submit Claims]
 CONTRIBUTOR --> |Can| C1[Edit Claims]
 CONTRIBUTOR --> |Can| C2[Add Evidence]
 CONTRIBUTOR --> |Can| C3[Improve Content]
 TRUSTED --> |Can| T1[Approve Changes]
 TRUSTED --> |Can| T2[Mentor New Contributors]
 MODERATOR --> |Can| M1[Review Flags]
 MODERATOR --> |Can| M2[Hide Harmful Content]
 MODERATOR --> |Can| M3[Resolve Disputes]
 style READER fill:#e1f5ff
 style CONTRIBUTOR fill:#99ff99
 style TRUSTED fill:#ffff99
 style MODERATOR fill:#ff9999

Simplified flat role structure:

• Reader: Default role, no login required
• Contributor: Registers and earns reputation through contributions
• Trusted Contributor: substantial reputation unlocks additional permissions
• Moderator: Appointed by Governing Team, handles abuse/disputes
  No hierarchy - roles represent responsibility levels, not management structure.

Technical & System Users
This diagram shows Technical Users (system processes like AKEL, sync bots, monitors) and their management by Moderators.

erDiagram
 USER {
 string UserID PK
 string role
 int reputation
 }
 MODERATOR {
 string ModeratorID PK
 string UserID FK
 string[] permissions
 }
 SYSTEM_SERVICE {
 string ServiceID PK
 string ServiceName
 string Purpose
 string Status
 }
 AKEL {
 string InstanceID PK
 string ServiceID FK
 string Version
 }
 BACKGROUND_SCHEDULER {
 string SchedulerID PK
 string ServiceID FK
 string[] ScheduledTasks
 }
 SEARCH_INDEXER {
 string IndexerID PK
 string ServiceID FK
 string LastSyncTime
 }
 USER ||--o| MODERATOR : "appointed-as"
 MODERATOR ||--o{ SYSTEM_SERVICE : "monitors"
 SYSTEM_SERVICE ||--|| AKEL : "AI-processing"
 SYSTEM_SERVICE ||--|| BACKGROUND_SCHEDULER : "periodic-tasks"
 SYSTEM_SERVICE ||--|| SEARCH_INDEXER : "search-sync"

Simplified technical model:

• USER: Standard users (Reader/Contributor based on reputation)
• MODERATOR: Appointed users with moderation permissions
• SYSTEM_SERVICE: Automated background services
• AKEL: AI processing engine
• BACKGROUND_SCHEDULER: Quality metrics, source updates, cleanup
• SEARCH_INDEXER: Elasticsearch synchronization
  Removed (no longer in simplified model):

4. User Class Diagram

classDiagram
 class User {
 +UUID id
 +String username
 +String email
 +Role role
 +Int reputation
 +Timestamp created_at
 +contribute()
 +flag_issue()
 +earn_reputation()
 }
 class Reader {
 <>
 +browse()
 +search()
 +flag_content()
 }
 class Contributor {
 <>
 +edit_claims()
 +add_evidence()
 +suggest_improvements()
 +requires: reputation sufficient
 }
 class Moderator {
 <>
 +review_flags()
 +hide_content()
 +resolve_disputes()
 +requires: appointed by Governing Team
 }
 User --> Reader : default role
 User --> Contributor : registers + earns reputation
 User --> Moderator : appointed
 note for User "Reputation system unlocks permissions progressively"
 note for Contributor "Reputation sufficient: Full edit access"
 note for Contributor "Reputation sufficient: Can approve changes"

Simplified flat role structure:

• Three roles only: Reader (default), Contributor (earned), Moderator (appointed)
• Reputation system replaces role hierarchy
• Progressive permissions based on reputation, not titles