# faruuza/bot architecture

> Architecture diagram of the GitHub repository faruuza/bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faruuza/bot
- Repository: https://github.com/faruuza/bot

## Overview

This is a Discord hackathon management bot. Participants open a registration ticket, submit team details through interactive Discord controls, and the bot creates team records and provisions private team channels and roles; invitations and recruitment manage later membership changes. Separate branches cover reconnect role restoration, support tickets, staff dashboards and controls, FAQ editing, challenge synchronization, and auditing. The README documents these capabilities; sampled source confirms selected service and routing relationships, so unsampled wiring is not expanded.

Main entry points: [`src/index.js`](https://github.com/faruuza/bot/blob/main/src/index.js) (Bot client), [`src/services/ticketService.js`](https://github.com/faruuza/bot/blob/main/src/services/ticketService.js) (Ticket provisioning), [`src/events/interactionCreate.js`](https://github.com/faruuza/bot/blob/main/src/events/interactionCreate.js) (Interaction router), [`src/services/teamService.js`](https://github.com/faruuza/bot/blob/main/src/services/teamService.js) (Team lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Discord runtime"]
  node_client["Bot client<br/>[index.js]"]
  node_interactions["Interaction router"]
  node_member_join["Join restoration<br/>[guildMemberAdd.js]"]
end

subgraph group_teams["Team lifecycle"]
  node_registration["Registration command<br/>[register.js]"]
  node_team_command["Team commands<br/>[team.js]"]
  node_team_service["Team lifecycle<br/>[teamService.js]"]
  node_discord_service["Discord provisioning<br/>[discordService.js]"]
  node_invitation["Invitations"]
  node_recruitment["Recruitment and challenges"]
end

subgraph group_operations["Staff and support"]
  node_ticket_service["Ticket provisioning<br/>[ticketService.js]"]
  node_guild_config["Guild configuration"]
  node_dashboard["Admin dashboard"]
  node_faq["FAQ management<br/>[faqService.js]"]
  node_admin_commands["Admin commands<br/>[setup.js]"]
  node_faq_command["FAQ command<br/>[faq.js]"]
  node_ticket_command["Ticket close<br/>[close.js]"]
end

subgraph group_persistence["Data and audit"]
  node_audit["Audit dispatcher<br/>[auditService.js]"]
  node_db_pool[("PostgreSQL pool<br/>[pool.js]")]
  node_team_queries["Team and member records<br/>[teamQueries.js]"]
  node_ticket_queries["Ticket records<br/>[ticketQueries.js]"]
  node_recruit_queries["Recruitment records"]
  node_faq_queries["FAQ records<br/>[faqQueries.js]"]
  node_audit_queries["Audit records<br/>[auditQueries.js]"]
end

node_discord(("Discord users"))
node_discord_service_external{{"Discord platform"}}
node_postgres[("PostgreSQL")]
node_nasa{{"NASA challenge site"}}

node_discord -->|"sends interactions"| node_client
node_client -->|"dispatches events"| node_interactions
node_client -->|"dispatches joins"| node_member_join
node_client -->|"registers command"| node_registration
node_client -->|"registers command"| node_team_command
node_interactions -->|"opens tickets"| node_ticket_service
node_interactions -->|"handles team actions"| node_team_service
node_interactions -->|"handles recruitment"| node_recruitment
node_registration -->|"provisions ticket"| node_ticket_service
node_team_command -->|"manages teams"| node_team_service
node_team_service -->|"reads and writes"| node_team_queries
node_team_service -->|"provisions roles"| node_discord_service
node_team_service -->|"manages invitations"| node_invitation
node_discord_service -->|"creates resources"| node_discord_service_external
node_invitation -->|"updates membership"| node_team_queries
node_recruitment -->|"reads teams"| node_team_queries
node_recruitment -->|"updates vacancies"| node_recruit_queries
node_recruitment -.->|"syncs challenge data"| node_nasa
node_member_join -->|"restores membership"| node_team_queries
node_member_join -->|"restores roles"| node_discord_service
node_ticket_service -->|"reads and writes"| node_ticket_queries
node_ticket_service -->|"creates channels"| node_discord_service_external
node_ticket_service -->|"logs closure"| node_audit
node_client -->|"registers command"| node_admin_commands
node_admin_commands -->|"sets up dashboard"| node_dashboard
node_dashboard -->|"reads settings"| node_guild_config
node_dashboard -->|"fetches guild state"| node_discord_service_external
node_interactions -->|"reads settings"| node_guild_config
node_client -->|"registers command"| node_faq_command
node_faq_command -->|"edits FAQ"| node_faq
node_faq -->|"reads and writes"| node_faq_queries
node_client -->|"registers command"| node_ticket_command
node_ticket_command -->|"closes ticket"| node_ticket_service
node_audit -->|"persists events"| node_audit_queries
node_audit -->|"dispatches log embeds"| node_discord_service_external
node_db_pool -->|"connects"| node_postgres

click node_client "https://github.com/faruuza/bot/blob/main/src/index.js"
click node_interactions "https://github.com/faruuza/bot/blob/main/src/events/interactionCreate.js"
click node_member_join "https://github.com/faruuza/bot/blob/main/src/events/guildMemberAdd.js"
click node_registration "https://github.com/faruuza/bot/blob/main/src/commands/registration/register.js"
click node_ticket_service "https://github.com/faruuza/bot/blob/main/src/services/ticketService.js"
click node_team_command "https://github.com/faruuza/bot/blob/main/src/commands/team/team.js"
click node_team_service "https://github.com/faruuza/bot/blob/main/src/services/teamService.js"
click node_discord_service "https://github.com/faruuza/bot/blob/main/src/services/discordService.js"
click node_invitation "https://github.com/faruuza/bot/blob/main/src/services/invitationService.js"
click node_recruitment "https://github.com/faruuza/bot/blob/main/src/services/nasaValidationService.js"
click node_guild_config "https://github.com/faruuza/bot/blob/main/src/services/guildConfigService.js"
click node_dashboard "https://github.com/faruuza/bot/blob/main/src/services/dashboardService.js"
click node_faq "https://github.com/faruuza/bot/blob/main/src/services/faqService.js"
click node_admin_commands "https://github.com/faruuza/bot/blob/main/src/commands/admin/setup.js"
click node_faq_command "https://github.com/faruuza/bot/blob/main/src/commands/admin/faq.js"
click node_ticket_command "https://github.com/faruuza/bot/blob/main/src/commands/ticket/close.js"
click node_audit "https://github.com/faruuza/bot/blob/main/src/services/auditService.js"
click node_db_pool "https://github.com/faruuza/bot/blob/main/src/database/pool.js"
click node_team_queries "https://github.com/faruuza/bot/blob/main/src/database/queries/teamQueries.js"
click node_ticket_queries "https://github.com/faruuza/bot/blob/main/src/database/queries/ticketQueries.js"
click node_recruit_queries "https://github.com/faruuza/bot/blob/main/src/database/queries/recruitmentQueries.js"
click node_faq_queries "https://github.com/faruuza/bot/blob/main/src/database/queries/faqQueries.js"
click node_audit_queries "https://github.com/faruuza/bot/blob/main/src/database/queries/auditQueries.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_interactions,node_member_join,node_discord toneBlue
class node_registration,node_team_command,node_team_service,node_discord_service,node_invitation,node_recruitment,node_postgres toneAmber
class node_ticket_service,node_guild_config,node_dashboard,node_faq,node_admin_commands,node_faq_command,node_ticket_command toneMint
class node_audit,node_db_pool,node_team_queries,node_ticket_queries,node_recruit_queries,node_faq_queries,node_audit_queries toneRose
class node_discord_service_external,node_nasa toneIndigo
```

## Components

### Discord runtime

- [Bot client](https://github.com/faruuza/bot/blob/main/src/index.js): `src/index.js`
- [Interaction router](https://github.com/faruuza/bot/blob/main/src/events/interactionCreate.js): `src/events/interactionCreate.js`
- [Join restoration](https://github.com/faruuza/bot/blob/main/src/events/guildMemberAdd.js): `src/events/guildMemberAdd.js`

### Team lifecycle

- [Registration command](https://github.com/faruuza/bot/blob/main/src/commands/registration/register.js): `src/commands/registration/register.js`
- [Team commands](https://github.com/faruuza/bot/blob/main/src/commands/team/team.js): `src/commands/team/team.js`
- [Team lifecycle](https://github.com/faruuza/bot/blob/main/src/services/teamService.js): `src/services/teamService.js`
- [Discord provisioning](https://github.com/faruuza/bot/blob/main/src/services/discordService.js): `src/services/discordService.js`
- [Invitations](https://github.com/faruuza/bot/blob/main/src/services/invitationService.js): `src/services/invitationService.js`
- [Recruitment and challenges](https://github.com/faruuza/bot/blob/main/src/services/nasaValidationService.js): `src/services/nasaValidationService.js`

### Staff and support

- [Ticket provisioning](https://github.com/faruuza/bot/blob/main/src/services/ticketService.js): `src/services/ticketService.js`
- [Guild configuration](https://github.com/faruuza/bot/blob/main/src/services/guildConfigService.js): `src/services/guildConfigService.js`
- [Admin dashboard](https://github.com/faruuza/bot/blob/main/src/services/dashboardService.js): `src/services/dashboardService.js`
- [FAQ management](https://github.com/faruuza/bot/blob/main/src/services/faqService.js): `src/services/faqService.js`
- [Admin commands](https://github.com/faruuza/bot/blob/main/src/commands/admin/setup.js): `src/commands/admin/setup.js`
- [FAQ command](https://github.com/faruuza/bot/blob/main/src/commands/admin/faq.js): `src/commands/admin/faq.js`
- [Ticket close](https://github.com/faruuza/bot/blob/main/src/commands/ticket/close.js): `src/commands/ticket/close.js`

### Data and audit

- [Audit dispatcher](https://github.com/faruuza/bot/blob/main/src/services/auditService.js): `src/services/auditService.js`
- [PostgreSQL pool](https://github.com/faruuza/bot/blob/main/src/database/pool.js): `src/database/pool.js`
- [Team and member records](https://github.com/faruuza/bot/blob/main/src/database/queries/teamQueries.js): `src/database/queries/teamQueries.js`
- [Ticket records](https://github.com/faruuza/bot/blob/main/src/database/queries/ticketQueries.js): `src/database/queries/ticketQueries.js`
- [Recruitment records](https://github.com/faruuza/bot/blob/main/src/database/queries/recruitmentQueries.js): `src/database/queries/recruitmentQueries.js`
- [FAQ records](https://github.com/faruuza/bot/blob/main/src/database/queries/faqQueries.js): `src/database/queries/faqQueries.js`
- [Audit records](https://github.com/faruuza/bot/blob/main/src/database/queries/auditQueries.js): `src/database/queries/auditQueries.js`

### Other components

- **Discord users**
- **Discord platform**
- **PostgreSQL**
- **NASA challenge site**

## Connections

- Discord users → Bot client: sends interactions
- Bot client → Interaction router: dispatches events
- Bot client → Join restoration: dispatches joins
- Bot client → Registration command: registers command
- Bot client → Team commands: registers command
- Interaction router → Ticket provisioning: opens tickets
- Interaction router → Team lifecycle: handles team actions
- Interaction router → Recruitment and challenges: handles recruitment
- Registration command → Ticket provisioning: provisions ticket
- Team commands → Team lifecycle: manages teams
- Team lifecycle → Team and member records: reads and writes
- Team lifecycle → Discord provisioning: provisions roles
- Team lifecycle → Invitations: manages invitations
- Discord provisioning → Discord platform: creates resources
- Invitations → Team and member records: updates membership
- Recruitment and challenges → Team and member records: reads teams
- Recruitment and challenges → Recruitment records: updates vacancies
- Recruitment and challenges → NASA challenge site: syncs challenge data
- Join restoration → Team and member records: restores membership
- Join restoration → Discord provisioning: restores roles
- Ticket provisioning → Ticket records: reads and writes
- Ticket provisioning → Discord platform: creates channels
- Ticket provisioning → Audit dispatcher: logs closure
- Bot client → Admin commands: registers command
- Admin commands → Admin dashboard: sets up dashboard
- Admin dashboard → Guild configuration: reads settings
- Admin dashboard → Discord platform: fetches guild state
- Interaction router → Guild configuration: reads settings
- Bot client → FAQ command: registers command
- FAQ command → FAQ management: edits FAQ
- FAQ management → FAQ records: reads and writes
- Bot client → Ticket close: registers command
- Ticket close → Ticket provisioning: closes ticket
- Audit dispatcher → Audit records: persists events
- Audit dispatcher → Discord platform: dispatches log embeds
- PostgreSQL pool → PostgreSQL: connects