# projectedengg/jayce architecture

> Architecture diagram of the GitHub repository projectedengg/jayce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/projectedengg/jayce
- Repository: https://github.com/projectedengg/jayce

## Overview

##### Project Type and Purpose
- This is a backend–only Java application implementing a Discord bot (“Jayce”) with GitHub integration.
- Its primary function is to listen for Discord events (messages, channel actions), respond to slash commands, schedule and run cleanup jobs in Discord channels, and query GitHub issues/repos.

##### File-Structure Analysis
- Top-level:
- pom.xml – Maven build file (dependencies include JDA or Discord4J, a GitHub API client, a scheduler)
- start.sh – startup shell script
- transfer-issue – likely a helper script for GitHub issue transfers
- src/main/java/gg/projecteden/jayce/:
- Jayce.java – entry point (bootstraps Discord client, scheduler, command registry)
- commands/ – command-handling classes (e.g., ChannelAppCommand, IssuesAppCommand)
- listeners/ – event listeners for Discord events (e.g., IssueLinkListener)
- config/ – configuration holders (aliases, bot config)
- github/ – wrappers around GitHub API calls (Repos, Issues)
- models/scheduledjobs/jobs/ – job classes executed on schedule (ChannelDeleteJob, MessageDeleteJob, etc.)
- utils/ – shared utilities

a. Discord Client Module
- Connects to Discord Gateway via JDA (or Discord4J).
- Dispatches raw events to listener layer.
b. Command Handler
- Registers slash commands at startup.
- Receives command events → routes to specific Command class in commands/*.
c. Event Listeners
- Subscribes to message/update events → triggers link parsing, support-channel archiving, etc.
d. GitHub Integration
- Issues and Repos classes wrap GitHub REST API calls.
- Invoked by commands (e.g., /issues) or link listener.
e. Scheduler
- A scheduled-task engine (Quartz or JDK scheduler)
- Executes scheduled jobs (e.g., cleaning up old messages or channels).
f. Configuration
- Holds bot token, command aliases, scheduling parameters.

##### Relationships and Data Flow
- User on Discord issues a slash command or posts a message → Discord Gateway → Discord Client → Command Handler or Event Listener.
- Command Handler may call GitHub Integration module → external GitHub REST API → parse response → send embed/message via Discord Client → back to user.
- Scheduler triggers Job classes on a cron or fixed delay → Job reads config → performs cleanup via Discord Client API.
- Configuration is read at startup and injected into all modules.

##### Architectural Patterns and Principles
- Layered structure:
- Core layer (Jayce.java, Config)
- API layer (github/)
- Presentation layer (listeners/, commands/)
- Infrastructure (scheduler, utils/)
- Command pattern for slash-command implementations.
- Observer pattern for event listeners.
- Dependency injection (manual or via small factory in Jayce.java).

##### Final Checklist
- Callouts for key technologies (Java 17+, Maven, JDA/Discord4J, GitHub API).
- Layer boundaries (e.g., Presentation, Business Logic, Infrastructure).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    DiscordGateway["Discord Gateway/API"]:::ext
    GitHubREST["GitHub REST API"]:::ext

    %% Core Module
    Jayce["Discord Client (Jayce.java)"]:::core
    click Jayce "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/Jayce.java"

    %% Presentation Layer: Command Handler
    subgraph "Command Handler" 
        CH1["ChannelAppCommand"]:::core
        CH2["IssuesAppCommand"]:::core
        CH3["JayceAppCommand"]:::core
        click CH1 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/commands/ChannelAppCommand.java"
        click CH2 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/commands/IssuesAppCommand.java"
        click CH3 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/commands/common/JayceAppCommand.java"
    end

    %% Presentation Layer: Event Listeners
    subgraph "Event Listener Layer"
        EL1["IssueLinkListener"]:::core
        EL2["RepoChannelListener"]:::core
        EL3["SupportChannelListener"]:::core
        EL4["DiscordListener"]:::core
        click EL1 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/listeners/IssueLinkListener.java"
        click EL2 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/listeners/RepoChannelListener.java"
        click EL3 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/listeners/SupportChannelListener.java"
        click EL4 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/listeners/common/DiscordListener.java"
    end

    %% API Layer: GitHub Integration
    subgraph "GitHub Integration Module"
        GH1["Issues"]:::ext
        GH2["Repos"]:::ext
        click GH1 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/github/Issues.java"
        click GH2 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/github/Repos.java"
    end

    %% Infrastructure Layer: Scheduler & Jobs
    subgraph "Scheduler & Jobs"
        Scheduler["Scheduler Engine"]:::infra
        J1["ChannelDeleteJob"]:::infra
        J2["MessageDeleteJob"]:::infra
        J3["SupportChannelArchiveJob"]:::infra
        click J1 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/models/scheduledjobs/jobs/ChannelDeleteJob.java"
        click J2 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/models/scheduledjobs/jobs/MessageDeleteJob.java"
        click J3 "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/models/scheduledjobs/jobs/SupportChannelArchiveJob.java"
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        Config["Config"]:::config
        Aliases["Aliases"]:::config
        Utils["Utils"]:::config
        click Config "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/config/Config.java"
        click Aliases "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/config/Aliases.java"
        click Utils "https://github.com/projectedengg/jayce/blob/master/src/main/java/gg/projecteden/jayce/utils/Utils.java"
    end

    %% Flow & Relationships
    DiscordGateway -->|events| Jayce
    Jayce -->|registers/dispatches| CH1
    Jayce --> CH2
    Jayce --> CH3
    Jayce --> EL1
    Jayce --> EL2
    Jayce --> EL3
    Jayce --> EL4

    CH2 -->|"calls"| GH1
    CH2 --> GH2
    GH1 -->|REST API| GitHubREST
    GH2 --> GitHubREST

    Scheduler --> J1
    Scheduler --> J2
    Scheduler --> J3
    J1 -->|uses Discord API| Jayce
    J2 --> Jayce
    J3 --> Jayce

    Jayce --> Scheduler

    Config --> Jayce
    Config --> Scheduler
    Config --> CH1
    Config --> EL1
    Aliases --> CH1
    Utils --> CH1
    Utils --> EL1

    %% Styling
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef ext fill:#ccffcc,stroke:#054d00,color:#054d00
    classDef infra fill:#ffe5cc,stroke:#663c00,color:#663c00
    classDef config fill:#e5e5e5,stroke:#6c757d,color:#6c757d
```
