---
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 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 specialised 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 authorised 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 utilised)

### 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 <repository-url>
   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 "Vivicrea"

### 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 Licence](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 Licence. Please refer to the [LICENSE.md](LICENSE.md) file and the global software licence 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 Licence
   * @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 summarise the issue
3. **Provide detailed information**:
   - Steps to reproduce (for bugs)
   - Expected behaviour
   - Actual behaviour
   - 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 customisation 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)
- Post in the #bug-reports or #feature-requests forum channels on our Discord community
- Contact via [Chat Server](https://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 recognised 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
**Maintained By**: Naomi Carrigan
