# ssilve1989/ulti-project architecture

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

- Interactive diagram: https://gitdiagram.com/ssilve1989/ulti-project
- Repository: https://github.com/ssilve1989/ulti-project

## Overview

##### Project type and purpose
- This is a backend “monolithic” service built on NestJS that implements a Discord bot.
- It handles slash‐command interactions, persists data to Firebase (Firestore), integrates with external APIs (Discord Gateway/REST, Google Sheets, FFLogs GraphQL), runs scheduled jobs via cron, and reports to Sentry.

##### File structure
- src/app.module.ts wires together all NestJS modules.
- Major top‐level directories under src are:
– discord: Gateway connection, decorators, service for interacting with Discord.
– slash-commands: All slash command definitions, handlers, subcommands modularized by feature (signup, blacklist, lookup, status, settings, turboprog, etc.).
– firebase: Firestore collections, models, module.
– sheets: Google Sheets integration (config, service, utils, turbo-prog sheets).
– fflogs: GraphQL schema & SDK, module for FFLogs queries.
– jobs: Cron‐triggered background jobs (invite-cleaner, clear-checker, sheet-cleaner).
– role-manager, sentry: cross-cutting modules for authorization and monitoring.
- Configuration and infra files: Dockerfile, fly.toml (deployment), GitHub Actions workflows (CI, release, docker-image), tsconfig, schema.graphql, codegen.ts.

##### README
- (Empty in this case, but file names and config imply GraphQL code generation, NestJS CLI, pnpm, Husky for pre-commit, Vitest for tests.)

##### Main components and interactions
a. Internal components (all inside one NestJS application):
- Core NestJS application
- DiscordModule/Service – connects to Discord Gateway & REST
- SlashCommandsModule – dispatches incoming interactions to feature modules
- Feature modules: SignupModule, BlacklistModule, LookupModule, SettingsModule, StatusModule, TurboProgModule, FinalPush, RemoveRole, Retire
- FirebaseModule – Firestore data persistence for signups, settings, blacklist
- SheetsModule – read/write to Google Sheets (spreadsheet, turbo-prog)
- FFLogsModule – GraphQL client to FFLogs API
- JobsModule – scheduled tasks for housekeeping
- RoleManagerModule – role-based authorization
- SentryModule – error/tracing reporting
- AppSagas – orchestrates long-running flows/events

b. External services:
- Discord API (Gateway & REST)
- Firebase Firestore
- Google Sheets API
- FFLogs GraphQL API
- Sentry

c. Data flow:
1. Discord user invokes slash command → Discord Gateway/REST posts interaction to your NestJS HTTP controller (DiscordModule)
2. Router delegates to SlashCommandsService → specific command handler
3. Handler may read/write Firestore via FirebaseModule, call Google Sheets via SheetsModule, or fetch from FFLogsModule
4. Handlers emit domain events → AppSagas picks up events → triggers follow-on actions (e.g., assign roles, send approval messages)
5. Cron jobs in JobsModule periodically run housekeeping tasks that also interact with Firebase and Discord (via DiscordService)
6. All exceptions/traces reported to Sentry

##### Architectural patterns and design principles
- Modular Monolith – each feature in its own NestJS module
- CQRS/Events – command handlers and event handlers with sagas
- Dependency Injection – NestJS providers & modules
- Hexagonal/Onion hints – separation of external services behind modules (Firebase, Sheets, FFLogs)

