User Class Diagram

Last modified by Robert Schaub on 2025/12/24 20:34

User Class Diagram

This diagram shows the user role hierarchy in FactHarbor v0.9.1, with corrected inheritance.

Critical: Corrected Inheritance

IMPORTANT CORRECTION:

Moderator derives from Reviewer (NOT from Expert)
Maintainer derives from Contributor (NOT from Reviewer or Moderator)

Two Independent Tracks from Contributor:

Content Track: Contributor → Reviewer → (Auditor | Expert | Moderator)

Focus: Content quality, validation, community management
Skills: Domain expertise, review, moderation

Technical Track: Contributor → Maintainer

Focus: System operations, configuration, deployment
Skills: DevOps, system administration, technical configuration
Independent from content review - Maintainers don't need review skills

System Track: Reader → Technical User

Not human users - automated processes
Examples: AKEL instances, sync bots, monitors
Managed by Maintainers

Role Hierarchy Explanation

Base: Reader

Anyone, no login required
Foundation for all other roles
Can browse, search, compare, flag, and automatically submit claims

Technical User (system type, extends Reader)

Not human users - automated system processes
Examples: AKEL instances, federation sync bots, backup services, monitoring
Can perform automated operations
AKEL is primary implementation of Technical User pattern

Contributor (extends Reader)

Registered human users
Can submit evidence, propose scenarios, participate in discussions
All Reader capabilities plus contribution rights
Two-way branching: Can become Reviewer (content track) or Maintainer (technical track)

Reviewer (is-a Contributor - Content Track)

Trusted community members on content track
Can review and approve content
Can validate AI-generated content (Mode 2 → Mode 3 for Tier B/C)
Participates in audit sampling
Three-way branching: Can specialize as Auditor, Expert, or Moderator

Maintainer (is-a Contributor - Technical Track)

Core technical team members on technical track
System configuration and deployment authority
Does NOT require review skills
Manages Technical Users (creates AKEL instances, sync bots, etc.)
Independent from content review hierarchy

Specialized Reviewer Roles:

Auditor (specialized Reviewer - QA track)

Dedicated quality assurance role
Reviews sampled AI-generated content
Validates quality gate enforcement
Provides feedback for system improvement

Expert (specialized Reviewer - domain track)

Subject matter specialists
Final authority for Tier A content in their domain
Can define domain-specific standards
Required for Tier A "Human-Reviewed" status

Moderator (specialized Reviewer - process track)

Community management focus
Handles abuse and disputes
Manages users and permissions
Oversees audit system
Independent from domain expertise and technical operations

AKEL (Technical User implementation)

AI system implementing Technical User interface
Creates drafts for Contributor review
Subject to Auditor oversight
Never bypasses human authority

Key Design Principles

Why Maintainer derives from Contributor (not Reviewer):

Different skill set: Technical operations ≠ Content review
Separation of concerns: Technical authority independent from editorial authority
Flexibility: Can have technical experts without review experience
Realistic: System admin skills and content review skills are distinct
Cleaner: Maintainer manages Technical Users (including AKEL) - natural fit on technical track

Why Moderator derives from Reviewer (not Expert):

Moderators handle process (community management, disputes) not domain expertise
Experts focus on subject matter (medical, legal, scientific validation)
Allows independent oversight of content quality (Experts) vs community behavior (Moderators)
Moderators don't need domain expertise to handle community issues

Technical User Pattern:

Purpose: Represents automated system processes
Examples: AKEL (AI processing), Federation sync bots, Scheduled audit tasks, Backup services, Monitoring systems, API integrations
Managed by: Maintainers create and configure Technical Users
Authority: Limited to programmatic operations, no human-level decisions

Progressive Trust:

Reader → Contributor (registration)
Contributor → Reviewer (content track) OR Maintainer (technical track)
Reviewer → Auditor/Expert/Moderator (specializations)
All appointments based on demonstrated competence

Human Authority:

Technical Users assist but don't make human-level decisions
Human Reviewers validate AI outputs
Experts have final say on Tier A content
Moderators have final say on community matters
Maintainers have final say on technical configuration

classDiagram
    class Reader {
        +String SessionID
        +String LocalPreferences
        +browse() View all published content
        +search() Search claims and scenarios
        +compare() Compare scenarios
        +flag() Flag issues or errors
        +submitClaim() Submit text for automatic claim extraction
    }
    
    class Contributor {
        +String UserID
        +String DisplayName
        +String Email
        +DateTime RegisteredAt
        +submitEvidence() Attach sources
        +proposeScenario() Draft scenarios
        +comment() Participate in discussions
        +requestReview() Request human review
    }
    
    class TechnicalUser {
        +String SystemID
        +String SystemName
        +String Purpose
        +automatedProcess() Execute automated tasks
        +systemIntegration() Integrate with external systems
    }
    
    class Reviewer {
        +String ReviewerID
        +String[] Domains
        +DateTime AppointedAt
        +review() Review contributions and AI drafts
        +validate() Validate AI-generated content Mode 2→3
        +edit() Edit claims, scenarios, evidence
        +approve() Approve Tier B/C for Human-Reviewed
        +flagForExpert() Escalate to expert review
        +audit() Participate in sampling audits
    }
    
    class Auditor {
        +String AuditorID
        +String[] AuditDomains
        +Float AuditAccuracy
        +reviewSample() Review sampled AI content
        +validateQualityGates() Check gate enforcement
        +identifyPatterns() Find AI error patterns
        +provideFeedback() Improve system quality
    }
    
    class Expert {
        +String ExpertID
        +String ExpertiseArea
        +String[] Certifications
        +DateTime VerifiedAt
        +authoritativeApproval() Final authority Tier A
        +validateComplex() Complex domain validation
        +defineStandards() Set domain quality standards
        +overrideAKEL() Override AI suggestions with docs
    }
    
    class Moderator {
        +String ModeratorID
        +String[] Responsibilities
        +handleAbuse() Manage abuse reports
        +manageUsers() User permissions
        +enforceGuidelines() Community guidelines
        +adjustRiskTiers() Review tier assignments
        +overseeAudits() Audit system oversight
    }
    
    class Maintainer {
        +String MaintainerID
        +String[] SystemAccess
        +configureSystem() Technical configuration
        +manageRoles() Grant and revoke roles
        +configureAKEL() Quality gates and parameters
        +deployUpdates() System deployment
        +setPolicy() Risk tier policies
        +manageTechnicalUsers() Create and manage system accounts
    }
    
    class AKEL {
        +String InstanceID
        +Enum AuthorType "AI"
        +extractClaims() Claim extraction
        +classifyRisk() Risk tier assignment
        +generateScenarios() Draft scenarios
        +searchContradictions() Mandatory counter-evidence search
        +validateQualityGates() Run 4 quality gates
        +proposeVerdicts() Draft verdicts
    }
    
    Reader <|-- Contributor : extends
    Reader <|-- TechnicalUser : system-type
    Contributor <|-- Reviewer : content-track
    Contributor <|-- Maintainer : technical-track
    Reviewer <|-- Auditor : specialized-QA
    Reviewer <|-- Expert : specialized-domain
    Reviewer <|-- Moderator : specialized-process
    
    AKEL --|> TechnicalUser : implements
    AKEL ..> Contributor : creates-drafts-for
    AKEL ..> Reviewer : submits-to
    AKEL ..> Auditor : audited-by
    Maintainer ..> TechnicalUser : manages