From 6b482ec56781ecb1458bf21a029d08d54851ac69 Mon Sep 17 00:00:00 2001 From: Naomi Carrigan Date: Wed, 12 Nov 2025 20:27:00 -0800 Subject: [PATCH] feat: add project documentation for Saisoku, Tyche, and Vivicrea --- src/components/navigation.ts | 17 +- src/content/docs/projects/saisoku.md | 332 ++++++++++++++++ src/content/docs/projects/tyche.md | 495 ++++++++++++++++++++++++ src/content/docs/projects/vivicrea.md | 522 ++++++++++++++++++++++++++ 4 files changed, 1365 insertions(+), 1 deletion(-) create mode 100644 src/content/docs/projects/saisoku.md create mode 100644 src/content/docs/projects/tyche.md create mode 100644 src/content/docs/projects/vivicrea.md diff --git a/src/components/navigation.ts b/src/components/navigation.ts index 3eba3bd..a735390 100644 --- a/src/components/navigation.ts +++ b/src/components/navigation.ts @@ -631,7 +631,22 @@ export const navigation = [ label: "Sylvara", link: "/projects/sylvara", badge: { text: "unreleased", variant: "danger" }, - } + }, + { + label: "Saisoku", + link: "/projects/saisoku", + badge: { text: "v1.0.0", variant: "tip" }, + }, + { + label: "Tyche", + link: "/projects/tyche", + badge: { text: "v1.0.0", variant: "tip" }, + }, + { + label: "Vivicrea", + link: "/projects/vivicrea", + badge: { text: "v1.0.0", variant: "tip" }, + }, ].sort((a, b) => a.label.localeCompare(b.label)), }, { diff --git a/src/content/docs/projects/saisoku.md b/src/content/docs/projects/saisoku.md new file mode 100644 index 0000000..5159dc2 --- /dev/null +++ b/src/content/docs/projects/saisoku.md @@ -0,0 +1,332 @@ +--- +title: Saisoku +--- + +Saisoku (hereinafter the "Application") is a Discord bot designed to help users maintain productivity through hourly task reminders. The bot allows users to create reminders with either encouraging or bullying messages, providing customizable motivation styles to suit different preferences. + +## 1. User Documentation + +This section is for those interacting with a live instance of the Application. + +### Adding the Bot to Discord + +To use Saisoku, add it to Discord using the [official invite link](https://discord.com/oauth2/authorize?client_id=1438325099345346723). + +### Subscription Requirements + +Saisoku is a premium Discord bot that requires an active subscription to use. When your subscription lapses, you will stop receiving reminders until you restore it. + +### Creating a Reminder + +To create a reminder, use the `/reminder` slash command with the following options: + +- **task** (required): The task you want to be reminded about (maximum 50 characters) +- **bully** (required): Choose your motivation style: + - `true` - Receive bullying/harsh reminders + - `false` - Receive encouraging/supportive reminders + +**Example:** +``` +/reminder task:"Drink water" bully:false +``` + +### Reminder Limitations + +- You can have a maximum of **5 active reminders** at any time +- Reminders are sent **every hour at the top of the hour** +- Reminders are sent via **Discord Direct Messages** + +### Completing a Task + +When you receive a reminder, it will include a "Complete" button. Clicking this button will: +- Remove the reminder from your active list +- Send you a completion message (encouraging or bullying, matching your reminder style) +- Free up a slot for new reminders + +### Motivation Styles + +#### Encouraging Mode +When `bully` is set to `false`, you'll receive gentle, supportive reminders like: +- "Just a gentle reminder to start [task name]." +- "You've got this! Time for [task name]." +- "Be kind to your future self and handle [task name] now." + +#### Bullying Mode +When `bully` is set to `true`, you'll receive harsh, motivating reminders like: +- "Stop procrastinating and do [task name]." +- "Are you waiting for a written invitation to do [task name]?" +- "JUST DO [task name]!" + +#### Completion Messages + +The mode you set for a specific task will also determine the style of confirmation message you see when you complete said task. + +### Getting Help + +If you need assistance or have questions about the bot, you can: +- Visit the [support chat server](https://chat.nhcarrigan.com) +- Check the [documentation site](https://docs.nhcarrigan.com/) + +## 2. Technical Documentation + +This section is for those interested in running their own instance of the Application. + +### Prerequisites + +- Node.js (version compatible with the project) +- pnpm 10.20.0 or higher +- MongoDB database +- Discord Bot Token +- Discord Application with User Install capabilities + +### Technology Stack + +- **Language**: TypeScript +- **Runtime**: Node.js +- **Package Manager**: pnpm +- **Discord Library**: discord.js 14.24.2 +- **Web Server**: Fastify 5.6.2 +- **Database ORM**: Prisma 6.19.0 +- **Database**: MongoDB +- **Scheduler**: node-schedule 2.1.1 +- **Analytics**: @nhcarrigan/discord-analytics 0.0.6 + +### Project Structure + +``` +src/ +├── commands/ +│ └── reminder.ts # Discord slash command definition +├── config/ +│ ├── entitlements.ts # Entitled user IDs configuration +│ └── phrases.ts # Encouraging and bullying message phrases +├── modules/ +│ ├── completeTask.ts # Handles task completion interactions +│ ├── createReminder.ts # Handles reminder creation +│ ├── isEntitled.ts # Checks user subscription status +│ └── sendReminders.ts # Sends hourly reminders to users +├── server/ +│ └── serve.ts # Fastify web server for health/info page +├── utils/ +│ ├── getRandomValue.ts # Utility for selecting random phrases +│ └── logger.ts # Logging utility +└── index.ts # Application entry point +``` + +### Database Schema + +The application uses a single MongoDB collection: + +**Reminders** +- `id`: String (ObjectId) - Primary key +- `userId`: String - Discord user ID +- `reminder`: String - The task description +- `isHarsh`: Boolean - Whether to use bullying messages + +### Installation + +1. Clone the repository: +```bash +git clone https://git.nhcarrigan.com/nhcarrigan/saisoku.git +cd saisoku +``` + +2. Install dependencies: +```bash +pnpm install +``` + +3. Set up your environment variables (create a `prod.env` file): +``` +BOT_TOKEN=your_discord_bot_token +MONGO_URI=your_mongodb_connection_string +``` + +4. Set up the database: +```bash +pnpm exec prisma generate +``` + +5. Build the application: +```bash +pnpm run build +``` + +6. Start the application: +```bash +pnpm start +``` + +### Development + +For development, you can build the TypeScript code using: +```bash +pnpm run build +``` + +Run linting: +```bash +pnpm run lint +``` + +### Discord Bot Configuration + +The bot requires the following Discord configurations: + +1. **Integration Types**: User Install (`ApplicationIntegrationType.UserInstall`) +2. **Interaction Contexts**: + - Bot DMs + - Guild channels + - Private channels +3. **Required Intents**: None (the bot uses minimal intents) +4. **Commands**: Register the `/reminder` command using `src/commands/reminder.ts` + +### Entitlement System + +The bot implements Discord's subscription system. Users must have an active subscription to use the bot. The subscription is checked: +- When creating a reminder (in `src/modules/createReminder.ts:29`) +- When completing a task (in `src/modules/completeTask.ts:34`) +- Before sending reminders (in `src/modules/sendReminders.ts:43`) + +The SKU ID for the subscription is: `1438369555956105382` + +Additionally, specific user IDs can be hardcoded in `src/config/entitlements.ts` to grant free access. + +### Scheduling + +The bot uses `node-schedule` to send reminders at the top of every hour. The cron expression used is `"0 * * * *"` as defined in `src/index.ts:28`. + +### Web Server + +A Fastify web server runs on port 9100, serving: +- A landing page at `/` with information about the bot +- Health monitoring endpoint + +### Logging + +The application uses `@nhcarrigan/logger` for consistent logging throughout the codebase. Logs are output for: +- Client ready status +- Server startup +- Errors during server instantiation + +### Analytics + +The bot includes Discord analytics tracking via `@nhcarrigan/discord-analytics`, which starts a cron job when the client is ready (in `src/index.ts:26`). + +### Key Files Reference + +- **Entry Point**: `src/index.ts:1` - Main application bootstrapping +- **Reminder Creation**: `src/modules/createReminder.ts:23` - Handles `/reminder` command +- **Reminder Sending**: `src/modules/sendReminders.ts:23` - Hourly reminder dispatch +- **Task Completion**: `src/modules/completeTask.ts:28` - Processes completion buttons +- **Entitlement Check**: `src/modules/isEntitled.ts:16` - Validates subscriptions +- **Web Server**: `src/server/serve.ts:54` - HTTP server initialization +- **Phrases**: `src/config/phrases.ts:7` - All reminder and completion messages + +### Environment Variables + +Required environment variables: +- `BOT_TOKEN`: Discord bot token for authentication +- `MONGO_URI`: MongoDB connection string + +Note: The application uses `op run --env-file=prod.env` in the start script, indicating it uses 1Password CLI for secure environment variable management in production. + +## 3. Legal Documentation + +This section is for expansions to our legal policies specific to the Application. + +### Privacy Policy + +The Application collects and stores the following data: +- Discord user IDs +- Task descriptions (reminder text) +- User preference for message style (encouraging vs. bullying) + +For the complete privacy policy applicable to this application, please visit: https://docs.nhcarrigan.com/#/privacy + +### Terms of Service + +By using Saisoku, you agree to: +- Maintain an active subscription to continue receiving reminders +- The hourly reminder schedule (reminders sent at the top of each hour) +- A maximum of 5 concurrent reminders per user +- Receive reminders via Discord Direct Messages + +For the complete Terms of Service, please visit: https://docs.nhcarrigan.com/#/terms + +### Data Retention + +- Active reminders are stored in the database until marked as complete +- If a user cannot be found when sending a reminder, their reminder data is automatically deleted (as implemented in `src/modules/sendReminders.ts:36`) +- Users who let their subscription lapse will not receive reminders but their data is retained + +### License + +This software is licensed under Naomi's Public License. Copyright is held by Naomi Carrigan. + +For more information, see the LICENSE.md file in the repository. + +## 4. Contributing Documentation + +This section is for documentation related to contributing to the Application's codebase. + +### Getting Started + +For comprehensive contributing guidelines, please visit: https://docs.nhcarrigan.com/#/contributing + +### Code of Conduct + +Before interacting with the community or contributing, please read the Code of Conduct available in the repository at `CODE_OF_CONDUCT.md`. + +### Development Setup + +1. Fork the repository +2. Clone your fork locally +3. Install dependencies with `pnpm install` +4. Create a `.env` file with required environment variables +5. Run `pnpm run build` to compile TypeScript +6. Make your changes +7. Run `pnpm run lint` to check code style +8. Test your changes thoroughly +9. Submit a pull request + +### Code Style + +The project uses: +- `@nhcarrigan/eslint-config` version 5.2.0 for linting +- `@nhcarrigan/typescript-config` version 4.0.0 for TypeScript configuration +- Maximum 0 warnings policy (enforced in lint script) + +### Project Conventions + +- All source files include copyright headers +- Functions are documented with JSDoc comments +- Type safety is enforced throughout the codebase +- Error handling uses try-catch blocks with proper logging + +### Key Areas for Contribution + +1. **Phrase Library** (`src/config/phrases.ts`): Add new encouraging or bullying phrases +2. **Features**: Propose new reminder features or customization options +3. **Documentation**: Improve user or technical documentation +4. **Bug Fixes**: Address issues reported in the issue tracker +5. **Testing**: Add test coverage (currently minimal) + +### Submitting Changes + +When submitting a pull request: +1. Ensure all lint checks pass +2. Provide a clear description of changes +3. Reference any related issues +4. Test your changes with a live Discord bot instance if possible + +### Getting Help + +If you need help contributing: +- Visit the [support chat](https://chat.nhcarrigan.com) +- Check the [documentation](https://docs.nhcarrigan.com/) +- Review existing issues and pull requests for examples + +### Security + +If you discover a security vulnerability, please refer to `SECURITY.md` in the repository for responsible disclosure procedures. diff --git a/src/content/docs/projects/tyche.md b/src/content/docs/projects/tyche.md new file mode 100644 index 0000000..539bf96 --- /dev/null +++ b/src/content/docs/projects/tyche.md @@ -0,0 +1,495 @@ +--- +title: Tyche +--- + +Tyche (hereinafter the "Application") is a Discord bot designed to roll dice for tabletop gaming, role-playing games, and other scenarios requiring randomized results. The Application provides support for various dice types, modifiers, and advantage/disadvantage mechanics commonly used in tabletop gaming systems. + +## 1. User Documentation + +This section is for those interacting with a live instance of the Application. + +### Adding Tyche to Your Discord Server + +To add Tyche to your Discord server, use the following invite link: +https://discord.com/oauth2/authorize?client_id=1436837822656020663 + +The bot requires the following permissions: +- View Channels (to see where commands are used) +- Send Messages (to respond to commands) +- Use Application Commands (to register and respond to slash commands) + +### Using the Roll Command + +Tyche provides a single slash command: `/roll` + +#### Command Parameters + +1. **count** (required): How many dice to roll + - Type: Integer + - Range: 1-100 + - Example: `5` to roll 5 dice + +2. **die** (required): What kind of dice to roll + - Type: Choice + - Options: + - d2 (2-sided die) + - d3 (3-sided die) + - d4 (4-sided die) + - d6 (6-sided die) + - d8 (8-sided die) + - d10 (10-sided die) + - d12 (12-sided die) + - d20 (20-sided die) + - d100 (100-sided die/percentile) + +3. **type** (required): What type of roll to perform + - Type: Choice + - Options: + - Normal Roll: Standard dice roll + - Advantage Roll: Roll twice and take the higher result + - Disadvantage Roll: Roll twice and take the lower result + +4. **modifier** (optional): Numeric modifier to apply to the roll + - Type: Number + - Can be positive or negative + - Example: `5` adds +5 to the result, `-2` subtracts 2 from the result + +#### Command Examples + +1. **Simple Roll**: Roll a single d20 + ``` + /roll count:1 die:d20 type:Normal Roll + ``` + +2. **Multiple Dice**: Roll 3d6 (common for character stats) + ``` + /roll count:3 die:d6 type:Normal Roll + ``` + +3. **Roll with Modifier**: Roll 1d20+5 (attack roll with +5 bonus) + ``` + /roll count:1 die:d20 type:Normal Roll modifier:5 + ``` + +4. **Advantage Roll**: Roll 2d20 and take the higher result + ``` + /roll count:1 die:d20 type:Advantage Roll + ``` + +5. **Complex Roll**: Roll 2d6+3 with advantage + ``` + /roll count:2 die:d6 type:Advantage Roll modifier:3 + ``` + +#### Understanding Results + +The bot will respond with a breakdown of your roll: + +**Normal Roll Example:** +``` +Rolled 3d6+2: +4 + 3 + 5 +Modifier: +2 +Total: **14** +``` + +**Advantage/Disadvantage Roll Example:** +``` +Rolled 1d20+5 with advantage: +15 +18 +Modifier: +5 +Total: **23** +``` + +### Support and Feedback + +If you encounter issues or have questions: +- Visit the support server: https://chat.nhcarrigan.com +- Email: contact@nhcarrigan.com +- View the source code: https://git.nhcarrigan.com/nhcarrigan/tyche + +## 2. Technical Documentation + +This section is for those interested in running their own instance of the Application. + +### System Requirements + +- Node.js 24.10.0 or higher +- pnpm 10.20.0 (package manager) +- A Discord bot token (obtained from Discord Developer Portal) +- Optional: 1Password CLI for environment variable management + +### Architecture Overview + +Tyche is built with the following technologies: + +- **Discord.js 14.24.2**: Discord API interaction library +- **Fastify 5.6.1**: Web server for health monitoring +- **TypeScript 5.9.3**: Type-safe JavaScript development +- **@nhcarrigan/discord-analytics**: Bot analytics and monitoring +- **@nhcarrigan/logger**: Centralized logging system + +#### Project Structure + +``` +src/ +├── commands/ +│ └── roll.ts # Slash command definition for Discord API +├── modules/ +│ └── roll.ts # Core dice rolling logic +├── server/ +│ └── serve.ts # Fastify web server setup +├── utils/ +│ └── logger.ts # Logger configuration +└── index.ts # Application entry point +``` + +#### Key Components + +**Entry Point** (`src/index.ts:1`) +- Initializes Discord client with Guild intents +- Sets up analytics tracking +- Routes interactions to the roll handler +- Starts the web server + +**Roll Command Handler** (`src/modules/roll.ts:14`) +- Parses command options (count, die, modifier, type) +- Uses Node.js `crypto.randomInt()` for secure random number generation +- Implements three roll types: + - Normal: Single roll with optional modifier + - Advantage: Two rolls, uses higher result + - Disadvantage: Two rolls, uses lower result +- Formats and sends results back to Discord + +**Web Server** (`src/server/serve.ts:54`) +- Runs on port 8123 +- Serves a simple HTML landing page +- Provides health monitoring endpoint +- Includes links to source code, documentation, and support + +**Logger** (`src/utils/logger.ts:9`) +- Configured with bot name "Tyche" +- Supports remote logging via LOG_TOKEN +- Used throughout the application for debugging and error tracking + +### Installation + +1. Clone the repository: + ```bash + git clone https://git.nhcarrigan.com/nhcarrigan/tyche.git + cd tyche + ``` + +2. Install dependencies: + ```bash + pnpm install + ``` + +3. Set up environment variables: + Create a `prod.env` file with the following variables: + ``` + BOT_TOKEN=your_discord_bot_token + LOG_TOKEN=your_logging_token (optional) + ``` + +4. Build the TypeScript code: + ```bash + pnpm run build + ``` + +5. Register the slash command with Discord: + ```bash + node prod/commands/roll.js + ``` + This outputs the JSON needed to register the command via the Discord API. + +### Running the Application + +**Production Mode:** +```bash +pnpm start +``` + +This uses the 1Password CLI to load environment variables from `prod.env` and starts the bot. + +**Development Mode:** +```bash +pnpm run build +node prod/index.js +``` + +### Configuration + +#### Discord Bot Setup + +1. Create a new application at https://discord.com/developers/applications +2. Navigate to the "Bot" section and create a bot +3. Enable the following intents: + - Server Members Intent (if using analytics features) +4. Copy the bot token and add it to your `prod.env` file +5. Use the OAuth2 URL generator to create an invite link with: + - Scopes: `bot`, `applications.commands` + - Permissions: Send Messages, Use Application Commands + +#### Environment Variables + +- **BOT_TOKEN** (required): Discord bot token for authentication +- **LOG_TOKEN** (optional): Token for remote logging service + +### Deployment Considerations + +1. **Port Configuration**: The web server runs on port 8123 by default (hardcoded in `src/server/serve.ts:65`) + +2. **Security**: The bot uses Node.js's cryptographically secure `randomInt()` function for dice rolls + +3. **Rate Limiting**: Discord's built-in rate limiting applies to all interactions + +4. **Monitoring**: + - Web server provides a basic health check endpoint + - Analytics are tracked via @nhcarrigan/discord-analytics + - Logging can be centralized using the LOG_TOKEN + +5. **Scaling**: As a stateless bot, multiple instances can run behind a load balancer if needed + +### Development + +**Linting:** +```bash +pnpm run lint +``` + +Uses ESLint with @nhcarrigan/eslint-config and enforces zero warnings. + +**Testing:** +```bash +pnpm test +``` + +Note: Currently returns success without running tests (test suite not yet implemented). + +### API Reference + +#### Roll Module (`src/modules/roll.ts`) + +```typescript +export const roll = async(interaction: ChatInputCommandInteraction): Promise +``` + +**Parameters:** +- `interaction`: Discord.js ChatInputCommandInteraction object + +**Behavior:** +1. Extracts command options (count, die, modifier, type) +2. Generates random numbers using `crypto.randomInt(1, sides + 1)` +3. For advantage/disadvantage: generates two sets of rolls +4. Calculates total based on roll type +5. Applies modifier to final result +6. Sends formatted response to Discord + +**Roll Logic:** +- Normal: Sum all dice + modifier +- Advantage: Max(roll1_sum, roll2_sum) + modifier +- Disadvantage: Min(roll1_sum, roll2_sum) + modifier + +## 3. Legal Documentation + +This section is for expansions to our legal policies specific to the Application. + +### License + +Tyche is licensed under Naomi's Public License. The full license text can be found at: +https://docs.nhcarrigan.com/#/license + +Copyright is held by Naomi Carrigan. + +### Terms of Service + +The Application-specific terms of service extend the global terms found at: +https://docs.nhcarrigan.com/#/terms + +#### Data Collection + +Tyche collects the following data: +- Discord server IDs (for analytics) +- Command usage statistics (for analytics) +- User IDs (only when interacting with commands) + +#### Data Usage + +Data collected is used solely for: +- Bot analytics and monitoring +- Improving bot functionality +- Debugging and error tracking + +#### Data Retention + +- Command interaction data is processed in-memory and not permanently stored +- Analytics data follows the retention policy of @nhcarrigan/discord-analytics +- Logs may be retained for debugging purposes + +### Privacy Policy + +The Application-specific privacy policy extends the global policy found at: +https://docs.nhcarrigan.com/#/privacy + +#### User Data + +Tyche does not: +- Store message content +- Track individual user behavior across servers +- Share data with third parties +- Use data for advertising or marketing + +Tyche does: +- Process command inputs to generate dice roll results +- Collect aggregate usage statistics +- Log errors for debugging purposes + +#### Your Rights + +Users have the right to: +- Request information about data collection +- Request deletion of any stored data +- Opt-out by removing the bot from their server + +For data requests, contact: contact@nhcarrigan.com + +### Security Policy + +Security issues should be reported following the guidelines at: +[SECURITY.md](./SECURITY.md) + +Do not publicly disclose security vulnerabilities. Instead: +1. Email details to: contact@nhcarrigan.com +2. Include steps to reproduce the vulnerability +3. Allow reasonable time for a fix before public disclosure + +## 4. Contributing Documentation + +This section is for documentation related to contributing to the Application's codebase. + +### Contributing Guidelines + +Full contributing guidelines can be found at: +https://docs.nhcarrigan.com/#/contributing + +### Code of Conduct + +All contributors must adhere to the Code of Conduct found in: +[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) + +Key principles: +- Be respectful and inclusive +- Welcome newcomers +- Focus on constructive feedback +- No harassment or discriminatory behavior + +### Development Setup + +1. Fork the repository +2. Clone your fork locally +3. Install dependencies: `pnpm install` +4. Create a feature branch: `git checkout -b feature/your-feature-name` +5. Make your changes +6. Ensure code passes linting: `pnpm run lint` +7. Build the project: `pnpm run build` +8. Test your changes with a Discord bot token + +### Code Style + +The project uses: +- **ESLint**: @nhcarrigan/eslint-config (enforces zero warnings) +- **TypeScript**: @nhcarrigan/typescript-config +- **Formatting**: Follow existing code patterns + +Key conventions: +- Use TypeScript for all source files +- Include JSDoc comments for exported functions +- Copyright headers required on all source files: + ```typescript + /** + * @copyright nhcarrigan + * @license Naomi's Public License + * @author Naomi Carrigan + */ + ``` + +### Project Structure Conventions + +- **commands/**: Discord slash command definitions (for API registration) +- **modules/**: Business logic implementations +- **server/**: Web server and HTTP endpoints +- **utils/**: Shared utilities and helpers + +### Adding New Features + +When adding new features: + +1. **New Dice Commands**: Add to `src/commands/roll.ts` and update the logic in `src/modules/roll.ts` + +2. **New Commands**: + - Create command definition in `src/commands/` + - Create handler in `src/modules/` + - Register handler in `src/index.ts` + +3. **Server Endpoints**: Add routes in `src/server/serve.ts` + +4. **Tests**: While not currently implemented, tests should be added to validate new functionality + +### Pull Request Process + +1. Ensure your code builds without errors +2. Ensure linting passes with zero warnings +3. Update documentation if adding new features +4. Create a pull request with a clear description of changes +5. Link any related issues +6. Wait for review from maintainers + +### Testing Your Changes + +To test changes: + +1. Create a test Discord server +2. Create a test bot application in Discord Developer Portal +3. Use your test bot token in `prod.env` +4. Build and run the bot: `pnpm run build && node prod/index.js` +5. Test commands in your test server +6. Verify the web server loads at http://localhost:8123 + +### Reporting Issues + +When reporting bugs: +- Use GitHub Issues at the source repository +- Include steps to reproduce +- Include expected vs actual behavior +- Include relevant error messages or logs +- Specify your environment (Node version, OS, etc.) + +### Feature Requests + +Feature requests are welcome! Include: +- Clear description of the feature +- Use case explanation +- Why it would benefit users +- Any implementation suggestions + +### Getting Help + +For questions or support: +- Join the support server: https://chat.nhcarrigan.com +- Email: contact@nhcarrigan.com +- Review documentation: https://docs.nhcarrigan.com + +### Resources + +- Discord.js Documentation: https://discord.js.org/docs +- Discord Developer Portal: https://discord.com/developers/docs +- TypeScript Documentation: https://www.typescriptlang.org/docs +- Fastify Documentation: https://fastify.dev/docs + +--- + +**Documentation Version**: 1.0.0 +**Last Updated**: 2025-11-12 +**Application Version**: 0.0.0 diff --git a/src/content/docs/projects/vivicrea.md b/src/content/docs/projects/vivicrea.md new file mode 100644 index 0000000..cf30a2e --- /dev/null +++ b/src/content/docs/projects/vivicrea.md @@ -0,0 +1,522 @@ +--- +title: Vivicrea +--- + +Vivicrea (hereinafter the "Application") is a Discord bot that generates AI-powered anime-style images of a character named Naomi using Google's Gemini 2.5 Flash Image generation model. The bot, internally named "Nomena", responds to mentions in Discord servers and creates custom artwork based on a detailed character reference. + +## 1. User Documentation + +This section is for those interacting with a live instance of the Application. + +### 1.1 Overview + +Vivicrea is a specialized Discord bot designed to generate consistent, high-quality anime-style artwork of a specific character. The bot uses advanced AI image generation technology to create unique images while maintaining character consistency across all generated artwork. + +### 1.2 How to Use + +#### 1.2.1 Prerequisites + +- Access to a Discord server where the bot is installed +- Authorization from the bot owner (currently restricted to user ID: 465650873650118659) + +#### 1.2.2 Generating an Image + +1. **Mention the Bot**: Mention the bot in any channel where it has access + - The bot listens for direct mentions only (ignores @everyone, @here, and role mentions) + +2. **Wait for Response**: The bot will display a "typing" indicator while generating your image + +3. **Receive Your Image**: The generated image will be posted as a reply to your message + - Images are generated in 16:9 aspect ratio + - The character will be depicted with consistent features (shoulder-length wavy light dusty brown hair, light blue eyes, pink glasses, etc.) + - Each generation creates a unique pose, outfit, or setting + +#### 1.2.3 Access Restrictions + +Currently, the Application only accepts image generation requests from a single authorized user (Naomi). Other users will receive a polite message indicating the restriction: + +> "Sorry, I can only generate images for Naomi." + +This restriction is intentional and ensures the bot serves its primary purpose. + +### 1.3 Character Reference + +All generated images maintain the following character features: +- **Name**: Naomi +- **Hair**: Shoulder-length wavy light dusty brown hair +- **Eyes**: Light blue +- **Skin**: Very pale white +- **Accessories**: Pink glasses, pink teardrop earrings, pearl bracelet +- **Details**: Small vampire fangs, gentle smile, barefoot with pink nail polish +- **Style**: Anime-style full body art, clean, detailed, and vibrant + +### 1.4 Limitations + +- The bot only responds to mentions in channels it can access +- Image generation may take several seconds depending on API response times +- If image generation fails, the bot will respond with an error message +- No text should appear in generated images per the prompt specifications + +## 2. Technical Documentation + +This section is for those interested in running their own instance of the Application. + +### 2.1 Architecture + +The Application is built using the following technology stack: + +- **Runtime**: Node.js with TypeScript +- **Discord Framework**: discord.js v14.24.2 +- **AI Provider**: Google GenAI (@google/genai) v1.28.0 +- **Logging**: @nhcarrigan/logger v1.1.1 +- **Analytics**: @nhcarrigan/discord-analytics v0.0.6 +- **Web Server**: fastify v5.6.1 (included but not currently utilized) + +### 2.2 Project Structure + +``` +Vivicrea/ +├── src/ +│ ├── index.ts # Main application entry point +│ └── classes/ +│ └── ai.ts # AI image generation utility class +├── package.json # Project dependencies and scripts +├── tsconfig.json # TypeScript configuration +└── prod/ # Compiled JavaScript output (generated) +``` + +### 2.3 Prerequisites + +Before running the Application, ensure you have: + +- Node.js (version compatible with the dependencies) +- pnpm v10.19.0 (specified package manager) +- A Discord Bot Token +- A Google Gemini API Key (with access to gemini-2.5-flash-image model) +- A logging service token (for @nhcarrigan/logger) + +### 2.4 Installation + +1. **Clone the repository**: + ```bash + git clone + cd Vivicrea + ``` + +2. **Install dependencies**: + ```bash + pnpm install + ``` + +3. **Configure environment variables** (see section 2.5) + +4. **Build the project**: + ```bash + pnpm run build + ``` + +### 2.5 Configuration + +The Application requires three environment variables to be set: + +#### Required Environment Variables + +| Variable | Description | Example | +|----------|-------------|---------| +| `DISCORD_TOKEN` | Your Discord bot token from the Discord Developer Portal | `MTk4NjIyNDgzN...` | +| `GEMINI_API_KEY` | API key for Google Gemini with image generation access | `AIzaSy...` | +| `LOG_TOKEN` | Token for the logging service | `log_...` | + +#### Setting Environment Variables + +For production deployment, the Application uses 1Password's `op run` command with a `prod.env` file: + +```bash +op run --env-file=prod.env -- node prod/index.js +``` + +Alternatively, you can use a standard `.env` file or set environment variables directly in your deployment environment. + +### 2.6 Running the Application + +#### Development Mode + +```bash +# Build TypeScript files +pnpm run build + +# Run with environment variables +export DISCORD_TOKEN="your-token" +export GEMINI_API_KEY="your-key" +export LOG_TOKEN="your-log-token" +node prod/index.js +``` + +#### Production Mode + +```bash +# Using 1Password CLI +pnpm start + +# Or directly +node prod/index.js +``` + +### 2.7 Available Scripts + +| Script | Command | Description | +|--------|---------|-------------| +| `build` | `tsc` | Compiles TypeScript to JavaScript in the `prod/` directory | +| `lint` | `eslint src --max-warnings 0` | Runs ESLint with zero warnings tolerance | +| `start` | `op run --env-file=prod.env -- node prod/index.js` | Starts the bot in production mode with 1Password env management | +| `test` | `echo "Error: no test specified" && exit 0` | Placeholder (no tests currently implemented) | + +### 2.8 Discord Bot Setup + +1. **Create a Discord Application**: + - Visit the [Discord Developer Portal](https://discord.com/developers/applications) + - Click "New Application" and give it a name + - Navigate to the "Bot" section and create a bot + +2. **Configure Bot Settings**: + - Enable the following intents: + - Guilds + - Guild Messages + - Copy the bot token for the `DISCORD_TOKEN` environment variable + +3. **Generate Invite Link**: + - Navigate to the "OAuth2" > "URL Generator" section + - Select scopes: `bot` + - Select bot permissions: + - Read Messages/View Channels + - Send Messages + - Attach Files + - Copy the generated URL and use it to invite the bot to your server + +4. **Get Bot User ID**: + - In Discord, enable Developer Mode (Settings > Advanced > Developer Mode) + - Right-click your bot and select "Copy ID" + - Update the hardcoded bot ID in `src/index.ts:36` if needed + +### 2.9 Customization + +#### Modifying the Character Prompt + +The character description is defined in `src/classes/ai.ts:37`. To generate images of a different character: + +1. Edit the prompt string in the `generateImage()` method +2. Update the character reference URL if applicable +3. Rebuild the project with `pnpm run build` + +#### Changing Access Restrictions + +The user restriction is implemented in `src/index.ts:43`. To modify who can use the bot: + +1. Replace the hardcoded user ID `"465650873650118659"` with your target user ID +2. Or remove the restriction entirely to allow all users +3. Rebuild the project + +#### Image Configuration + +Image generation settings are configured in `src/classes/ai.ts:34-36`: + +- `aspectRatio`: Currently set to "16:9", can be modified to other supported ratios +- `model`: Currently uses "gemini-2.5-flash-image", can be updated to other Gemini models + +### 2.10 Troubleshooting + +#### Bot Not Responding + +1. Verify all environment variables are set correctly +2. Check that the bot has proper permissions in the Discord server +3. Ensure the bot mention is direct (not @everyone or @here) +4. Review logs for error messages + +#### Image Generation Failures + +1. Verify your Gemini API key has access to the image generation model +2. Check your API quota/rate limits +3. Review the error message returned by the bot +4. Inspect the application logs for detailed error information + +#### Build Errors + +1. Ensure you're using a compatible Node.js version +2. Verify all dependencies are installed: `pnpm install` +3. Check for TypeScript errors: `pnpm run lint` + +### 2.11 Monitoring and Logging + +The Application uses `@nhcarrigan/logger` for structured logging: + +- Bot startup events are logged at the "debug" level +- The logger requires a `LOG_TOKEN` environment variable +- Logs are identified with the service name "Nomena" + +### 2.12 Deployment Considerations + +- The Application maintains no persistent state (stateless) +- No database is required +- Environment variables should be securely managed (e.g., using 1Password, AWS Secrets Manager, etc.) +- Consider implementing rate limiting if opening access to multiple users +- Monitor API usage and costs for Google Gemini API calls + +## 3. Legal Documentation + +This section is for expansions to our legal policies specific to the Application. + +### 3.1 Applicable Policies + +The Application operates under the following legal framework maintained by NHCarrigan: + +- **Software License**: [Global Software License](https://docs.nhcarrigan.com/#/license) +- **Terms of Service**: [Terms of Service](https://docs.nhcarrigan.com/#/terms) +- **Privacy Policy**: [Privacy Policy](https://docs.nhcarrigan.com/#/privacy) +- **Code of Conduct**: Available in the repository + +All users, contributors, and operators of the Application are subject to these policies. + +### 3.2 Copyright and Ownership + +Copyright is held by Naomi Carrigan. + +The Application's source code is licensed under Naomi's Public License. Please refer to the [LICENSE.md](LICENSE.md) file and the global software license documentation for full terms. + +### 3.3 Data Processing + +#### 3.3.1 Discord Data + +The Application processes the following Discord data: +- Guild (server) information for bot operation +- Message content when the bot is mentioned +- User IDs for access control +- Channel IDs for sending responses + +#### 3.3.2 Third-Party Data Sharing + +The Application shares data with the following third-party services: + +1. **Discord**: Message content and attachments (generated images) +2. **Google Gemini API**: Character description prompts (no user-generated content is sent) +3. **Logging Service**: Application debug information and operational logs + +#### 3.3.3 Data Retention + +- The Application does not store message content or user data persistently +- All data processing is transient and in-memory only +- Generated images are delivered via Discord and not stored by the Application +- Logs may be retained according to the logging service's retention policy + +### 3.4 Generated Content Rights + +All images generated by the Application are created using Google's Gemini AI model. Users should refer to Google's terms of service regarding AI-generated content ownership and usage rights. + +The character design and reference used in the prompts are the intellectual property of Naomi Carrigan. + +### 3.5 API Usage and Compliance + +Operators of the Application are responsible for: +- Complying with Discord's Terms of Service and Developer Terms +- Complying with Google's Gemini API Terms of Service +- Maintaining valid API keys and not exceeding rate limits +- Ensuring proper attribution when required by service providers + +### 3.6 Modifications to Legal Policies + +The legal policies linked in this documentation may be updated by NHCarrigan from time to time. Users and operators should periodically review the linked policies for any changes. + +## 4. Contributing Documentation + +This section is for documentation related to contributing to the Application's codebase. + +### 4.1 General Contributing Guidelines + +All contributions to the Application must follow the general contributing guidelines available at: +[https://docs.nhcarrigan.com/#/contributing](https://docs.nhcarrigan.com/#/contributing) + +Please review these guidelines thoroughly before submitting any contributions. + +### 4.2 Code of Conduct + +Before interacting with the project or community, please read and agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). + +### 4.3 Development Environment Setup + +1. **Fork and clone the repository**: + ```bash + git clone https://github.com/your-username/Vivicrea.git + cd Vivicrea + ``` + +2. **Install dependencies**: + ```bash + pnpm install + ``` + +3. **Create a development environment file** with your test credentials + +4. **Make your changes** following the project's coding standards + +### 4.4 Coding Standards + +The project uses the following code quality tools: + +#### 4.4.1 ESLint + +- Configuration: `@nhcarrigan/eslint-config` v5.2.0 +- Run linting: `pnpm run lint` +- Zero warnings policy: All ESLint warnings must be resolved + +#### 4.4.2 TypeScript + +- Configuration: `@nhcarrigan/typescript-config` v4.0.0 +- TypeScript version: 5.9.3 +- All code must be properly typed (no `any` types without justification) + +#### 4.4.3 Code Style + +- Follow the existing code style in the project +- Use clear, descriptive variable and function names +- Add JSDoc comments for all classes and public methods +- Include copyright headers on new files: + ```typescript + /** + * @copyright NHCarrigan + * @license Naomi's Public License + * @author Naomi Carrigan + */ + ``` + +### 4.5 Project Structure Guidelines + +When adding new features: + +- **Classes**: Place utility classes in `src/classes/` +- **Naming**: Use PascalCase for classes, camelCase for functions and variables +- **Imports**: Use ES modules syntax with `.js` extensions (for TypeScript module resolution) +- **Async**: Use async/await for asynchronous operations + +### 4.6 Testing + +Currently, the project does not have a test suite implemented. When contributing: + +- Manually test your changes thoroughly +- Test with a development Discord bot instance +- Verify the bot responds correctly to mentions +- Ensure image generation works as expected + +Future contributions to add a testing framework would be welcome. + +### 4.7 Submitting Contributions + +#### 4.7.1 Pull Request Process + +1. **Create a feature branch**: + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** following the coding standards + +3. **Run linting**: + ```bash + pnpm run lint + ``` + +4. **Build the project**: + ```bash + pnpm run build + ``` + +5. **Commit your changes** with clear, descriptive commit messages + +6. **Push to your fork**: + ```bash + git push origin feature/your-feature-name + ``` + +7. **Open a Pull Request** on GitHub with: + - A clear title describing the change + - A detailed description of what was changed and why + - Any relevant issue numbers + - Screenshots or examples if applicable + +#### 4.7.2 Pull Request Guidelines + +- Keep PRs focused on a single feature or fix +- Update documentation if adding new features +- Ensure all ESLint checks pass +- Respond to review feedback promptly +- Be respectful and professional in all interactions + +### 4.8 Issue Reporting + +When reporting bugs or requesting features: + +1. **Check existing issues** to avoid duplicates +2. **Use descriptive titles** that summarize the issue +3. **Provide detailed information**: + - Steps to reproduce (for bugs) + - Expected behavior + - Actual behavior + - Environment details (Node version, OS, etc.) + - Error messages or logs +4. **Be patient** - maintainers will respond as soon as possible + +### 4.9 Areas for Contribution + +The following areas would benefit from community contributions: + +#### 4.9.1 High Priority + +- Implement a test suite (unit and integration tests) +- Add error handling improvements +- Implement rate limiting for image generation +- Add configuration file support (vs. hardcoded values) + +#### 4.9.2 Medium Priority + +- Utilize the Fastify dependency for health check endpoints +- Add metrics and monitoring instrumentation +- Implement slash commands in addition to mentions +- Add queue system for image generation requests + +#### 4.9.3 Low Priority + +- Add support for multiple characters +- Implement image history/gallery features +- Add customization options for image generation parameters +- Create a web dashboard for configuration + +### 4.10 Getting Help + +If you need help with contributing: + +- Review the [NHCarrigan documentation](https://docs.nhcarrigan.com) +- Open a GitHub issue with your question +- Contact via [Chat Server](http://chat.nhcarrigan.com) +- Email: contact@nhcarrigan.com + +### 4.11 Security Vulnerabilities + +If you discover a security vulnerability: + +- **DO NOT** open a public issue +- Review the [SECURITY.md](SECURITY.md) file for reporting procedures +- Contact the maintainer privately +- Allow time for the vulnerability to be addressed before public disclosure + +### 4.12 Recognition + +Contributors will be recognized in the following ways: +- GitHub contribution history +- Potential inclusion in project acknowledgments +- Community recognition and thanks + +Thank you for your interest in contributing to Vivicrea! + +--- + +**Documentation Version**: 1.0.0 +**Last Updated**: 2025-11-12 +**Maintained By**: Naomi Carrigan