– Label modules with key technologies (e.g., “FirebaseModule (Firestore)”, “SheetsModule (Google Sheets API)”).
– Ensure it captures scheduling (JobsModule) and event orchestration (AppSagas).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    DiscordAPI["Discord API\n(Gateway & REST)"]:::external
    Firestore["Firebase Firestore"]:::external
    SheetsAPI["Google Sheets API"]:::external
    FFLogsAPI["FFLogs GraphQL API"]:::external
    SentryService["Sentry"]:::external

    %% NestJS Core
    subgraph "NestJS Core" 
        direction TB
        AppModule["AppModule"]:::internal
        Main["main.ts"]:::internal
        AppController["AppController"]:::internal
        AppService["AppService"]:::internal
        AppSagas["AppSagas"]:::internal
    end

    %% Discord Module
    DiscordModule["DiscordModule\n(src/discord)"]:::internal

    %% Slash Commands Router
    SlashCommandsModule["SlashCommandsModule\n(src/slash-commands)"]:::internal

    %% Feature Modules
    subgraph "Feature Modules" 
        direction TB
        SignupModule["SignupModule"]:::internal
        BlacklistModule["BlacklistModule"]:::internal
        LookupModule["LookupModule"]:::internal
        SettingsModule["SettingsModule"]:::internal
        StatusModule["StatusModule"]:::internal
        TurboProgModule["TurboProgModule"]:::internal
        FinalPushModule["FinalPush"]:::internal
        RemoveRoleModule["RemoveRoleModule"]:::internal
        RetireModule["RetireModule"]:::internal
        SearchModule["SearchModule"]:::internal
    end

    %% Persistence & Integration Modules
    FirebaseModule["FirebaseModule\n(Firestore)"]:::internal
    SheetsModule["SheetsModule\n(Google Sheets)"]:::internal
    FFLogsModule["FFLogsModule\n(FFLogs GraphQL)"]:::internal

    %% Jobs and Cross-cutting
    JobsModule["JobsModule\n(Cron Jobs)"]:::jobs
    RoleManagerModule["RoleManagerModule"]:::internal
    SentryModule["SentryModule"]:::internal

    %% Connections
    DiscordAPI -->|"Interaction"| DiscordModule
    DiscordModule -->|"HTTP Interaction"| SlashCommandsModule
    SlashCommandsModule -->|"Dispatch"| SignupModule
    SlashCommandsModule -->|"Dispatch"| BlacklistModule
    SlashCommandsModule -->|"Dispatch"| LookupModule
    SlashCommandsModule -->|"Dispatch"| SettingsModule
    SlashCommandsModule -->|"Dispatch"| StatusModule
    SlashCommandsModule -->|"Dispatch"| TurboProgModule
    SlashCommandsModule -->|"Dispatch"| FinalPushModule
    SlashCommandsModule -->|"Dispatch"| RemoveRoleModule
    SlashCommandsModule -->|"Dispatch"| RetireModule
    SlashCommandsModule -->|"Dispatch"| SearchModule

    SignupModule <-->|"Firestore R/W"| FirebaseModule
    BlacklistModule <-->|"Firestore R/W"| FirebaseModule
    LookupModule <-->|"Firestore R/W"| FirebaseModule
    SettingsModule <-->|"Firestore R/W"| FirebaseModule

    SignupModule -->|"Sheets API Call"| SheetsModule
    TurboProgModule -->|"Sheets API Call"| SheetsModule

    LookupModule -->|"GraphQL Query"| FFLogsModule

    FeatureEvents(("Event Bus")):::event
    SignupModule -->|"Emit Event"| FeatureEvents
    BlacklistModule -->|"Emit Event"| FeatureEvents
    FeatureEvents -->|"Handle Event"| AppSagas
    AppSagas -->|"Trigger Action"| StatusModule

    JobsModule -->|"Cron Trigger"| FirebaseModule
    JobsModule -->|"Cron Trigger"| DiscordModule

    RoleManagerModule -->|"Authorization"| SignupModule
    RoleManagerModule -->|"Authorization"| BlacklistModule
    RoleManagerModule -->|"Authorization"| SettingsModule

    AppModule -->|"Integrates"| DiscordModule
    AppModule -->|"Integrates"| SlashCommandsModule
    AppModule -->|"Integrates"| FirebaseModule
    AppModule -->|"Integrates"| SheetsModule
    AppModule -->|"Integrates"| FFLogsModule
    AppModule -->|"Integrates"| JobsModule
    AppModule -->|"Integrates"| RoleManagerModule
    AppModule -->|"Integrates"| SentryModule

    %% Reporting to Sentry
    DiscordModule -->|"Report Errors"| SentryModule
    SlashCommandsModule -->|"Report Errors"| SentryModule
    FirebaseModule -->|"Report Errors"| SentryModule
    SheetsModule -->|"Report Errors"| SentryModule
    FFLogsModule -->|"Report Errors"| SentryModule
    JobsModule -->|"Report Errors"| SentryModule
    AppSagas -->|"Report Errors"| SentryModule

    %% Click Events
    click AppModule "https://github.com/ssilve1989/ulti-project/blob/master/src/app.module.ts"
    click Main "https://github.com/ssilve1989/ulti-project/blob/master/src/main.ts"
    click AppController "https://github.com/ssilve1989/ulti-project/blob/master/src/app.controller.ts"
    click AppService "https://github.com/ssilve1989/ulti-project/blob/master/src/app.service.ts"
    click AppSagas "https://github.com/ssilve1989/ulti-project/blob/master/src/app.sagas.ts"

    click DiscordModule "https://github.com/ssilve1989/ulti-project/blob/master/src/discord/discord.module.ts"
    click DiscordService "https://github.com/ssilve1989/ulti-project/blob/master/src/discord/discord.service.ts"
    click DiscordDecorators "https://github.com/ssilve1989/ulti-project/blob/master/src/discord/discord.decorators.ts"
    click DiscordConsts "https://github.com/ssilve1989/ulti-project/blob/master/src/discord/discord.consts.ts"
    click DiscordHelpers "https://github.com/ssilve1989/ulti-project/blob/master/src/discord/discord.helpers.ts"
    click DiscordExceptions "https://github.com/ssilve1989/ulti-project/blob/master/src/discord/discord.exceptions.ts"

    click SlashCommandsModule "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/slash-commands.module.ts"
    click SlashCommandsService "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/slash-commands.service.ts"
    click SlashCommandsUtils "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/slash-commands.utils.ts"
    click SlashCommandsInterfaces "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/slash-commands.interfaces.ts"

    click SignupModule "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/signup/signup.module.ts"
    click SignupService "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/signup/signup.service.ts"
    click SignupSlash "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/signup/signup.slash-command.ts"
    click SignupSchema "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/signup/signup.schema.ts"
    click SignupConsts "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/signup/signup.consts.ts"
    click SignupHandler "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/signup/commands/handlers/signup.command-handler.ts"

    click BlacklistModule "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/blacklist/blacklist.module.ts"
    click BlacklistSlash "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/blacklist/blacklist.slash-command.ts"

    click LookupModule "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/lookup/lookup.module.ts"
    click LookupSlash "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/lookup/lookup.slash-command.ts"

    click SettingsModule "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/settings/settings.module.ts"

    click StatusModule "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/status/status.module.ts"

    click TurboProgModule "https://github.com/ssilve1989/ulti-project/blob/master/src/slash-commands/turboprog/turbo-prog.module.ts"

    click FirebaseModule "https://github.com/ssilve1989/ulti-project/blob/master/src/firebase/firebase.module.ts"
    click FirebaseConfig "https://github.com/ssilve1989/ulti-project/blob/master/src/firebase/firebase.config.ts"
    click FirebaseConsts "https://github.com/ssilve1989/ulti-project/blob/master/src/firebase/firebase.consts.ts"
    click FirebaseCollections "https://github.com/ssilve1989/ulti-project/tree/master/src/firebase/collections"
    click FirebaseModels "https://github.com/ssilve1989/ulti-project/tree/master/src/firebase/models"

    click SheetsModule "https://github.com/ssilve1989/ulti-project/blob/master/src/sheets/sheets.module.ts"
    click SheetsService "https://github.com/ssilve1989/ulti-project/blob/master/src/sheets/sheets.service.ts"

    click FFLogsModule "https://github.com/ssilve1989/ulti-project/blob/master/src/fflogs/fflogs.module.ts"
    click FFLogsService "https://github.com/ssilve1989/ulti-project/blob/master/src/fflogs/fflogs.service.ts"
    click FFLogsSDK "https://github.com/ssilve1989/ulti-project/blob/master/src/fflogs/graphql/sdk.ts"

    click JobsModule "https://github.com/ssilve1989/ulti-project/blob/master/src/jobs/jobs.module.ts"
    click ClearChecker "https://github.com/ssilve1989/ulti-project/blob/master/src/jobs/clear-checker/clear-checker.job.ts"
    click InviteCleaner "https://github.com/ssilve1989/ulti-project/blob/master/src/jobs/invite-cleaner/invite-cleaner.job.ts"

    click RoleManagerModule "https://github.com/ssilve1989/ulti-project/blob/master/src/role-manager/role-manager.module.ts"
    click RoleManagerService "https://github.com/ssilve1989/ulti-project/blob/master/src/role-manager/role-manager.service.ts"

    click SentryModule "https://github.com/ssilve1989/ulti-project/blob/master/src/sentry/sentry.module.ts"

    %% Styles
    classDef internal fill:#f9f,stroke:#333,stroke-width:1px;
    classDef external fill:#bbf,stroke:#333,stroke-width:1px;
    classDef jobs fill:#bfb,stroke:#333,stroke-width:1px;
    classDef event fill:#ff9,stroke:#333,stroke-width:1px;
```
