docs/src/content/docs/projects/altaria.md

title

title
Altaria

Altaria (hereinafter the "Application") is a Discord bot that provides gentle reminders to users when they upload images without alt-text descriptions, promoting accessibility and inclusion within Discord communities.

1. User Documentation

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

What is Altaria?

Altaria is a friendly Discord bot designed to encourage the use of alt-text (alternative text) for images in Discord servers. Alt-text helps make content accessible to users who rely on screen readers and assistive technologies.

How to Add Altaria to Your Server

1. Use the official invitation link: Add to Discord
2. Select your server from the dropdown menu
3. Grant the necessary permissions:
   • Read Messages/View Channels
   • Send Messages
   • Use Slash Commands

How Altaria Works

• Automatic Monitoring: Altaria monitors messages in channels where it has permissions
• Image Detection: When someone posts an image without alt-text, Altaria detects it automatically
• Gentle Reminders: The bot responds with one of 100 carefully crafted, encouraging messages
• Educational Links: Each reminder includes helpful resources about adding alt-text and writing descriptions

Using Slash Commands

Altaria supports slash commands that provide information about the bot:

• Type / and select an Altaria command to learn more about the bot's features and purpose

Reminder Message Categories

Altaria's reminders fall into five themed categories:

1. Gentle Encouragement (20 messages) - Soft, supportive reminders
2. Playful/Cute (20 messages) - Fun, anime-inspired messages with emoticons
3. Educational (20 messages) - Informative content about accessibility
4. Community Vibes (20 messages) - Emphasising collective responsibility
5. Thematic/Fantasy (20 messages) - Creative, story-driven reminders

Getting Help

If you need assistance:

• Join the support server: Discord Server
• Review Discord's guide: How to add alt-text
• Use Cordelia for AI-generated descriptions: Cordelia

2. Technical Documentation

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

Architecture Overview

Altaria is built using:

• Node.js with TypeScript
• Discord.js v14.21.0 for Discord API interaction
• Fastify v5.5.0 for the web server
• @nhcarrigan/logger for structured logging

Project Structure

src/
├── index.ts                 # Main application entry point
├── modules/
│   └── checkAltText.ts     # Core alt-text detection logic
├── config/
│   ├── blocks.ts           # Discord UI blocks configuration
│   └── reminders.ts        # Collection of reminder messages
├── utils/
│   ├── errorHandler.ts     # Error handling utilities
│   ├── logger.ts          # Logger configuration
│   └── getRandomValue.ts  # Random selection utility
└── server/
    └── serve.ts           # Web server for health checks

Core Functionality

Alt-Text Detection (src/modules/checkAltText.ts:16)

• Filters messages for image attachments
• Identifies images without descriptions
• Sends randomized gentle reminders with educational resources

Random Reminder Selection (src/utils/getRandomValue.ts:15)

• Securely selects random messages using Node.js crypto module
• Ensures variety in user experience

Web Server (src/server/serve.ts:54)

• Provides health monitoring endpoint on port 6022
• Serves informational landing page with bot details

Installation Requirements

• Node.js (compatible with ES modules)
• pnpm package manager v10.14.0+
• TypeScript 5.9.2+

Environment Variables

• BOT_TOKEN: Discord bot token (required)
• LOG_TOKEN: Logging service token (optional)

Development Setup

1. Clone the repository
2. Install dependencies: pnpm install
3. Create environment file with required tokens
4. Build: pnpm run build
5. Start: pnpm start

Deployment

• Production deployment uses 1Password CLI: op run --env-file=./prod.env -- node prod/index.js
• Web server runs on port 6022 for health monitoring
• Supports process monitoring and logging

API Endpoints

• GET /: Landing page with bot information and invite link
• Health check endpoint for monitoring services

3. Legal Documentation

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

License

This software is licensed under Naomi's Public Licence. Full details available at: https://docs.nhcarrigan.com/#/license

Copyright

Copyright held by Naomi Carrigan (@nhcarrigan).

Privacy Considerations

• Altaria only processes message content to detect image attachments
• No message content or user data is stored permanently
• Bot interactions are logged for debugging purposes only
• Complies with Discord's Terms of Service and Developer Policy

Data Processing

• Message Scanning: Bot analyses messages in real-time for image attachments
• Temporary Processing: Message data is processed only for alt-text detection
• No Data Retention: No user messages or personal data are stored
• Logging: Error logs may contain anonymized debugging information

Terms of Use

By adding Altaria to your Discord server, you agree to:

• Allow the bot to read messages in authorised channels
• Accept that the bot will send reminder messages about alt-text
• Understand that the bot promotes accessibility and inclusion

4. Contributing Documentation

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

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Install dependencies: pnpm install
4. Read the Contributing Guidelines
5. Review the Code of Conduct

Development Workflow

1. Create a feature branch from main
2. Make your changes following the coding standards
3. Run linting: pnpm run lint
4. Build the project: pnpm run build
5. Test your changes thoroughly
6. Submit a Pull Request

Code Style Guidelines

• TypeScript: Strict typing enabled
• ESLint: Uses @nhcarrigan/eslint-config with max 0 warnings
• Formatting: Consistent code style enforced
• Comments: JSDoc comments for functions and modules
• Error Handling: Comprehensive error handling with UUID tracking

Adding New Reminder Messages

To add new reminder messages to src/config/reminders.ts:9:

1. Choose an appropriate category (gentle, playful, educational, community, thematic)
2. Follow the existing tone and length guidelines
3. Include accessibility-focused messaging
4. Test that messages display correctly in Discord
5. Maintain the current array structure

Testing Guidelines

• Test Discord interactions manually in a development server
• Verify alt-text detection works for various image types
• Ensure reminder messages display correctly
• Test web server endpoints

Submission Requirements

• All code must pass linting without warnings
• Changes should include appropriate JSDoc documentation
• Pull requests must include a clear description of changes
• Follow existing patterns and conventions

Contact for Contributors

• Discord: Chat Server
• Email: contact@nhcarrigan.com
• Issues: Post in the #bug-reports or #feature-requests forum channels on our Discord community

Recognition

Contributors will be recognised in future releases and project documentation as appropriate.