Feat/cerberus erep

[coodos]

Description of change

Issue Number

Type of change

• Breaking (any change that would cause existing functionality to not work as expected)
• New (a change which implements a new feature)
• Update (a change which updates existing functionality)
• Fix (a change which fixes an issue)
• Docs (changes to the documentation)
• Chore (refactoring, build scripts or anything else that isn't user-facing)

How the change has been tested

Change checklist

• I have ensured that the CI Checks pass locally
• I have removed any unnecessary logic
• My code is well documented
• I have signed my commits
• My code follows the pattern of the application
• I have self reviewed my code

Summary by CodeRabbit

• New Features
  • Introduced comprehensive references system for tracking violation records with metadata including severity scores and attribution tracking
  • Charter violation analysis now automatically persists violation references with detailed record-keeping
  • Added system reference creation API endpoint for internal service operations
  • Integrated with external reputation platform for cross-platform violation tracking and coordination

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 93d77ce4-e815-4c49-a89b-ad5b37430e38

📥 Commits

Reviewing files that changed from the base of the PR and between d22457f and fb137bc.

📒 Files selected for processing (10)

• platforms/cerberus/client/src/database/data-source.ts
• platforms/cerberus/client/src/database/entities/Reference.ts
• platforms/cerberus/client/src/services/CerberusTriggerService.ts
• platforms/cerberus/client/src/services/ReferenceWriterService.ts
• platforms/cerberus/client/src/web3adapter/mappings/reference.mapping.json
• platforms/cerberus/client/src/web3adapter/watchers/subscriber.ts
• platforms/ereputation/api/src/controllers/ReferenceController.ts
• platforms/ereputation/api/src/controllers/WebhookController.ts
• platforms/ereputation/api/src/index.ts
• platforms/ereputation/api/src/web3adapter/mappings/reference.mapping.json

---

📝 Walkthrough

Walkthrough

This PR introduces a new Reference entity across Cerberus and eReputation platforms to track violations detected during charter analysis. It includes TypeORM entity definitions, database mappings, a service layer for writing violation references to both local database and an external eReputation API, integration with charter violation detection, and corresponding API endpoints.

Changes

Cohort / File(s)	Summary
Reference Entity Definition platforms/cerberus/client/src/database/entities/Reference.ts, platforms/cerberus/client/src/database/data-source.ts	Added new TypeORM Reference entity with UUID primary key, target metadata (targetType, targetId, targetName), content, reference type, optional numeric score, author relation to User, status (defaulting to "signed"), anonymous flag, and timestamps. Registered entity in AppDataSource.
Reference Infrastructure platforms/cerberus/client/src/web3adapter/mappings/reference.mapping.json, platforms/cerberus/client/src/web3adapter/watchers/subscriber.ts	Added web3 adapter mapping configuration for references table with schema and field mappings, and extended PostgresSubscriber to load author relation for Reference entities.
Reference Writer Service platforms/cerberus/client/src/services/ReferenceWriterService.ts	Added new service that writes violation references to local TypeORM repository and external eReputation API endpoint (/api/references/system), with user lookup by ename or name and error handling per violation.
Violation Detection Integration platforms/cerberus/client/src/services/CerberusTriggerService.ts	Extended charter violation analysis to return user violations array with id, name, ename, violation text, severity, and score; added control flow to resolve author and invoke ReferenceWriterService to persist violations; updated AI prompt formatting to include sender identifiers.
eReputation API Endpoint platforms/ereputation/api/src/controllers/ReferenceController.ts, platforms/ereputation/api/src/index.ts	Added new createSystemReference controller method guarded by PLATFORM_SHARED_SECRET header, with validation for required fields and numeric score range (1–5); registered as unauthenticated POST route /api/references/system.
eReputation Webhook Handler platforms/ereputation/api/src/controllers/WebhookController.ts, platforms/ereputation/api/src/web3adapter/mappings/reference.mapping.json	Added webhook handling for references table to create or update Reference entities from synced data, with field mapping and conditional author assignment; added corresponding web3 adapter mapping configuration.

Sequence Diagram

sequenceDiagram
    participant CA as Cerberus<br/>Trigger
    participant OS as OpenAI<br/>Service
    participant RW as Reference<br/>WriterService
    participant DB as Cerberus<br/>Database
    participant API as eReputation<br/>API

    CA->>OS: analyzeCharterViolations(message)
    OS-->>CA: { userViolations[] }
    
    alt userViolations not empty
        CA->>RW: writeViolationReferences(violations, authorId)
        
        loop for each violation
            RW->>DB: referenceRepository.create(Reference)
            DB-->>RW: saved Reference
            
            RW->>API: POST /api/references/system<br/>(X-Platform-Secret header)
            API-->>RW: 201 Created
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~55 minutes

Possibly related PRs

• feat: anonymous ereferences #927: Modifies Reference entity definition and anonymous flag handling, overlapping with this PR's entity structure.
• Graph of recommendations in control panel #867: Updates eReputation reference codepath including ReferenceController modifications and mapping configuration.
• Feat/ereputation adapter #439: Introduces Reference entity wiring, mappings, and system reference endpoint in eReputation, directly overlapping with this PR's scope.

Suggested reviewers

• sosweetham

Poem

🐰 References bloom where violations hide,
Cross platforms unified, side by side,
From Cerberus to eReputation's stream,
Tracking transgressions with analytical dream,
A web of accountability, hopping with pride!

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cerberus-erep

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}