Harlequin API

Repo: clanofartisans/Harlequin-API

This is the brain that runs all my Harlequin projects. It effectively maintains a realtime mirror of Horizon's character database by intelligently pulling data from the Horizon API only when it updates. It can also report live updates to arbitrary webhooks (a public version would allow users to register their own) that can fire on logins/logouts (useful for Harlequin Friend List) and level/job/zone/other changes. Its database also contains historical data like online counts and daily active user data. I'm the only one with access to this at the moment.

An important function of the Harlequin API is this is where all search comment matching happens. I designed the service to be public but it's really only being used by Harlequin Auth (see below) right now. Basically anyone can request a search comment check for a HorizonXI character. If it gets a match in the next hour, it responds to a callback address you gave it when you made the request. I use this same method when authenticating other projects like Harlequin Friend List.

This is a Laravel PHP application and most functionality exists as REST API calls and an asynchronous job queue system running on Laravel Horizon.

Harlequin Bot

Repo: clanofartisans/Harlequin-Bot-JS

This handles all the "realtime" functionality for the Harlequin Discord buttons, commands, modals, etc. and sends more complicated things to auth.horizonxi.com for processing.

Foreground things it handles:

  • Register/Refresh/Unregister functionality in #discord-setup
  • Role Selection in #channels-and-roles
  • The /mute command for mods (mutes technically route through Horizon Auth, see below)
  • The /ticket command for mods
  • Laying all the text you see in channels like #discord-setup (this would be better handled with a webhook)

In the background, it also reports details of several events to Harlequin Auth (see below):

  • Any time a user joins the Discord
  • Any time a user leaves the Discord
  • Any time a user gets/loses a Tickets Only role

This is a Discord.js application written in JavaScript for NodeJS.

Harlequin Auth

https://auth.horizonxi.com/

Repo: HorizonFFXI/harlequin-bot

This does most of the heavier lifting that the JavaScript component of the Harlequin Bot would choke on. From here, we integrate with the Harlequin API, the HorizonXI API, and the Discord API.

Character/Discord Linking

All character/Discord registrations flow through Harlequin Auth's API, whether from the Discord bot or from the web interface. When a request to link a character comes through, a search comment check is dispatched to the Harlequin API with a callback URL. When the Harlequin API finds a match, it sends the character data to Harlequin Auth's callback URL. From there, it ties the character and Discord account together in its database, then updates the user's Discord roles and nickname, then unlocks the Mog Satchel for the account.

Level-Based Roles

In addition, the Harlequin API keeps Harlequin Auth constantly updated about relevant character data changes thanks to its webhook system for receiving live updates. As it detects level changes through these updates, Harlequin Auth calculates whether or not a user's Discord roles need updated and applies any needed changes through the Discord API. This powers the level based New / Certified / Proven / Seasoned / Veteran / Master Adventurer role automation.

Web Interface

This is also where the web interface lives and was originally the only way to manage your character/Discord registration before you could just do everything in the #discord-setup channel. The web interface is also home to the admin and audit interfaces where everything Harlequin Auth does is logged and searchable, and admins can manually register characters or request data refreshes.

Sticky Roles and Tickets Only

There are a couple other smaller things it does in the background to help with moderation like sticky roles. When a user leaves the Discord, the JavaScript Harlequin Bot sends that user's info to Horizon Auth's API where the user's role list is persisted to a database. When a user joins the server, the JS bot sends a similar event to the API where Horizon Auth looks the user up in this database and reapplies any missing roles automatically. The bot also lets Horizon Auth know when users receive the Tickets Only role which uses that information to post in the mod channel dedicated to logging that activity. It does its best to correlate the information with Discord's audit logs but their API around that is seriously lacking so it sometimes things the wrong person applied mutes.

Like the Harlequin API, this is a Laravel PHP application and most functionality exists as REST API calls and an asynchronous job queue system running on Laravel Horizon.

Harlequin Suggestions (honorable mention)

Repo: https://github.com/Suggester/Suggester

I also run the "Harlequin Suggestions" bot, which is really just the old "Suggester" bot we used whose code just happened to be open source when they shut down.