---
title: Veluna
---

Veluna (hereinafter the "Application") is a Discord bot that allows communities to ask administrators anonymous questions and receive public answers, facilitating open communication while maintaining user privacy.

## 1. User Documentation

This section is for those interacting with a live instance of the Application.

### Getting Started

Veluna enables anonymous question-and-answer interactions within Discord servers. Community members can ask questions privately, and server administrators can respond publicly.

### Available Commands

- `/about` - Display information about Veluna and how to use it
- `/ask` - Open a modal to submit an anonymous question (available to all users)
- `/questions <channel>` - Set the private channel where questions will be posted (admin only)
- `/answers <channel>` - Set the public channel where answers will be published (admin only)

### How It Works

1. **Setup**: Server administrators must configure two channels:
   - A private **questions channel** where submitted questions appear (for moderation)
   - A public **answers channel** where responses are published (for community visibility)

2. **Asking Questions**: Any server member can use `/ask` to submit anonymous questions up to 1000 characters

3. **Answering**: Administrators can respond to questions, and answers will be posted to the configured public channel

### Permissions

- **All Users**: Can ask questions using `/ask`
- **Server Administrators**: Can configure channels and answer questions (requires "Manage Guild" permission)

### Bot Permissions Required

Veluna needs the following permissions in configured channels:
- View Channel
- Send Messages
- Embed Links

### Support

If you encounter issues, reach out through:
- [Discord Support Server](https://chat.nhcarrigan.com)
- [Documentation Portal](https://docs.nhcarrigan.com/)

## 2. Technical Documentation

This section is for those interested in running their own instance of the Application.

### System Requirements

- Node.js with TypeScript support
- MongoDB database
- Discord Bot Token
- 1Password CLI (for production secrets management)

### Architecture

Veluna is built with:
- **Discord.js v14** - Discord API interaction
- **Fastify** - Web server for health monitoring
- **Prisma** - Database ORM with MongoDB
- **TypeScript** - Type-safe development

### Database Schema

```prisma
model Servers {
  id                String   @id @default(auto()) @map("_id") @db.ObjectId
  serverId          String   @unique
  questionChannelId String   @default("")
  answerChannelId   String   @default("")
  blockedUsers      String[] @default([])
}
```

### Project Structure

```
src/
├── components/     # Discord UI components
│   └── about.ts   # About command interface
├── interfaces/    # TypeScript type definitions
│   └── veluna.ts  # Core application types
├── modals/        # Discord modal forms
│   ├── ask.ts     # Question submission modal
│   └── answer.ts  # Answer submission modal
├── modules/       # Event handlers
│   ├── handleButton.ts      # Button interaction handler
│   ├── handleChatCommand.ts # Slash command handler
│   └── handleModalSubmit.ts # Modal submission handler
├── server/        # Web server
│   └── serve.ts   # Health monitoring endpoint
├── utils/         # Utilities
│   └── logger.ts  # Logging functionality
└── index.ts       # Application entry point
```

### Installation & Setup

1. **Dependencies**:
   ```bash
   pnpm install
   ```

2. **Database Setup**:
   - Set up MongoDB instance
   - Configure `MONGO_URI` environment variable

3. **Discord Bot**:
   - Create Discord application at https://discord.com/developers/applications
   - Generate bot token and set `BOT_TOKEN` environment variable

4. **Build**:
   ```bash
   pnpm run build
   ```

5. **Development**:
   ```bash
   pnpm run lint  # Code linting
   ```

6. **Production**:
   ```bash
   pnpm run start  # Uses 1Password for secret management
   ```

### Environment Variables

- `BOT_TOKEN` - Discord bot authentication token
- `MONGO_URI` - MongoDB connection string

### Health Monitoring

The application includes a Fastify web server on port 6099 that serves:
- Root endpoint `/` - Basic information page with invite link
- Health monitoring capabilities

### Bot Invite URL

The bot can be invited with this URL:
```
https://discord.com/oauth2/authorize?client_id=1391505285465509978
```

## 3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

### Licensing

- **Copyright**: NHCarrigan
- **License**: Naomi's Public License
- **Author**: Naomi Carrigan

### Data Handling

Veluna stores minimal data:
- Server configurations (question/answer channel IDs)
- Server IDs for configuration persistence
- Blocked user lists (when implemented)

No message content or user personal information is stored permanently.

### Privacy Considerations

- Questions are submitted anonymously - the bot does not store or reveal question authors
- Only server administrators can see submitted questions in the private channel
- Answers are posted publicly in the configured channel

## 4. Contributing Documentation

This section is for documentation related to contributing to the Application's codebase.

### Development Standards

- **TypeScript**: Strict typing required
- **ESLint**: Zero warnings policy (`pnpm run lint`)
- **Code Style**: Follow existing patterns and conventions

### Code Organization

- Event handlers are modularized in `/modules`
- UI components are separated in `/components` and `/modals`
- Database interactions use Prisma ORM
- Logging uses structured logger utility

### Key Functions

- `handleChatCommand()` - Processes slash commands in `src/modules/handleChatCommand.ts:39`
- `handleModalSubmit()` - Processes modal form submissions
- `handleButton()` - Processes button interactions
- `instantiateServer()` - Starts web server in `src/server/serve.ts:54`

### Adding New Commands

1. Add command logic to `handleChatCommand()`
2. Create any required modals in `/modals`
3. Add UI components in `/components` if needed
4. Update database schema if persistence is required

### Testing

Currently no automated tests are configured (`echo "Error: no test specified" && exit 0`).

### Building

The build process:
1. Generates Prisma client
2. Compiles TypeScript to JavaScript
3. Outputs to `prod/` directory

### Git Workflow

- Main branch: `main`
- Repository appears to follow standard GitHub flow
- Commits should be descriptive and focused

### Code Style Guidelines

- Use existing ESLint configuration (`@nhcarrigan/eslint-config`)
- Follow TypeScript best practices
- Maintain consistent indentation and formatting
- Document functions with JSDoc comments where appropriate