feat: document veluna

2025-09-27 18:36:40 -07:00
parent 7962bbb710
commit ca6340b25f
2 changed files with 234 additions and 0 deletions
@@ -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)),
  },
  {
@@ -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 <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