# eddieoz/atproto-scam-detector architecture

> Architecture diagram of the GitHub repository eddieoz/atproto-scam-detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eddieoz/atproto-scam-detector
- Repository: https://github.com/eddieoz/atproto-scam-detector

## Overview

##### Main Components Identification

The system should be represented with these key components:

a) Core Service Layer:
- Main Bot Service (src/main.ts)
- Bot Session Manager (src/modules/botSession.ts)
- Database Systems
- SQLite Database (src/modules/database.ts)
- In-Memory Database (src/modules/memDatabase.ts)

b) Detection Modules:
- Scam Detection (src/modules/scamDetection.ts)
- Spam Detection (src/modules/spamDetection.ts)
- Ignore Watcher (src/modules/ignoreWatcher.ts)

c) External Services:
- BlueSky ATProto Integration
- DeepSeek-V3 API Integration
- Ozone Server Integration

**┌─────────────────────────────────────────────────────────┐**
- Crypto-Labeler Bot                   │

- ┌─────────────┐    ┌──────────────┐    ┌──────────┐   │
- Bot Session │────│ Main Service │────│ Helpers  │   │
- ┘    └──────────────┘    └──────────┘   │

- ┌─────────────────────────────────────────────────┐   │
- Detection Modules                  │   │
- ┌──────────┐  ┌──────────┐  ┌─────────────┐   │   │
- Scam   │  │   Spam   │  │   Ignore    │   │   │
- Detection│  │ Detection│  │   Watcher   │   │   │
- ┘  └──────────┘  └─────────────┘   │   │
- ┘   │

- ┌─────────────────────────────────────────────────┐   │
- Storage Layer                      │   │
- ┌──────────┐            ┌─────────────┐        │   │
- SQLite  │            │  In-Memory  │        │   │
- Database │            │  Database   │        │   │
- ┘            └─────────────┘        │   │
- ┘   │
- ┘   │

- ▼
**┌─────────────┐    ┌──────────────┐    ┌─────────────┐**
- ATProto   │    │ DeepSeek-V3  │    │   Ozone     │
- (BlueSky) │    │     API      │    │   Server    │
- ┘    └──────────────┘    └─────────────┘

##### Important Elements to Highlight

a) Data Flow:
- How posts/content flows from BlueSky through the detection pipeline
- AI evaluation paths through DeepSeek-V3
- Database read/write operations
- Moderation action flows to Ozone

b) Integration Points:
- ATProto connection points
- AI API endpoints
- Database connections
- Moderation interfaces

##### Specific Implementation Details

- The bot's session management and persistence
- The separation between different types of detection (spam, scam, etc.)
- Database schema for ignored handles
- Integration with external AI services
- The role of pre-filters (scam terms and ignore lists)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Services"]
        direction TB
        BSKY["BlueSky ATProto"]:::external
        DEEP["DeepSeek-V3 API"]:::external
        OZ["Ozone Labeler"]:::external
    end

    subgraph Core["Core Service Layer"]
        direction TB
        MAIN["Main Bot Service"]:::core
        SESS["Bot Session Manager"]:::core
        subgraph DB["Database Systems"]
            direction TB
            SQL["SQLite Database"]:::database
            MEM["In-Memory Database"]:::database
        end
    end

    subgraph Detection["Detection Modules"]
        direction TB
        SCAM["Scam Detection"]:::detection
        SPAM["Spam Detection"]:::detection
        IGN["Ignore Watcher"]:::detection
        DID["DID Resolver"]:::detection
    end

    subgraph Config["Configuration"]
        direction TB
        ENV["Environment Config"]:::config
        TERMS["Scam Terms"]:::config
        HIGN["Handle Ignore List"]:::config
    end

    subgraph Helpers["Helper Components"]
        direction TB
        OAI["OpenAI Integration"]:::helper
        TREND["Trending Coins Analyzer"]:::helper
    end

    %% Core Relationships
    MAIN --> SESS
    SESS --> DB
    MAIN --> Detection
    
    %% External Service Integration
    MAIN <--> BSKY
    Detection <--> DEEP
    MAIN --> OZ
    
    %% Configuration Dependencies
    ENV --> MAIN
    TERMS --> SCAM
    HIGN --> IGN
    
    %% Helper Integration
    Detection <--> Helpers

    %% Styling
    classDef external fill:#a8d1f0
    classDef core fill:#90EE90
    classDef database fill:#d3d3d3
    classDef detection fill:#ffeb99
    classDef config fill:#ffb366
    classDef helper fill:#DDA0DD

    %% Click Events
    click MAIN "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/main.ts"
    click SESS "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/modules/botSession.ts"
    click SQL "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/modules/database.ts"
    click MEM "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/modules/memDatabase.ts"
    click SCAM "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/modules/scamDetection.ts"
    click SPAM "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/modules/spamDetection.ts"
    click IGN "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/modules/ignoreWatcher.ts"
    click DID "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/modules/didResolver.ts"
    click OAI "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/helpers/evaluateWithOpenAI.ts"
    click TREND "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/helpers/findTrendingCoins.ts"
    click TERMS "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/lists/scam_terms.js"
    click HIGN "https://github.com/eddieoz/atproto-scam-detector/blob/master/src/lists/handle_ignore_array.js"
    click ENV "https://github.com/eddieoz/atproto-scam-detector/blob/master/.env-sample"
```
