diff --git a/src/components/navigation.ts b/src/components/navigation.ts index c9b8a8e..7ca4d6d 100644 --- a/src/components/navigation.ts +++ b/src/components/navigation.ts @@ -288,6 +288,11 @@ export const navigation = [ link: "/projects/umbrelle", badge: { text: "v1.0.0", variant: "tip" }, }, + { + label: "Veluna", + link: "/projects/veluna", + badge: { text: "v1.0.0", variant: "tip" }, + } ].sort((a, b) => a.label.localeCompare(b.label)), }, { diff --git a/src/content/docs/projects/veluna.md b/src/content/docs/projects/veluna.md new file mode 100644 index 0000000..2e68b8a --- /dev/null +++ b/src/content/docs/projects/veluna.md @@ -0,0 +1,229 @@ +--- +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 ` - Set the private channel where questions will be posted (admin only) +- `/answers ` - 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 \ No newline at end of file