Zipbot Discord Bot Development

You are helping maintain and develop Zipbot, a Discord bot built with Discord.js v13 that manages reactions, quotes, and user engagement tracking.

Project Architecture

Bot Capabilities

Command System Structure

Commands are registered in a `Collection` in `src/index.ts` and implement the `Command<T>` interface:

```typescript

interface Command<T> {

data: any; // Command metadata (name, description, type)

execute: (interaction: T) => Promise<void>;

}

```

**Three Command Types:**

1. `Command<Message>` - Message-based (e.g., `react.ts`)

2. `Command<CommandInteraction>` - Slash commands (e.g., `quote.ts`, `leaderboard.ts`)

3. `Command<ContextMenuInteraction>` - Context menu (e.g., `highlight.ts`)

Event Handling Flow

The entry point (`src/index.ts`) handles three Discord events:

Development Workflow

Running the Bot

```bash

Development with hot reload

npm run start:dev

Build TypeScript

npm run build

Production (runs compiled code from dist/)

npm start

```

Database Operations

```bash

Generate Prisma client after schema.prisma changes

npm run prisma:generate

Apply migrations to production

npm run prisma:migrate

Create and apply migration in development

npx prisma migrate dev

Open database GUI

npx prisma studio

```

Docker Deployment

```bash

docker-compose up # Starts app with PostgreSQL

```

Database Schema & Patterns

Core Models

Critical Pattern: connectOrCreate

**ALWAYS use Prisma's `connectOrCreate` pattern** to handle first-time users/channels and prevent duplicate key errors:

```typescript

user: {

connectOrCreate: {

create: { id: author.id, name: author.username },

where: { id: author.id }

}

}

```

This pattern is used in all commands that interact with users or channels.

Command Implementations

react.ts (Auto-triggered)

highlight.ts (Context Menu)

- Non-bot author

- Text channel only

- No duplicate messageId

quote.ts (Slash Command)

- Author ("Wisdom Dispenser")

- Submitter ("Inscriptor of History")

- Permalink to original message

leaderboard.ts (Slash Command)

Environment Configuration

Required environment variables (see `.env.example`):

Key Files Reference

| File | Purpose |

|------|---------|

| `src/index.ts` | Main entry point, event handlers, command registration |

| `src/prisma.ts` | Singleton PrismaClient with conditional logging |

| `src/constants.ts` | REACTIONS array, embed colors, leaderboard emojis |

| `src/types.d.ts` | Command interface and type definitions |

| `prisma/schema.prisma` | Database schema |

Best Practices When Modifying Code

1. **New Commands:** Always implement the `Command<T>` interface matching the interaction type

2. **Database Queries:** Use `connectOrCreate` for any user/channel/guild relationships

3. **Schema Changes:** Run `npm run prisma:generate` after modifying `schema.prisma`

4. **Environment:** Test locally with `npm run start:dev` before deployment

5. **Migrations:** Use `npx prisma migrate dev` with descriptive names

6. **Caching:** Consider cache invalidation for data that changes frequently (see leaderboard.ts)

7. **Validation:** Always validate message context (channel type, author type) before database operations

8. **Error Handling:** Wrap database operations in try/catch and provide user-friendly error messages

Common Tasks

Adding a New Command

1. Create file in `src/commands/`

2. Implement `Command<T>` interface

3. Register in command Collection in `src/index.ts`

4. Use `connectOrCreate` for any user/guild/channel references

Modifying Database Schema

1. Edit `prisma/schema.prisma`

2. Run `npx prisma migrate dev --name descriptive_name`

3. Run `npm run prisma:generate`

4. Update TypeScript types if needed

Adding New Reactions

1. Add image URL to REACTIONS array in `src/constants.ts`

2. Test with a message containing "unzip"