nhcarrigan/docs
2
0
Fork 0
generated from nhcarrigan/template
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add product documentation (#8)
Some checks failed
Code Analysis / SonarQube (push) Failing after 15s
Details
Node.js CI / Lint and Test (push) Successful in 51s
Details

Browse Source 
### Explanation

Finally.

### Issue

_No response_

### Attestations

- [ ] I have read and agree to the [Code of Conduct](https://docs.nhcarrigan.com/community/coc/)
- [ ] I have read and agree to the [Community Guidelines](https://docs.nhcarrigan.com/community/guide/).
- [ ] My contribution complies with the [Contributor Covenant](https://docs.nhcarrigan.com/dev/covenant/).

### Dependencies

- [ ] I have pinned the dependencies to a specific patch version.

### Style

- [ ] I have run the linter and resolved any errors.
- [ ] My pull request uses an appropriate title, matching the conventional commit standards.
- [ ] My scope of feat/fix/chore/etc. correctly matches the nature of changes in my pull request.

### Tests

- [ ] My contribution adds new code, and I have added tests to cover it.
- [ ] My contribution modifies existing code, and I have updated the tests to reflect these changes.
- [ ] All new and existing tests pass locally with my changes.
- [ ] Code coverage remains at or above the configured threshold.

### Documentation

_No response_

### Versioning

_No response_

Reviewed-on: #8
Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Co-committed-by: Naomi Carrigan <commits@nhcarrigan.com>
This commit is contained in:
Naomi Carrigan
2025-07-06 18:04:44 -07:00
committed by Naomi Carrigan
parent c461453342
commit 31d7273061
20 changed files with 4101 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.cspell.json
View File

@ -34,7 +34,37 @@
"Musicolet"
],
"words": [
"Abalise",
"atproto",
"Becca",
"Beccalia",
"CCPA",
"Celestine",
"Čeština",
"Dansk",
"Fediverse",
"polycule"
"Français",
"Gitea",
"Hikari",
"Italiano",
"Iuvo",
"Lietuvių",
"Lyria",
"Mommy",
"Nederlands",
"Polski",
"polycule",
"Română",
"Rosalia",
"Sakura",
"Suomi",
"Svenska",
"Taryne",
"Türkçe",
"Ελληνικά",
"Български",
"Русский",
"Українська",
"हिन्दी"
]
}

93
src/components/navigation.ts
View File

@ -119,6 +119,91 @@ export const navigation = [
link: "/projects/eslint-config",
badge: { text: "v5.1.0", variant: "tip" },
},
{
label: "Aria Iuvo",
link: "/projects/aria-iuvo",
badge: { text: "v1.2.0", variant: "tip" },
},
{
label: "Becca Lyria",
link: "/projects/becca-lyria",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Naomi's Blog",
link: "/projects/blog",
badge: { text: "v0.1.0", variant: "caution" },
},
{
label: "Celestine",
link: "/projects/celestine",
badge: { text: "v1.3.0", variant: "tip" },
},
{
label: "Cordelia Taryne",
link: "/projects/cordelia-taryne",
badge: { text: "v1.1.0", variant: "tip" },
},
{
label: "Gwen Abalise",
link: "/projects/gwen-abalise",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Hikari",
link: "/projects/hikari",
badge: { text: "v0.0.0", variant: "danger" },
},
{
label: "Maylin Taryne",
link: "/projects/maylin-taryne",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Melody Iuvo",
link: "/projects/melody-iuvo",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Mommy Bot",
link: "/projects/mommy-bot",
badge: { text: "v0.0.0", variant: "danger" },
},
{
label: "Mommy",
link: "/projects/mommy",
badge: { text: "v0.0.0", variant: "danger" },
},
{
label: "NHCarrigan Portfolio",
link: "/projects/portfolio",
badge: { text: "unversioned", variant: "success" },
},
{
label: "Logger",
link: "/projects/logger",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Resume",
link: "/projects/resume",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Rosalia Nightsong",
link: "/projects/rosalia-nightsong",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Static Pages",
link: "/projects/static-pages",
badge: { text: "unversioned", variant: "success" },
},
{
label: "Website Headers",
link: "/projects/website-headers",
badge: { text: "v2.1.0", variant: "tip" },
},
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
@ -140,14 +225,14 @@ export const navigation = [
{
label: "Managing Local Music",
link: "/misc/music",
}
]
},
],
},
{
label: "Sitemap",
link: "https://sitemap.nhcarrigan.com",
attrs: {
target: "_blank",
}
}
},
},
];

319
src/content/docs/projects/aria-iuvo.md Normal file
View File

@ -0,0 +1,319 @@
---
title: Aria Iuvo
---
Aria Iuvo (hereinafter the "Application") is a Discord bot designed to provide seamless message translation capabilities using LibreTranslate. The bot allows users to translate Discord messages to their preferred language through an intuitive right-click context menu interface. Developed by NHCarrigan, Aria Iuvo supports over 25 languages and offers both free and premium functionality through Discord's subscription system.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Getting Started
To use Aria Iuvo, [add the bot to your Discord account](https://discord.com/oauth2/authorize?client_id=1338596130207957035) using the provided authorization link. The bot operates as a user-installable application, meaning it can be used across any Discord server or direct message where you have access.
### Core Features
#### Message Translation
- **Context Menu Access**: Right-click on any message, select "Apps", then choose "Translate Message"
- **Automatic Language Detection**: The bot automatically detects the source language of the message
- **User Locale Targeting**: Messages are translated to your Discord interface language
- **Confidence Reporting**: Translation results include the detection confidence percentage
#### About Command
- Use the `/about` slash command to view bot information
- Displays current version, commit hash, and helpful links
- Available in 25+ languages matching your Discord locale
#### Premium Features
- **Subscription Required**: Message translation requires an active premium subscription
- **Subscription Management**: Use the premium button in bot responses to manage subscriptions
### Supported Languages
Aria Iuvo supports translation between the following languages:
- English (en)
- Spanish (es)
- French (Français)
- German (Deutsch)
- Italian (Italiano)
- Portuguese (pt)
- Russian (Русский)
- Chinese Simplified (zh)
- Chinese Traditional (zt)
- Japanese (日本語)
- Korean (한국어)
- Dutch (Nederlands)
- Polish (Polski)
- Czech (Čeština)
- Danish (Dansk)
- Swedish (Svenska)
- Finnish (Suomi)
- Greek (Ελληνικά)
- Bulgarian (Български)
- Romanian (Română)
- Hungarian (Magyar)
- Lithuanian (Lietuvių)
- Ukrainian (Українська)
- Turkish (Türkçe)
- Thai (ไทย)
- Hindi (हिन्दी)
- Indonesian (Bahasa Indonesia)
### Error Handling
- **No Message Content**: The bot will notify you if the selected message contains no translatable text
- **Unsupported Language**: If your locale isn't supported, you'll receive a notification
- **Network Issues**: Connection problems are logged and users receive error notifications
- **Rate Limiting**: The bot handles API rate limits gracefully
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### System Architecture
Aria Iuvo is built using modern TypeScript and Node.js technologies with the following key components:
#### Core Technologies
- **Runtime**: Node.js with ES modules
- **Language**: TypeScript with strict configuration
- **Discord Library**: discord.js v14+
- **Translation Service**: LibreTranslate API
- **Web Framework**: Fastify (for health monitoring)
- **Package Manager**: pnpm
#### Project Structure
```
src/
├── index.ts # Main entry point and Discord client setup
├── commands/ # Slash command definitions
│ ├── about.ts # About command configuration
│ └── translate.ts # Context menu command configuration
├── modules/ # Core functionality implementations
│ ├── about.ts # About command logic
│ ├── translate.ts # Translation processing logic
│ └── getLocale.ts # Locale resolution utilities
├── config/ # Configuration files
│ └── locales.ts # Supported locales and mappings
├── i18n/ # Internationalization
│ └── responses.ts # Localized response strings
├── server/ # Web server components
│ └── serve.ts # Health monitoring server
└── utils/ # Utility functions
├── i18n.ts # Translation utilities
├── logger.ts # Logging functionality
└── replyToError.ts # Error response handling
```
### Environment Setup
#### Required Environment Variables
```bash
DISCORD_TOKEN=your_discord_bot_token
TRANSLATE_TOKEN=your_libretranslate_api_key
```
#### Installation Steps
1. Clone the repository
2. Install dependencies: `pnpm install`
3. Configure environment variables
4. Build the project: `pnpm run build`
5. Start the application: `pnpm run start`
#### Development Workflow
- **Linting**: `pnpm run lint` (ESLint with @nhcarrigan/eslint-config)
- **Testing**: `pnpm run test` (Vitest with coverage)
- **Building**: `pnpm run build` (TypeScript compilation)
### API Integration
#### LibreTranslate Service
- **Detection Endpoint**: `https://trans.nhcarrigan.com/detect`
- **Translation Endpoint**: `https://trans.nhcarrigan.com/translate`
- **Authentication**: API key-based authentication
- **Request Format**: URL-encoded form data
#### Discord Integration
- **Application Type**: User-installable bot
- **Interaction Types**: Message context menus, slash commands
- **Permission Model**: Minimal intents required (no message content access)
- **Premium Integration**: Discord's SKU-based subscription system
### Monitoring and Health Checks
#### Web Server
- **Port**: 5001
- **Endpoint**: `/` (serves HTML status page)
- **Framework**: Fastify with logging disabled
- **Purpose**: Health monitoring and basic bot information
#### Logging System
- **Error Handling**: Comprehensive error logging with structured data
- **Process Monitoring**: Unhandled rejection and exception tracking
- **Subscription Events**: User subscription/unsubscription logging
### Deployment Considerations
#### Production Requirements
- Node.js 22+ runtime environment
- Access to LibreTranslate API service
- Discord bot token with appropriate permissions
- Environment variable management (1Password integration shown)
#### Scaling Considerations
- Stateless design enables horizontal scaling
- Rate limiting handled at API level
- Minimal memory footprint due to no message caching
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### Licensing
Aria Iuvo is licensed under Naomi's Public License, as referenced in the global software license documentation available at [docs.nhcarrigan.com](https://docs.nhcarrigan.com/#/license).
### Data Handling
#### Message Processing
- **Temporary Processing**: Messages are sent to LibreTranslate for translation only
- **No Storage**: The bot does not store or cache message content
- **Ephemeral Responses**: All bot responses are ephemeral (only visible to the requesting user)
#### User Data
- **Minimal Collection**: Only Discord user IDs and locale preferences are processed
- **Subscription Data**: Premium subscription status is managed through Discord's system
- **No Personal Information**: No additional personal data is collected or stored
#### Third-Party Services
- **LibreTranslate**: Message content is temporarily sent to LibreTranslate for processing
- **Discord**: All interactions are governed by Discord's Terms of Service and Privacy Policy
### Copyright and Attribution
- **Copyright Holder**: Naomi Carrigan (nhcarrigan)
- **Source Code**: Available at [git.nhcarrigan.com/nhcarrigan/aria-iuvo](https://git.nhcarrigan.com/nhcarrigan/aria-iuvo)
- **Attribution**: Uses LibreTranslate for translation services
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Environment
#### Prerequisites
- Node.js 22 or higher
- pnpm package manager
- Git version control
- TypeScript knowledge
- Discord.js familiarity
#### Code Standards
- **Linting**: ESLint with @nhcarrigan/eslint-config
- **Type Safety**: Strict TypeScript configuration
- **Testing**: Vitest with coverage requirements
- **Documentation**: JSDoc comments for all public functions
### Contribution Workflow
#### Getting Started
1. Fork the repository
2. Create a feature branch from main
3. Set up development environment
4. Make your changes following code standards
5. Run tests and linting
6. Submit a pull request
#### Code Style Guidelines
- **Naming Conventions**: camelCase for variables, PascalCase for types
- **File Organization**: Logical separation by functionality
- **Import Style**: ES modules with explicit extensions
- **Error Handling**: Comprehensive try-catch blocks with logging
#### Internationalization (i18n)
##### Adding New Languages
1. Add locale to `supportedLocales` array in `config/locales.ts`
2. Add mapping if needed in `mappedLocales` object
3. Add translations to `responses` object in `i18n/responses.ts`
4. Update command localizations in `commands/` files
##### Translation Structure
```typescript
[Locale.NewLanguage]: {
"button": {
code: "Source Code Translation",
support: "Help Translation",
},
"command-error": "Error message translation",
"embed": {
commit: "Commit translation",
description: "Bot description translation",
title: "About title translation",
version: "Version translation",
},
"no-message-content": "No content message translation",
"subscription-required": "Subscription required translation",
"translation": "Translation format string",
"unsupported-locale": "Unsupported locale translation",
}
```
### Testing Guidelines
#### Test Structure
- **Unit Tests**: Located in `test/` directory
- **Coverage Requirements**: Maintained through Vitest
- **Locale Testing**: Verify i18n functionality
- **Integration Testing**: Test Discord interaction flows
#### Running Tests
```bash
# Run all tests with coverage
pnpm run test
# Run tests in watch mode (development)
npx vitest --watch
# Check test coverage
npx vitest run --coverage
```
### Bug Reports and Feature Requests
#### Issue Templates
- **Bug Reports**: Include steps to reproduce, expected vs actual behavior
- **Feature Requests**: Describe use case, proposed implementation
- **Translation Issues**: Specify locale and incorrect translation
#### Communication Channels
- **Issues**: GitHub/Git repository issue tracker
- **Support**: [chat.nhcarrigan.com](https://chat.nhcarrigan.com)
- **Email**: contact@nhcarrigan.com
### Release Process
#### Version Management
- **Semantic Versioning**: Following semver conventions
- **Changelog**: Maintained for all releases
- **Git Tags**: Version tags for release tracking
#### Deployment Pipeline
- **Build Verification**: All tests must pass
- **Linting Check**: No linting errors allowed
- **Type Checking**: TypeScript compilation must succeed
- **Manual Testing**: Discord integration verification
### Documentation Standards
#### Code Documentation
- **JSDoc**: All public functions and complex logic
- **README**: Project overview and quick start guide
- **CONTRIBUTING**: Detailed contribution guidelines
- **This Document**: Comprehensive application documentation
#### Maintenance
- **Regular Updates**: Documentation updated with code changes
- **Accuracy**: All examples and instructions verified
- **Accessibility**: Clear language and structured formatting

212
src/content/docs/projects/becca-lyria.md Normal file
View File

@ -0,0 +1,212 @@
---
title: Becca Lyria
---
Becca Lyria (hereinafter the "Application") is an AI-powered Discord bot that provides an interactive text-based role-playing game experience through direct messages. The bot utilizes Anthropic's Claude AI to create dynamic, personalized RPG adventures for users.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Overview
Becca Lyria is a user-installable Discord bot that transforms your DMs into an immersive text-based RPG experience. Acting as a wise mage named Becca with a cold and calculating personality, the bot serves as your personal dungeon master, weaving interactive stories that adapt to your choices and actions.
### Getting Started
1. **Installation**: [Add Becca Lyria to your Discord account](https://discord.com/oauth2/authorize?client_id=1343341112437248041)
2. **Subscription**: The bot requires an active subscription to use its features
3. **Start Playing**: Use the `/start` command to begin your adventure
### Available Commands
- **`/start`** - Start a new RPG scenario. Becca will create a fresh adventure and send it to your DMs
- **`/about`** - Learn more about the bot, including version information and useful links
- **`/clear`** - Clear your current adventure history to start fresh
### How to Play
1. Send Becca a `/start` command to begin a new adventure
2. Once the story begins in your DMs, simply respond naturally to continue the narrative
3. The bot maintains conversation history (up to 20 messages) to provide context-aware responses
4. Use `/clear` to reset your adventure history when you want to start over
5. The bot supports free-form text adventures - you can attempt any action you can imagine
### Features
- **AI-Powered Storytelling**: Powered by Claude 3.5 Sonnet for rich, dynamic narratives
- **Conversation Memory**: Maintains context from recent messages for coherent storytelling
- **Free-Form Gameplay**: No restrictive multiple choice options - express your actions naturally
- **Personalized Experience**: The bot adapts to your playstyle and incorporates your Discord display name
- **Privacy-Focused**: All gameplay happens in private DMs
### Subscription Model
Becca Lyria operates on a premium subscription model through Discord's monetization system. Users must have an active subscription to access the bot's RPG features.
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture Overview
Becca Lyria is built as a modern Discord bot using TypeScript and several key technologies:
**Core Technologies:**
- **Node.js/TypeScript**: Main runtime and development language
- **Discord.js**: Discord API interaction library
- **Anthropic SDK**: Integration with Claude AI models
- **Fastify**: Web server for health monitoring
- **PNPM**: Package management
**AI Integration:**
- **Provider**: Anthropic Claude (claude-3-5-sonnet-latest for conversations, claude-sonnet-4-20250514 for story starts)
- **Context Management**: Maintains up to 20 messages of conversation history
- **Personality System**: Configurable personality traits for consistent character behavior
### Project Structure
```
src/
├── index.ts # Main entry point and Discord client setup
├── commands/ # Slash command definitions
│ ├── about.ts
│ ├── clear.ts
│ └── start.ts
├── config/
│ └── personality.ts # AI personality configuration
├── events/
│ └── message.ts # Direct message event handling
├── modules/ # Command implementation logic
│ ├── about.ts
│ ├── clear.ts
│ └── start.ts
├── server/
│ └── serve.ts # Health monitoring web server
└── utils/ # Utility functions
├── ai.ts # Anthropic client configuration
├── calculateCost.ts # Usage cost tracking
├── isSubscribed.ts # Subscription verification
├── logger.ts # Logging utility
└── replyToError.ts # Error handling
```
### Environment Variables
The application requires several environment variables:
- `DISCORD_TOKEN`: Discord bot token
- `AI_TOKEN`: Anthropic API key
- `LOG_TOKEN`: Logging service token (optional)
### Key Features Implementation
**Subscription System:**
- Integrates with Discord's premium features
- SKU ID: `1343347225698500744`
- Entitlement checking for both interactions and messages
- Special bypass for bot owner (ID: `465650873650118659`)
**Conversation Management:**
- Fetches last 20 messages from DM channel
- Supports history clearing with special `<Clear History>` marker
- Converts message history to Anthropic's message format
- Maintains role context (user vs assistant)
**Error Handling:**
- Comprehensive error logging with custom logger
- Graceful error responses to users
- Unhandled rejection and exception catching
**Cost Tracking:**
- Monitors AI usage with token counting
- Calculates costs based on Anthropic pricing (input: $3/1M tokens, output: $15/1M tokens)
- Logs usage statistics per user
### Development Setup
1. **Prerequisites**: Node.js, PNPM
2. **Installation**: `pnpm install`
3. **Build**: `pnpm run build`
4. **Development**: Configure environment variables in `dev.env`
5. **Production**: Configure environment variables in `prod.env`
6. **Start**: `pnpm start` (requires 1Password CLI for env injection)
### Deployment Considerations
- Web server runs on port 5010 for health checks
- Requires Discord bot permissions for DMs and message content
- Needs stable Anthropic API access
- Logging integration with nhcarrigan logging service
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### Data Processing
Your conversation history is transmitted to Anthropic AI for processing and response generation. The content of your messages may be retained by them for model improvement.
### Subscription Model
Becca operates as a paid service with a $5/month subscription fee per Discord server. This subscription model ensures:
- Sustainable development and maintenance
- Priority support for subscribers
- Regular feature updates and improvements
- Infrastructure costs coverage
### Service Availability
- Best-effort uptime with monitoring systems
- Planned maintenance notifications
- Support through designated Discord server
- Community-driven feedback and feature requests
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Standards
**Code Quality:**
- TypeScript with strict configuration
- ESLint with @nhcarrigan/eslint-config
- Maximum function length limits enforced
- Comprehensive JSDoc documentation required
**Testing:**
- Vitest framework configured
- Istanbul coverage reporting
- Currently no tests implemented (placeholder exists)
**Licensing:**
- Licensed under Naomi's Public License
- Copyright held by Naomi Carrigan
- See LICENSE.md for full terms
### Contribution Process
1. **Issues**: Report bugs and request features through GitHub issues
2. **Pull Requests**: Fork, develop, and submit PRs for review
3. **Code Review**: All changes require review before merging
4. **Guidelines**: Follow established [contributing guidelines](CONTRIBUTING.md)
5. **Conduct**: Adhere to [Code of Conduct](CODE_OF_CONDUCT.md)
### Development Workflow
**Commands:**
- `pnpm run build`: Compile TypeScript to production JavaScript
- `pnpm run lint`: Run ESLint with zero warnings tolerance
- `pnpm run test`: Run test suite (currently placeholder)
- `pnpm start`: Start production build with environment injection
**Architecture Patterns:**
- Event-driven Discord bot architecture
- Modular command system with separate definition and implementation
- Utility-first approach for common functionality
- Separation of concerns between commands, events, and business logic
### Contact Information
- **Chat Server**: [http://chat.nhcarrigan.com](http://chat.nhcarrigan.com)
- **Email**: contact@nhcarrigan.com
- **Source Code**: [https://git.nhcarrigan.com/nhcarrigan/becca-lyria](https://git.nhcarrigan.com/nhcarrigan/becca-lyria)
- **Documentation**: [https://docs.nhcarrigan.com/](https://docs.nhcarrigan.com/)

144
src/content/docs/projects/blog.md Normal file
View File

@ -0,0 +1,144 @@
---
title: Naomi's Blog
---
Naomi's Blog (hereinafter the "Application") is a personal blog platform built with Next.js that showcases the personal musings of a transfem software engineer. The Application serves markdown-based blog posts with a clean, accessible interface and focuses on storytelling and technical experiences.
## 1. User Documentation
### Overview
Naomi's Blog is a personal blog featuring posts about software engineering, technology, and personal experiences. The blog is accessible at https://blog.nhcarrigan.com and provides a clean, minimalist interface for reading articles.
### Navigation
- **Home Page**: Displays a chronological list of all blog posts with titles, publication dates, and summaries
- **Individual Posts**: Click on any post title to read the full article
- **Return Navigation**: Each post page includes a "← Back to home" link to return to the main listing
### Post Structure
Each blog post includes:
- **Title**: The main heading of the article
- **Publication Date**: Displayed in British format (e.g., "Wednesday, 21 May 2025")
- **Summary**: A brief excerpt visible on the home page
- **Content**: Full markdown-rendered content with support for:
- Headers and text formatting
- Links and images
- Code blocks and syntax highlighting
- HTML elements when needed
### Accessibility Features
- Semantic HTML structure with proper heading hierarchy
- Underlined links for clear navigation
- Clean typography using Inter font
- Responsive design that works across devices
## 2. Technical Documentation
### Architecture
Naomi's Blog is built using:
- **Framework**: Next.js 15.1.6 with App Router
- **Language**: TypeScript 5.x
- **Styling**: Tailwind CSS with custom CSS variables
- **Content**: Markdown files with frontmatter parsing via gray-matter
- **Markdown Rendering**: react-markdown with rehype-raw and remark-gfm plugins
### Project Structure
```
src/
├── app/
│ ├── layout.tsx # Root layout with metadata and styling
│ ├── page.tsx # Home page listing all posts
│ ├── globals.css # Global styles and CSS variables
│ └── post/[slug]/
│ └── page.tsx # Dynamic post pages
├── components/
│ └── rule.tsx # Custom horizontal rule component
└── lib/
└── posts.ts # Post data fetching utilities
posts/ # Markdown blog posts
```
### Installation & Setup
1. **Prerequisites**: Node.js and pnpm package manager
2. **Install dependencies**: `pnpm install`
3. **Development server**: `pnpm dev` (runs on port 3003)
4. **Build for production**: `pnpm build`
5. **Start production server**: `pnpm start`
### Content Management
- **Adding Posts**: Create `.md` files in the `posts/` directory
- **Frontmatter Format**:
```yaml
---
title: "Your Post Title"
date: "YYYY-MM-DD"
summary: "Brief description of the post"
---
```
- **Content**: Write in Markdown with GitHub Flavoured Markdown support
- **Automatic Processing**: Posts are automatically sorted by date (newest first)
### Key Features
- **Static Generation**: Posts are processed at build time for optimal performance
- **SEO Optimized**: Proper metadata, Open Graph, and Twitter Card support
- **TypeScript**: Full type safety throughout the application
- **Responsive Design**: Mobile-friendly layout
- **Custom Styling**: Branded colors and typography
## 3. Legal Documentation
### License
The Application is distributed under **Naomi's Public License** as indicated in the source code headers.
### Copyright
All source code is copyright © nhcarrigan (Naomi Carrigan).
### Third-Party Dependencies
The Application uses the following open-source libraries:
- **Next.js**: MIT License
- **React**: MIT License
- **TypeScript**: Apache License 2.0
- **Tailwind CSS**: MIT License
- **gray-matter**: MIT License
- **react-markdown**: MIT License
- **rehype-raw**: MIT License
- **remark-gfm**: MIT License
### Content Policy
Blog post content represents the personal opinions and experiences of the author. Content guidelines and policies specific to this Application may be added here as needed.
## 4. Contributing Documentation
### Development Guidelines
- **Code Style**: ESLint configuration (`@nhcarrigan/eslint-config`) enforces consistent formatting
- **Type Safety**: All code must pass TypeScript checks with no warnings
- **Testing**: Run `pnpm lint` to verify code standards (note: test suite is pending implementation)
### Code Organization
- **Components**: React components go in `src/components/`
- **Utilities**: Helper functions belong in `src/lib/`
- **Pages**: Follow Next.js App Router conventions in `src/app/`
- **Styles**: Global styles in `src/app/globals.css`, component styles via Tailwind classes
### Pull Request Process
1. **Fork & Branch**: Create feature branches from main
2. **Code Quality**: Ensure ESLint passes with zero warnings
3. **Type Safety**: All TypeScript must compile without errors
4. **Documentation**: Update relevant documentation for significant changes
5. **Testing**: Verify the application builds and runs correctly
### File Header Requirements
All source files must include the standard copyright header:
```typescript
/**
* @copyright nhcarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
*/
```
### Dependency Management
- Use `pnpm` for package management
- Keep dependencies up to date and security-focused
- Prefer established, well-maintained packages
- Document any new dependencies and their purpose

303
src/content/docs/projects/celestine.md Normal file
View File

@ -0,0 +1,303 @@
---
title: Celestine
---
Celestine (hereinafter the "Application") is a comprehensive paid moderation bot for Discord servers, built with TypeScript and Discord.js. The Application provides advanced moderation tools, automated security features, leveling systems, birthday celebrations, and comprehensive logging capabilities. It includes a web server for health monitoring and metrics, integrates with MongoDB for data persistence, and features a subscription-based access model.
## 1. User Documentation
### Core Features
#### Moderation Commands
- **`/ban`** - Ban users from the server with optional message pruning and evidence links
- **`/unban`** - Remove bans from users with logging and notification systems
- **`/kick`** - Remove users from the server temporarily
- **`/mute`** - Temporarily restrict user communication with duration controls (minutes, hours, days, weeks)
- **`/unmute`** - Remove communication restrictions from users
- **`/warn`** - Issue warnings to users with evidence tracking
- **`/note`** - Add private moderation notes about users
- **`/softban`** - Ban and immediately unban to clean up user messages
- **`/massban`** - Ban multiple users at once using a list of user IDs
#### Server Management
- **`/lockdown`** - Lock text channels to prevent message sending
- **`/unlock`** - Remove lockdown restrictions from channels
- **`/prune`** - Bulk delete messages from channels
- **`/secure`** - Toggle server-wide DM and invite restrictions for new members
#### Configuration System
- **`/config list`** - View current server configuration
- **`/config logging`** - Set up moderation and event log channels
- **`/config invite-link`** - Configure invite links sent to kicked users
- **`/config appeal-link`** - Set ban appeal links for banned users
- **`/config roles`** - Toggle roles as self-assignable
- **`/config join-role`** - Set automatic role assignment for new members
- **`/config birthday-channel`** - Configure birthday celebration channel
#### User Experience Features
- **`/rank`** - View personal level and XP in the server
- **`/leaderboard`** - Browse server level rankings with pagination
- **`/profile`** - Customize profile appearance (avatar, colors, background)
- **`/role`** - Self-assign permitted roles
- **`/birthday`** - Set birthday for automatic celebrations
- **`/level-role`** - Configure roles automatically assigned at specific levels
#### Administrative Tools
- **`/cases`** - View specific moderation case details
- **`/history`** - View comprehensive user moderation history
- **`/help`** - Get bot information, version details, and support links
- **`/ping`** - Check bot latency and database connectivity
#### Context Menu Actions
- **Report Message** - Right-click context menu to report problematic messages
### Automated Features
#### Leveling System
- Automatic XP gain from message activity with anti-spam cooldowns
- Customizable level roles that auto-assign at specified levels
- Visual profile cards with customizable backgrounds and colors
- Server leaderboards with pagination
#### Security & Moderation
- Automatic detection and removal of known spam domains
- Automatic muting of compromised accounts posting malicious links
- Comprehensive audit logging for all moderation actions
- Member join/leave tracking with configurable logging
#### Event Logging
- Message edit/delete tracking with content preservation
- Voice channel activity monitoring
- Member update tracking (nickname, role changes)
- Moderation action logging with evidence and case numbers
#### Birthday System
- Automatic birthday wishes in designated channels
- Scheduled daily birthday checks
- User-configurable birthday dates with validation
### Access Control
- Subscription-based access model ($5/month)
- Permission-based command restrictions
- Moderator role validation for administrative commands
- Granular configuration permissions
This section is for those interacting with a live instance of the Application.
## 2. Technical Documentation
### Architecture Overview
Celestine is built as a modern Discord bot using:
- **Runtime**: Node.js with TypeScript
- **Discord Library**: Discord.js v14
- **Database**: MongoDB with Prisma ORM
- **Web Server**: Express.js for health endpoints
- **Monitoring**: Prometheus metrics integration
- **Scheduling**: Node-schedule for automated tasks
### Project Structure
```
src/
├── commands/ # Slash command implementations
├── contexts/ # Context menu command handlers
├── events/ # Discord event handlers
│ ├── client/ # Bot lifecycle events
│ ├── guild/ # Server-related events
│ ├── interaction/ # Command interaction handling
│ ├── member/ # Member join/leave/update events
│ ├── message/ # Message create/edit/delete events
│ ├── thread/ # Thread-related events
│ └── voice/ # Voice state change events
├── interfaces/ # TypeScript type definitions
├── modules/ # Reusable business logic
│ ├── commands/ # Command-specific modules
│ ├── data/ # Database interaction modules
│ ├── events/ # Event processing modules
│ ├── interactions/ # Interaction handling modules
│ ├── modals/ # Modal form handlers
│ └── subcommands/ # Subcommand implementations
├── server/ # Web server and health endpoints
├── utils/ # Utility functions and helpers
├── config/ # Configuration constants
└── database/ # Database connection setup
```
### Database Schema
The application uses MongoDB with the following key models:
#### Core Data Models
- **`cases`** - Moderation case tracking with evidence and timestamps
- **`configs`** - Per-server configuration settings
- **`levels`** - User XP and level progression data
- **`levelRoles`** - Automatic role assignments by level
- **`roles`** - Self-assignable role permissions
- **`birthdays`** - User birthday tracking
- **`entitlements`** - Server subscription management
- **`security`** - Server security settings (DM/invite restrictions)
#### Key Features of Data Layer
- Unique constraints for data integrity
- Indexed queries for performance
- Automatic relationship management
- Soft deletion support for case history
### Development Setup
#### Prerequisites
- Node.js 18+
- MongoDB instance
- Discord Bot Token
- TypeScript compiler
#### Environment Variables
```bash
TOKEN=<discord_bot_token>
MONGO_URI=<mongodb_connection_string>
DEBUG_HOOK=<discord_webhook_url>
DEV_MODE=<boolean>
```
#### Build Process
```bash
npm install # Install dependencies
npm run prebuild # Clean build directory and generate Prisma client
npm run build # Compile TypeScript to JavaScript
npm start # Run the bot
```
#### Development Scripts
- `npm run lint` - ESLint and Prettier validation
- `npm run audit` - Dependency and code analysis with Knip
- `npm run scan` - SonarCloud quality analysis
### Web Server Endpoints
The bot includes an Express.js server providing:
#### Health & Status
- **`GET /`** - HTML landing page with bot information and invite links
- **`GET /metrics`** - Prometheus metrics endpoint for monitoring
### Integration Points
#### Discord API
- Slash commands and context menus
- Webhook integrations for logging
- Permission validation
- Message content scanning
#### External Services
- GitHub integration for version tracking
- Prometheus metrics collection
- MongoDB Atlas for cloud database
- 1Password for secrets management
### Monitoring & Observability
#### Logging
- Winston-based structured logging
- Error tracking with unique identifiers
- Debug message routing to Discord webhooks
- Comprehensive audit trails
#### Metrics
- Prometheus integration for performance monitoring
- Database latency tracking
- Command usage statistics
- Server count and member tracking
### Security Considerations
#### Access Control
- Subscription validation for server access
- Permission-based command restrictions
- Rate limiting through Discord.js built-ins
- Input validation and sanitization
#### Data Protection
- Encrypted database connections
- Secure environment variable handling
- Minimal data retention policies
- Privacy-conscious logging practices
This section is for those interested in running their own instance of the Application.
## 3. Legal Documentation
### Subscription Model
Celestine operates as a paid service with a $5/month subscription fee per Discord server. This subscription model ensures:
- Sustainable development and maintenance
- Priority support for subscribers
- Regular feature updates and improvements
- Infrastructure costs coverage
### Data Handling
The Application processes and stores:
- Discord user IDs and server IDs
- Message content for moderation purposes (temporary)
- User-configured profile information
- Moderation case history and evidence links
- Server configuration preferences
### Service Availability
- Best-effort uptime with monitoring systems
- Planned maintenance notifications
- Support through designated Discord server
- Community-driven feedback and feature requests
## 4. Contributing Documentation
### Development Workflow
#### Code Standards
- TypeScript for type safety
- ESLint and Prettier for code formatting
- Comprehensive error handling with unique error IDs
- JSDoc documentation for public interfaces
#### Testing Strategy
- Integration testing with Discord API
- Database transaction testing
- Command validation testing
- Performance benchmarking
#### Pull Request Process
1. Fork the repository
2. Create feature branch from main
3. Implement changes with tests
4. Ensure linting and build passes
5. Submit PR with detailed description
6. Address review feedback
7. Merge after approval
#### Architecture Decisions
- Modular command structure for maintainability
- Event-driven architecture for real-time responses
- Database abstraction through Prisma ORM
- Configuration-driven behavior customization
### Extension Points
#### Adding New Commands
1. Create command file in `src/commands/`
2. Implement Command interface
3. Add to command loader
4. Update permissions if needed
5. Add documentation
#### Custom Event Handlers
1. Create handler in appropriate `src/events/` subdirectory
2. Implement error handling
3. Add to event registration system
4. Test with Discord API
#### Database Schema Changes
1. Update Prisma schema
2. Generate migration
3. Test migration on development database
4. Update TypeScript interfaces
5. Implement backward compatibility

322
src/content/docs/projects/cordelia-taryne.md Normal file
View File

@ -0,0 +1,322 @@
---
title: Cordelia Taryne
---
Cordelia Taryne (hereinafter the "Application") is an AI-powered multi-purpose assistant Discord bot that leverages Anthropic's Claude AI to provide various text processing, analysis, and assistance features. The bot features a distinctive vampire personality named Cordelia with haughty and self-inflated characteristics, providing users with intelligent assistance while maintaining a unique character persona.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Getting Started
To use Cordelia Taryne, [add her to your Discord account](https://discord.com/oauth2/authorize?client_id=1338664192714211459).
### Available Commands
Cordelia Taryne offers the following slash commands:
#### `/about`
- **Description**: Learn more about the bot
- **Usage**: Simply run `/about` to get information about the bot, including version and commit details
- **Access**: Available to all users
#### `/query`
- **Description**: Ask Cordelia a general question
- **Parameters**: `prompt` (required, max 2000 characters) - The question you would like to ask
- **Usage**: `/query prompt: What is the capital of France?`
- **Access**: Requires active subscription
#### `/alt-text`
- **Description**: Generate descriptive and accessible alt-text for images
- **Parameters**: `image` (required) - The image file to generate alt-text for
- **Supported formats**: JPG, JPEG, PNG, GIF, WEBP
- **Limitations**: Maximum 5MB file size, maximum 8000px dimensions
- **Usage**: Upload an image and run `/alt-text image: [your-image]`
- **Access**: Requires active subscription
#### `/eval`
- **Description**: Have Cordelia evaluate and run code snippets
- **Parameters**: `code` (required, max 2000 characters) - The code to evaluate
- **Usage**: `/eval code: 2 + 2 * 3`
- **Access**: Requires active subscription
#### `/mood`
- **Description**: Analyze the sentiment and mood of text passages
- **Parameters**: `text` (required, max 2000 characters) - The text to analyze
- **Usage**: `/mood text: I had an amazing day at the beach!`
- **Access**: Requires active subscription
#### `/proofread`
- **Description**: Have Cordelia proofread text for grammar and style
- **Parameters**: `text` (required, max 2000 characters) - The text to proofread
- **Usage**: `/proofread text: This are my essay about science.`
- **Access**: Requires active subscription
#### `/summarise`
- **Description**: Generate concise summaries of longer text passages
- **Parameters**: `text` (required, max 2000 characters) - The text to summarize
- **Usage**: `/summarise text: [long article or document text]`
- **Access**: Requires active subscription
### Subscription Model
Most features require an active subscription. The bot uses Discord's premium subscription system:
- Free users can access the `/about` command
- Subscribers gain access to all AI-powered features
- Bot owner (developer) has unlimited access for testing and maintenance
### Personality
Cordelia has a distinctive personality:
- **Character**: A vampire assistant with a haughty and self-inflated demeanour
- **Appearance**: Blonde hair in twin buns, pink-red cat-like eyes, pale skin, gold dress
- **Behavior**: Subtly condescending but never directly rude or insulting
- **Communication**: Professional assistance without role-playing text
### Support and Feedback
- **Bug Reports**: Open a GitHub issue
- **Feature Requests**: Create a GitHub issue with the enhancement label
- **General Support**: Visit the [chat server](http://chat.nhcarrigan.com)
- **Contact**: Email `contact@nhcarrigan.com`
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture Overview
Cordelia Taryne is built with:
- **Runtime**: Node.js with TypeScript
- **Discord Library**: discord.js v14
- **AI Provider**: Anthropic Claude API (Claude Sonnet 4)
- **Web Server**: Fastify (for status page)
- **Package Manager**: pnpm
- **Build System**: TypeScript compiler
### System Requirements
- Node.js 22+
- pnpm package manager
- Git for version control
- Environment variable management (1Password recommended)
### Environment Variables
Required environment variables:
- `DISCORD_TOKEN`: Discord bot token
- `AI_TOKEN`: Anthropic API key
- `npm_package_version`: Application version (auto-set by npm/pnpm)
### Installation and Setup
1. **Clone the repository**:
```bash
git clone https://github.com/nhcarrigan/cordelia-taryne.git
cd cordelia-taryne
```
2. **Install dependencies**:
```bash
pnpm install
```
3. **Set up environment variables**:
- Create a `prod.env` file with required variables
- Configure 1Password CLI for secure environment management
4. **Build the application**:
```bash
pnpm run build
```
5. **Deploy slash commands**:
```bash
node prod/commands/[command-name].js
```
6. **Start the application**:
```bash
pnpm start
```
### Project Structure
```
src/
├── index.ts # Main application entry point
├── commands/ # Slash command definitions
├── modules/ # Command implementation logic
├── config/
│ └── personality.ts # Bot personality configuration
├── server/
│ └── serve.ts # Web server for status page
└── utils/ # Utility functions
├── ai.ts # Anthropic AI client
├── calculateCost.ts # Usage cost calculation
├── isSubscribed.ts # Subscription validation
├── logger.ts # Logging utilities
└── replyToError.ts # Error handling
```
### Development Workflow
1. **Linting**: `pnpm run lint`
2. **Building**: `pnpm run build`
3. **Development**: Make changes in `src/`, build, and test
4. **Deployment**: Use the build artifacts in `prod/`
### API Integration
The bot integrates with:
- **Discord API**: For bot functionality and user interactions
- **Anthropic API**: For AI-powered text processing
- **Discord Premium**: For subscription management
### Monitoring and Logging
- Uses `@nhcarrigan/logger` for structured logging
- Tracks API usage and costs for each command
- Monitors subscription events (create/delete)
- Error handling with automatic logging
### Security Considerations
- All AI interactions are ephemeral (private responses)
- Subscription validation before AI API calls
- Input validation and sanitization
- Secure environment variable management
- Rate limiting through Discord's built-in mechanisms
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### Data Processing
- **User Data**: Discord user IDs are logged for usage tracking
- **Content Processing**: Text and images are sent to Anthropic for processing
- **Retention**: Logs are retained according to standard practices
- **Privacy**: All interactions are ephemeral and not stored permanently
### Third-Party Services
The Application integrates with:
- **Discord**: User authentication and interaction handling
- **Anthropic**: AI text and image processing
- **1Password**: Secure environment variable management
### Subscription Terms
- Subscriptions are managed through Discord's premium system
- Features are gated behind active subscription status
- Bot owner maintains unlimited access for maintenance
- Usage is tracked and logged for billing transparency
### Intellectual Property
- Bot personality and character design are original creations
- Source code is licensed under Naomi's Public License
- Avatar and visual assets are proprietary
- AI model responses are generated by Anthropic's Claude
### Usage Limits
- Text input limited to 2000 characters per command
- Image uploads limited to 5MB and 8000px dimensions
- API usage tracked and billed to service operator
- Fair use policies apply to prevent abuse
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Getting Started
1. **Read the Guidelines**: Review `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`
2. **Fork the Repository**: Create your own fork on GitHub
3. **Set Up Development Environment**: Follow technical documentation setup
4. **Create Feature Branch**: Use descriptive branch names
### Development Standards
#### Code Quality
- **TypeScript**: Strict typing required
- **ESLint**: Must pass linting with zero warnings (`pnpm run lint`)
- **Formatting**: Follow established code style
- **Comments**: JSDoc comments for all public functions
#### Architecture Patterns
- **Command Pattern**: Separate command definitions from implementations
- **Module Separation**: Clear separation between Discord logic and AI logic
- **Error Handling**: Comprehensive error handling with logging
- **Type Safety**: Proper TypeScript types throughout
#### File Structure Conventions
```
src/
├── commands/[name].ts # Discord command definitions
├── modules/[name].ts # Command implementation logic
├── utils/[name].ts # Shared utilities
└── config/[name].ts # Configuration files
```
### Contribution Process
1. **Issue Creation**: Create detailed GitHub issues for bugs/features
2. **Discussion**: Discuss approach before starting work
3. **Implementation**: Follow coding standards and patterns
4. **Testing**: Test thoroughly in development environment
5. **Pull Request**: Create detailed PR with description and testing notes
6. **Review**: Address feedback from maintainers
7. **Merge**: Maintainers will merge approved changes
### Testing Guidelines
- **Manual Testing**: Test all command paths and error cases
- **Integration Testing**: Verify Discord and Anthropic integrations
- **Subscription Testing**: Test both subscribed and unsubscribed flows
- **Error Scenarios**: Test network failures, API errors, and edge cases
### Feature Development
#### Adding New Commands
1. Create command definition in `src/commands/[name].ts`
2. Implement logic in `src/modules/[name].ts`
3. Add command to main handler in `src/index.ts`
4. Test subscription gating and error handling
5. Update documentation
#### Modifying AI Behavior
1. Update personality configuration if needed
2. Modify system prompts in relevant modules
3. Test with various inputs and edge cases
4. Consider cost implications of changes
### Code Review Standards
- **Functionality**: Does the code work as intended?
- **Style**: Does it follow established patterns?
- **Security**: Are there any security concerns?
- **Performance**: Are there efficiency improvements?
- **Documentation**: Are changes properly documented?
### Release Process
1. **Version Bump**: Update version in `package.json`
2. **Build**: Ensure clean build with `pnpm run build`
3. **Testing**: Comprehensive testing of new features
4. **Documentation**: Update relevant documentation
5. **Deployment**: Deploy to production environment
6. **Monitoring**: Monitor for issues post-deployment
### Community Guidelines
- **Respectful Communication**: Follow Code of Conduct
- **Constructive Feedback**: Provide helpful, actionable feedback
- **Collaboration**: Work together to improve the project
- **Learning**: Help others learn and grow
- **Recognition**: Credit contributors appropriately
For more detailed contributing information, see the `CONTRIBUTING.md` file in the repository.

282
src/content/docs/projects/docs.md Normal file
View File

@ -0,0 +1,282 @@
---
title: NHCarrigan Documentation Site
---
NHCarrigan Documentation Site (hereinafter the "Application") is a comprehensive documentation website built with Astro and Starlight that serves as the central hub for all documentation related to NHCarrigan's projects, policies, and services. The site provides organized access to technical documentation, legal policies, community guidelines, and project-specific information across multiple categories including Discord bots, web applications, libraries, and development tools. The Application features a custom-themed interface with accessibility considerations, analytics integration, and environmental sustainability features.
## 1. User Documentation
### Site Structure and Navigation
The Application is organized into several main sections accessible via the sidebar navigation:
- **About Us**: Mission statement, sustainability information, hiring, donations, contact, and mentorship
- **Legal Information**: Terms of service, privacy policy, software license, security policy, DMCA information, subprocessors list, and government actions
- **Community Policies**: Code of conduct, community guidelines, and appeal process
- **Development Documentation**: Contributing guide, contributor covenant, style guide, issue/PR labels, development environment, server setup, and VTubing setup
- **Project Documentation**: Comprehensive documentation for all NHCarrigan projects including Discord bots, web applications, libraries, and tools
- **Staff Guidelines**: Staff handbook and team application information
- **Miscellaneous Documents**: Additional resources like music management guides
### Key Features
#### Custom Theming
- Light and dark mode support with automatic detection
- Custom "Sakura Dreams" color scheme with pink/purple tones
- Accessibility features including OpenDyslexic font support
- Responsive design that works across all devices
#### Enhanced Footer
- TreeNation carbon offset widget integration for environmental sustainability
- Direct donation link for supporting the organization
- Standard Starlight navigation elements (edit links, last updated, pagination)
#### Analytics and Tracking
- Privacy-focused Plausible Analytics integration
- Page view and event tracking for user behavior insights
- Google AdSense integration for monetization
#### Content Features
- Project status badges indicating version and development status
- Comprehensive search functionality
- Table of contents for easy navigation within pages
- Social media links and contact information
### Accessibility
The Application includes several accessibility features:
- Semantic HTML structure with proper heading hierarchy
- OpenDyslexic font support for users with dyslexia
- High contrast color schemes
- Keyboard navigation support
- Screen reader compatible markup
## 2. Technical Documentation
### Architecture Overview
The Application is built using modern web technologies:
- **Framework**: Astro 5.3.0 - Static site generator for optimal performance
- **Theme**: Starlight 0.32.0 - Documentation-focused Astro integration
- **Language**: TypeScript 5.7.3 - Type-safe development
- **Build Tool**: Native Astro build system with minification and optimization
- **Package Manager**: PNPM (evidenced by pnpm-lock.yaml)
- **Hosting**: Static deployment to https://docs.nhcarrigan.com
### Project Structure
```
src/
├── components/ # Custom Astro components
│ ├── Footer.astro # Enhanced footer with TreeNation widget and donations
│ ├── ThemeProvider.astro # Custom theme system with analytics integration
│ └── navigation.ts # Sidebar navigation configuration
├── content/ # Documentation content
│ ├── config.ts # Content collection configuration
│ └── docs/ # Markdown/MDX documentation files
│ ├── intro.mdx # Homepage with hero section
│ ├── about/ # Organization information
│ ├── community/ # Community policies and guidelines
│ ├── dev/ # Development documentation
│ ├── legal/ # Legal policies and terms
│ ├── misc/ # Miscellaneous resources
│ ├── projects/ # Project-specific documentation
│ └── staff/ # Staff guidelines
├── fonts/ # Custom font files and CSS
├── pages/ # Astro pages
│ └── index.astro # Root page with legacy redirect handling
└── styles/ # Custom styling and themes
├── style.css # Global styles and CSS variables
├── theme.json # Light theme configuration for code highlighting
└── theme-dark.json # Dark theme configuration for code highlighting
public/ # Static assets
├── favicon.svg # Site favicon
├── logo.png # NHCarrigan logo
└── images/ # Project screenshots and documentation images
```
### Configuration Files
#### Astro Configuration (`astro.config.mjs`)
- Site URL configuration: https://docs.nhcarrigan.com
- Starlight integration with custom components
- Custom expressive code themes (Sakura Dreams light/dark)
- Analytics and tracking script injection
- TreeNation environmental widget integration
- Social media links and site metadata
- Custom CSS and font loading
#### Content Configuration (`src/content/config.ts`)
- Defines the `docs` collection using Starlight's schema
- Enables frontmatter validation and type safety
#### Navigation Configuration (`src/components/navigation.ts`)
- Hierarchical sidebar navigation structure
- Project status badges with version information
- External links to community resources
- Organized categorization of all documentation
### Custom Components
#### Footer Component (`src/components/Footer.astro`)
- Extends Starlight's default footer
- Integrates TreeNation carbon offset widget
- Adds donation link with visual call-to-action
- Maintains standard Starlight footer functionality (edit links, pagination, last updated)
#### Theme Provider (`src/components/ThemeProvider.astro`)
- Custom theme switching logic
- Analytics event tracking integration
- Theme persistence using localStorage
- Support for light, dark, and auto modes
### Styling System
#### CSS Variables and Theming
- Custom color scheme using CSS variables
- Pink/purple "Sakura Dreams" theme
- Dark mode with inverted color palette
- Background image integration for visual appeal
#### Typography
- OpenDyslexic font for accessibility
- Custom font loading via CSS @font-face
- Consistent typography hierarchy
### Development Workflow
#### Available Scripts
- `pnpm dev` / `pnpm start`: Development server on localhost:4321
- `pnpm build`: Production build to ./dist/
- `pnpm preview`: Preview production build locally
- `pnpm lint`: Spell checking with cspell
- `pnpm scan`: SonarCloud analysis for code quality
#### Code Quality
- TypeScript strict mode configuration
- ESLint integration (referenced in project documentation)
- SonarCloud integration for static analysis
- Spell checking for documentation content
### External Integrations
#### Analytics
- Plausible Analytics for privacy-focused tracking
- Custom event tracking for page views and interactions
- Google AdSense for monetization
#### Environmental Sustainability
- TreeNation carbon offset widget
- Environmental impact tracking and offsetting
#### Social and Community
- Links to self-hosted Git instance (git.nhcarrigan.com)
- Forum integration (forum.nhcarrigan.com)
### Performance and SEO
#### Static Site Generation
- Pre-built static pages for optimal loading speed
- Optimized asset delivery
- Compressed HTML output
#### SEO Features
- Open Graph meta tags for social media sharing
- Structured navigation for search engine crawling
- Sitemap generation (external: sitemap.nhcarrigan.com)
- Proper heading hierarchy and semantic markup
## 3. Legal Documentation
The Application serves as the central repository for all legal documentation related to NHCarrigan's operations and services. This includes:
### Comprehensive Legal Coverage
- **Terms of Service**: User agreements for all NHCarrigan services
- **Privacy Policy**: Data collection, processing, and user rights
- **Software License**: Open source licensing for projects
- **Security Policy**: Vulnerability reporting and security practices
- **DMCA and Copyright**: Intellectual property policies
- **Subprocessors List**: Third-party service providers and data processing
- **Government Actions**: Transparency reporting for legal requests
### Policy Management
- Centralized location for all legal documents
- Version control through Git for policy changes
- Public accessibility for transparency
- Regular updates reflecting current legal requirements
## 4. Contributing Documentation
### Development Environment Setup
#### Prerequisites
- Node.js (latest LTS version)
- PNPM package manager
- Git access to NHCarrigan's self-hosted instance
#### Local Development
1. Clone the repository from git.nhcarrigan.com
2. Install dependencies: `pnpm install`
3. Start development server: `pnpm dev`
4. Access local site at http://localhost:4321
### Content Contribution Guidelines
#### Documentation Standards
- Use Markdown (.md) or MDX (.mdx) for content files
- Follow established frontmatter schema for consistency
- Include appropriate metadata (title, description, etc.)
- Maintain consistent heading hierarchy (h2-h4 in table of contents)
#### File Organization
- Place content in appropriate `/src/content/docs/` subdirectories
- Use descriptive filenames following kebab-case convention
- Include project status badges for project documentation
- Update navigation configuration when adding new sections
#### Style Guidelines
- Follow existing documentation patterns
- Use clear, concise language
- Include code examples where appropriate
- Maintain accessibility standards
- Add project screenshots to `/public/images/` when relevant
### Code Contribution Process
#### Development Standards
- TypeScript strict mode compliance
- Pass spell checking with cspell
- Follow Astro and Starlight best practices
- Maintain existing component interfaces
#### Submission Process
1. Create feature branch from main
2. Make changes following style guidelines
3. Test locally with `pnpm dev`
4. Run quality checks: `pnpm lint`
5. Submit pull request to self-hosted Git instance
6. Await review and approval
#### Review Criteria
- Code quality and TypeScript compliance
- Documentation accuracy and completeness
- Accessibility compliance
- Performance impact assessment
- Security considerations
### Maintenance and Updates
#### Regular Maintenance Tasks
- Update project version badges
- Refresh project screenshots
- Review and update legal documents
- Monitor analytics for user behavior insights
- Update dependencies and security patches
#### Community Involvement
- Enable edit links for community contributions
- Maintain responsive support through various communication channels
- Encourage feedback through multiple contact methods
- Regular review of community guidelines and policies

126
src/content/docs/projects/gwen-abalise.md Normal file
View File

@ -0,0 +1,126 @@
---
title: Gwen Abalise
---
Gwen Abalise (hereinafter the "Application") is a Discord bot that provides a private thread-based ticketing system for Discord communities. The bot enables users to create support tickets through a simple button interface, with tickets managed as private threads that include designated support staff roles.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Getting Started
To use Gwen Abalise, [add her to your Discord server](https://discord.com/oauth2/authorize?client_id=1343413943447584819).
### Commands
The bot provides three slash commands:
- `/about` - Learn more about the bot, including version information and helpful links
- `/start <channel>` - Set up the ticket system in a specified text channel (requires MANAGE_GUILD permission)
- `/role <role>` - Configure which role should be pinged and added to new tickets (requires MANAGE_GUILD permission)
### Ticket System
The ticketing system works through a simple button interface:
1. Administrators use `/start` to place a "Create Ticket" button in a channel
2. Users click the button to open a private thread ticket
3. The designated support role is automatically added to the thread
4. Support staff can close tickets using the "Close Ticket" button within threads
### Subscription Model
The bot operates on a subscription model with Discord's premium features:
- Servers require an active subscription to use the ticketing functionality
- Entitled guilds (configured in the codebase) have access without subscription
- Non-subscribed servers receive prompts to subscribe with premium buttons
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture
The application is built with:
- **Runtime**: Node.js with TypeScript
- **Discord Library**: discord.js v14
- **Database**: MongoDB with Prisma ORM
- **Web Server**: Fastify (for health monitoring and landing page)
- **Logging**: Custom logger utility
### Core Components
#### Commands (`src/commands/`)
Command definitions for Discord slash commands:
- `about.ts` - Bot information command
- `role.ts` - Support role configuration command
- `start.ts` - Ticket system initialization command
#### Modules (`src/modules/`)
Business logic implementations:
- `about.ts` - Displays bot information with action buttons
- `close.ts` - Handles ticket closure and thread management
- `open.ts` - Creates new ticket threads and database records
- `role.ts` - Manages support role configuration
- `start.ts` - Sets up ticket creation interface in channels
#### Utilities (`src/utils/`)
- `isSubscribed.ts` - Validates server subscription status
- `logger.ts` - Logging functionality
- `replyToError.ts` - Error handling for interactions
#### Database Schema
Two main models:
- `Tickets` - Tracks ticket state (open/closed), thread IDs, and user associations
- `Roles` - Maps server IDs to their designated support role IDs
#### Web Server (`src/server/`)
Provides health monitoring endpoint and informational landing page at port 5012.
### Environment Requirements
- `DISCORD_TOKEN` - Bot token from Discord Developer Portal
- `MONGO_URI` - MongoDB connection string
- `npm_package_version` - Automatically set by npm for version display
### Permissions
The bot requires these Discord permissions:
- Send Messages
- Create Private Threads
- Manage Threads
- Use Slash Commands
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Setup
The project uses:
- TypeScript with strict configuration
- ESLint with @nhcarrigan/eslint-config
- Prisma for database management
- Vitest for testing (tests not yet implemented)
- pnpm for package management
### Build Process
```bash
pnpm build # Compiles TypeScript to prod/ directory
pnpm lint # Runs ESLint with zero warnings policy
pnpm start # Runs the compiled application with 1Password secrets
```
### Code Structure
The codebase follows a modular architecture with clear separation between:
- Command definitions (registration data)
- Command implementations (business logic)
- Utility functions (shared functionality)
- Database models (data persistence)
- Web server (health monitoring)

245
src/content/docs/projects/hikari.md Normal file
View File

@ -0,0 +1,245 @@
---
title: Hikari
---
Hikari (hereinafter the "Application") is a centralized platform for managing NHCarrigan's products and services. It consists of three main components: a Discord bot with AI capabilities, an Angular web client for dashboard management, and a Fastify server backend. The platform enables users to manage their accounts, subscriptions, licenses, product configurations, and provides an AI-powered support agent for assistance with NHCarrigan's ecosystem of products.
## 1. User Documentation
### Discord Bot Features
The Hikari Discord bot provides the following functionality:
- **AI Support Agent**: Chat with Hikari through direct messages to get help with NHCarrigan's products
- **Product Information**: Ask questions about any of the available products and services
- **Command Interface**: Use slash commands for quick actions
- `/about` - Get information about Hikari and available features
- `/dm` - Trigger a DM response to easily find your direct message channel
### Web Dashboard Features
The web dashboard provides a user-friendly interface for:
- **Product Browsing**: View all available products categorized by type (Community Tools, Websites/APIs, Apps/Games)
- **Announcements**: Stay updated with the latest product updates and community news
- **Account Management**: Manage your subscriptions, licenses, and configurations
- **Product Filtering**: Filter products by category or view all products at once
### Product Categories
1. **Community Tooling and Integrations**: Discord bots, translation services, and community management tools
2. **Websites and APIs**: Web applications, documentation sites, and API services
3. **Apps and Games**: Desktop applications, games, and interactive experiences
### Getting Started
1. **Discord Bot**: Install Hikari from the Discord app directory or invite to your server
2. **Web Dashboard**: Visit [hikari.nhcarrigan.com](https://hikari.nhcarrigan.com) to access the dashboard
3. **Support**: Join the [Discord community](https://chat.nhcarrigan.com) or visit the [forum](https://forum.nhcarrigan.com) for additional help
## 2. Technical Documentation
### Architecture Overview
Hikari follows a microservices architecture with three main components:
#### Bot Service (`/bot`)
- **Framework**: Discord.js v14.21.0
- **AI Integration**: Anthropic Claude API for intelligent responses
- **Language**: TypeScript with Node.js
- **Key Features**:
- Slash command handling
- Direct message AI conversations
- Web search integration
- Error handling and logging
#### Client Service (`/client`)
- **Framework**: Angular v20.0.4
- **Language**: TypeScript
- **Key Features**:
- Responsive web interface
- Product catalog with filtering
- Announcements system
- Routing and navigation
#### Server Service (`/server`)
- **Framework**: Fastify v5.4.0
- **Database**: MongoDB with Prisma ORM
- **Key Features**:
- RESTful API endpoints
- Announcement management
- Database operations
- Discord and forum integration
### Development Setup
#### Prerequisites
- Node.js (latest LTS)
- pnpm package manager
- MongoDB instance
- Discord bot token
- Anthropic API key
#### Installation
```bash
# Clone the repository
git clone https://git.nhcarrigan.com/nhcarrigan/hikari
# Install dependencies
pnpm install
# Build all services
pnpm build
```
#### Environment Configuration
**Bot Service** (`bot/prod.env`):
```ini
DISCORD_TOKEN=your_discord_token
ANTHROPIC_API_KEY=your_anthropic_key
```
**Server Service**:
```ini
MONGO_URI=your_mongodb_connection_string
```
#### Running Services
```bash
# Start bot service
cd bot && pnpm start
# Start client development server
cd client && ng serve
# Start server service
cd server && pnpm start
```
### Database Schema
The application uses MongoDB with the following models:
```prisma
model Announcements {
id String @id @default(auto()) @map("_id") @db.ObjectId
title String
content String
type String // "products" or "community"
createdAt DateTime @default(now()) @unique
}
```
### API Endpoints
- `POST /announcement` - Create new announcements
- `GET /announcements` - Retrieve announcements
- Health check and monitoring endpoints
### Key Configuration Files
- [`client/src/app/config/products.ts`](client/src/app/config/products.ts) - Product catalog configuration
- [`bot/src/config/prompt.ts`](bot/src/config/prompt.ts) - AI agent personality and instructions
- [`client/src/app/app.routes.ts`](client/src/app/app.routes.ts) - Client-side routing
- [`bot/commandJson.js`](bot/commandJson.js) - Discord slash command definitions
### Build and Deployment
The project uses Turbo for monorepo management:
```bash
# Build all projects
turbo build
# Run linting
turbo lint
# Run tests
turbo test
```
## 3. Legal Documentation
### License
This software is licensed under [Naomi's Public License](https://docs.nhcarrigan.com/#/license).
### Privacy Policy
User data handling is governed by the [NHCarrigan Privacy Policy](https://docs.nhcarrigan.com/#/privacy).
### Terms of Service
Usage of Hikari is subject to the [NHCarrigan Terms of Service](https://docs.nhcarrigan.com/#/terms).
### Security Policy
Security vulnerabilities should be reported according to the [NHCarrigan Security Policy](https://docs.nhcarrigan.com/#/security).
### Data Collection
- Discord user IDs for bot functionality
- Message content for AI processing (not stored permanently)
- Usage analytics for service improvement
- Subscription and account information
### Third-Party Services
- **Discord**: Bot hosting and user interaction
- **Anthropic Claude**: AI conversation processing
- **MongoDB**: Data storage
- **Gitea**: Source code hosting
## 4. Contributing Documentation
### Code of Conduct
All contributors must follow the [NHCarrigan Code of Conduct](https://docs.nhcarrigan.com/community/coc/).
### Contributing Guidelines
Please review the [Contributing Guidelines](https://docs.nhcarrigan.com/community/guide/) before submitting contributions.
### Development Workflow
1. **Issue Creation**: Use the provided templates in [`.gitea/issue_template/`](.gitea/issue_template/)
2. **Pull Requests**: Follow the template in [`.gitea/pull_request_template.yml`](.gitea/pull_request_template.yml)
3. **Code Standards**:
- ESLint configuration enforced
- TypeScript strict mode
- Comprehensive error handling
- Logging for debugging
### Project Structure
```
hikari/
├── bot/ # Discord bot service
│ ├── src/ # TypeScript source
│ └── prod/ # Compiled JavaScript
├── client/ # Angular web application
│ └── src/ # Angular source files
├── server/ # Fastify API server
│ ├── src/ # Server source
│ └── prisma/ # Database schema
└── docs/ # Documentation
```
### Testing Requirements
- Unit tests for new functionality
- Integration tests for API endpoints
- End-to-end tests for critical user flows
- Code coverage maintenance above threshold
### Style Guidelines
- Use TypeScript for all new code
- Follow existing naming conventions
- Include JSDoc comments for public methods
- Maintain consistent indentation (2 spaces)
- Use meaningful variable and function names
### Submission Checklist
- [ ] Code follows project style guidelines
- [ ] Tests added for new functionality
- [ ] Documentation updated as needed
- [ ] No breaking changes without discussion
- [ ] All checks pass in CI/CD pipeline
### Getting Help
- **Discord Community**: [chat.nhcarrigan.com](https://chat.nhcarrigan.com)
- **Forum**: [forum.nhcarrigan.com](https://forum.nhcarrigan.com)
- **Email**: contact@nhcarrigan.com

235
src/content/docs/projects/logger.md Normal file
View File

@ -0,0 +1,235 @@
---
title: "@nhcarrigan/logger"
---
@nhcarrigan/logger (hereinafter the "Application") is a custom logging utility that provides a wrapper around a custom alert monitoring server, enabling applications to pipe errors and log messages to a centralized alerting system.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Installation
Install the package using your preferred package manager:
```bash
npm install @nhcarrigan/logger
```
```bash
pnpm add @nhcarrigan/logger
```
```bash
yarn add @nhcarrigan/logger
```
### Quick Start
```typescript
import { Logger } from "@nhcarrigan/logger";
// Initialize the logger
const logger = new Logger("my-app", "your-api-token");
// Send log messages
await logger.log("info", "Application started successfully");
await logger.log("warn", "This is a warning message");
await logger.log("debug", "Debug information");
// Send error reports
try {
// Your code here
} catch (error) {
await logger.error("functionName", error);
}
```
### API Reference
#### Constructor
```typescript
new Logger(application: string, token: string, url?: string)
```
**Parameters:**
- `application` (string): The name of your application (will appear in logs)
- `token` (string): Your API token for the monitoring service
- `url` (optional string): Custom URL for your own alerting instance (defaults to "https://alerts.nhcarrigan.com")
#### Methods
##### `log(level: Level, message: string): Promise<void>`
Sends a log message to the alerting service.
**Parameters:**
- `level` (Level): The log level - one of "debug", "info", or "warn"
- `message` (string): The message to send
##### `error(context: string, error: Error): Promise<void>`
Sends an error to the alerting service with stack trace information.
**Parameters:**
- `context` (string): A brief description of where the error occurred (e.g., function name)
- `error` (Error): The Node.js error object
### Log Levels
The Application supports three log levels:
- `"debug"`: Debug information for development purposes
- `"info"`: General informational messages
- `"warn"`: Warning messages that don't halt execution
### Custom Alerting Server
By default, the logger sends data to `https://alerts.nhcarrigan.com`. You can configure it to use your own alerting instance by providing a custom URL in the constructor.
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture
The Application is built as a TypeScript class that wraps HTTP requests to an alerting server. It provides two main endpoints:
1. `/log` - For general log messages
2. `/error` - For error reporting with stack traces
### API Endpoints
#### POST /log
Sends structured log data:
```json
{
"application": "your-app-name",
"level": "info",
"message": "Your log message"
}
```
#### POST /error
Sends structured error data:
```json
{
"application": "your-app-name",
"context": "function-name",
"message": "Error message",
"stack": "Stack trace information"
}
```
### Authentication
All requests require an `Authorization` header with your API token.
### Development Setup
1. Clone the repository:
```bash
git clone https://git.nhcarrigan.com/nhcarrigan/logger.git
```
2. Install dependencies:
```bash
pnpm install
```
3. Build the project:
```bash
pnpm run build
```
4. Run linting:
```bash
pnpm run lint
```
### Project Structure
```
src/
├── index.ts # Main Logger class
└── types/
└── level.ts # Log level type definitions
```
### TypeScript Configuration
The project uses:
- `@nhcarrigan/typescript-config` for TypeScript configuration
- `@nhcarrigan/eslint-config` for ESLint rules
- ES modules (`"type": "module"`)
## 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 License. See the [LICENSE.md](LICENSE.md) file for complete terms.
### Copyright
Copyright held by Naomi Carrigan.
### Privacy
See [PRIVACY.md](PRIVACY.md) for privacy policy information.
### Terms of Service
See [TERMS.md](TERMS.md) for terms of service.
### Security
See [SECURITY.md](SECURITY.md) for security policy and vulnerability reporting procedures.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Getting Started
1. Read our [Code of Conduct](CODE_OF_CONDUCT.md)
2. Review our [Contributing Guidelines](CONTRIBUTING.md)
3. Fork the repository
4. Create a feature branch
5. Make your changes
6. Submit a Pull Request
### Development Guidelines
- Follow the existing code style enforced by ESLint
- Ensure TypeScript compilation passes without errors
- Add appropriate JSDoc comments for new public methods
- Test your changes thoroughly
### Issue Reporting
If you encounter bugs or have feature requests:
1. Check existing issues first
2. Create a new issue with detailed information
3. Include reproduction steps for bugs
4. Tag issues appropriately
### Contact
- Chat Server: [http://chat.nhcarrigan.com](http://chat.nhcarrigan.com)
- Email: contact@nhcarrigan.com
- Repository: [https://git.nhcarrigan.com/nhcarrigan/logger](https://git.nhcarrigan.com/nhcarrigan/logger)
- Issues: [https://git.nhcarrigan.com/nhcarrigan/logger/issues](https://git.nhcarrigan.com/nhcarrigan/logger/issues)
### Package Information
- **Package Name**: @nhcarrigan/logger
- **Version**: 1.0.0
- **NPM**: [https://www.npmjs.com/package/@nhcarrigan/logger](https://www.npmjs.com/package/@nhcarrigan/logger)
- **Repository**: Git-based repository hosted at git.nhcarrigan.com

176
src/content/docs/projects/maylin-taryne.md Normal file
View File

@ -0,0 +1,176 @@
---
title: Maylin Taryne
---
Maylin Taryne (hereinafter the "Application") is an AI-powered Discord bot that offers companionship and comfort during your darkest moments. Built with TypeScript and powered by Anthropic's Claude AI, Maylin provides a safe space for users to share their feelings and experiences through direct message conversations.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Quick Start
1. [Add Maylin to your Discord account](https://discord.com/oauth2/authorize?client_id=1343370633916059668)
2. Use the `/dm` command to start a private conversation
3. Send messages directly to Maylin in DMs for AI-powered companionship
### Available Commands
- `/about` - Learn more about Maylin and view bot information
- `/dm` - Opens a direct message conversation with Maylin
- `/clear` - Clears your conversation history to start fresh
### Subscription Features
Maylin operates on a subscription model. Some features require an active subscription:
- AI-powered conversations in direct messages
- Conversation history management
- Premium support access
### Important Notes
- Maylin is **NOT** a therapist and does **NOT** provide legal, medical, or financial advice
- She serves as a supportive, encouraging friend during tough times
- All conversations happen in private direct messages
- Conversation history can be cleared using the `/clear` command
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture Overview
Maylin Taryne is built as a user-installable Discord bot with the following key components:
#### Core Technologies
- **Runtime**: Node.js with TypeScript
- **Discord API**: discord.js v14
- **AI Integration**: Anthropic Claude (claude-sonnet-4-20250514)
- **Web Server**: Fastify for health monitoring
- **Logging**: @nhcarrigan/logger for centralized logging
- **Build System**: TypeScript compiler with ES modules
#### Bot Architecture
- **Event-Driven**: Responds to Discord events (messages, interactions, entitlements)
- **Command System**: Slash commands for user interactions
- **Subscription Model**: Discord entitlement system for premium features
- **Direct Message Focus**: Primarily operates in DM channels
#### Key Modules
##### Commands (`src/commands/`)
- Command definitions for Discord slash commands
- Exported as JSON for Discord API registration
##### Modules (`src/modules/`)
- **About Module**: Displays bot information and version details
- **Clear Module**: Manages conversation history clearing
##### Events (`src/events/`)
- **Message Handler**: Processes incoming DM messages and generates AI responses
- Manages conversation context and history
- Implements subscription validation
##### Utilities (`src/utils/`)
- **AI Integration**: Anthropic Claude API wrapper
- **Subscription Validation**: Discord entitlement checking
- **Cost Calculation**: Usage tracking and cost monitoring
- **Error Handling**: Standardized error responses
- **Logging**: Centralized logging infrastructure
##### Server (`src/server/`)
- Health monitoring web server on port 5011
- Serves basic landing page with bot information
#### Configuration
- **Personality**: Defined in `src/config/personality.ts`
- **Environment Variables**:
- `DISCORD_TOKEN`: Bot authentication
- `AI_TOKEN`: Anthropic API key
- `LOG_TOKEN`: Logging service token
#### Deployment
- Built to `prod/` directory using TypeScript compiler
- Runs with 1Password CLI for environment variable management
- Uses `op run` for secure environment injection
### Development Setup
```bash
# Install dependencies
pnpm install
# Build the project
pnpm run build
# Run linting
pnpm run lint
# Start the bot (requires environment setup)
pnpm start
```
### Environment Requirements
- Node.js (ES modules support)
- Discord Bot Token
- Anthropic API Key
- 1Password CLI (for production deployment)
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### Licensing
- Licensed under Naomi's Public License
- Copyright held by Naomi Carrigan
- See [global software license](https://docs.nhcarrigan.com/#/license) for details
### Privacy Considerations
- All conversations occur in Discord direct messages
- Message history is temporarily stored for context (up to 20 messages)
- Conversation history can be cleared by users via `/clear` command
- Usage metrics and costs are logged for operational purposes
### Service Limitations
- Maylin is not a licensed therapist or counsellor
- No legal, medical, or financial advice is provided
- Service availability depends on Discord and Anthropic API uptime
- Subscription required for full feature access
- NHCarrigan are not liable for any decisions you make based on Maylin's responses.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Standards
- TypeScript with strict type checking
- ESLint configuration (@nhcarrigan/eslint-config)
- ES modules throughout
- Comprehensive error handling and logging
### Code Structure
- Modular architecture with clear separation of concerns
- Event-driven design following Discord.js patterns
- Utility-first approach for shared functionality
- Configuration-driven personality and behavior
### Testing
- Vitest for testing framework (configuration present)
- Coverage reporting with Istanbul
- Currently no test files ("No tests yet!" placeholder)
### Build Process
- TypeScript compilation to `prod/` directory
- Clean build process (removes existing `prod/` before compilation)
- Source maps and proper module resolution
### Contributing Guidelines
- Review [CONTRIBUTING.md](CONTRIBUTING.md) before submitting changes
- Follow the established [Code of Conduct](CODE_OF_CONDUCT.md)
- Create Pull Requests for proposed changes
- All contributions subject to review process
### Support and Contact
- [Chat Server](http://chat.nhcarrigan.com) for community support
- Email: contact@nhcarrigan.com
- [Source Code Repository](https://git.nhcarrigan.com/nhcarrigan/maylin-taryne)

190
src/content/docs/projects/melody-iuvo.md Normal file
View File

@ -0,0 +1,190 @@
---
title: Melody Iuvo
---
Melody Iuvo (hereinafter the "Application") is a powerful task management bot for Discord that enables users to create, organize, and track their tasks, deadlines, and goals directly within Discord. The bot provides a comprehensive set of slash commands for task management with support for categories, priorities, status tracking, and due dates.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Getting Started
To use Melody Iuvo, you'll need to [add the bot to your Discord account](https://discord.com/oauth2/authorize?client_id=1338753576583041074) and subscribe to access the premium features.
### Available Commands
The bot provides the following slash commands for task management:
#### Core Commands
- **`/create`** - Create a new task
- **title**: The title for your task (required, max 256 characters)
- **description**: The description for your task (required, max 2048 characters)
- **status**: Task status - TODO, In Progress, In Review, or Complete (required)
- **priority**: Task priority - None, Low, Medium, High, or Critical (required)
- **category**: The category for your task (required, max 1024 characters)
- **due-date**: Due date in YYYY/MM/DD format (optional)
- **`/list`** - View your currently active tasks (excludes completed tasks)
- Shows up to 10 tasks sorted by due date
- Displays tasks in rich embed format with all details
- **`/view`** - View details of a specific task
- **number**: The task number you wish to view (required)
#### Task Modification Commands
- **`/retitle`** - Update the title of an existing task
- **number**: The task number to update (required)
- **title**: New title for the task (required, max 256 characters)
- **`/redescribe`** - Update the description of an existing task
- **number**: The task number to update (required)
- **description**: New description for the task (required, max 2048 characters)
- **`/restate`** - Update the status of an existing task
- **number**: The task number to update (required)
- **status**: New status (TODO, In Progress, In Review, Complete) (required)
- **`/reprioritise`** - Update the priority of an existing task
- **number**: The task number to update (required)
- **priority**: New priority (None, Low, Medium, High, Critical) (required)
- **`/recategorise`** - Update the category of an existing task
- **number**: The task number to update (required)
- **category**: New category (required, max 1024 characters)
- **`/retarget`** - Update the due date of an existing task
- **number**: The task number to update (required)
- **due-date**: New due date in YYYY/MM/DD format (optional)
#### Information Commands
- **`/about`** - Learn more about the bot
- Shows version information, commit details, and useful links
- Provides buttons for support, source code, and subscription
### Task Features
#### Status Types
- **TODO**: Task is planned but not started
- **In Progress**: Task is currently being worked on
- **In Review**: Task is completed and awaiting review
- **Complete**: Task is fully finished
#### Priority Levels
- **None**: No specific priority
- **Low**: Low priority task
- **Medium**: Medium priority task
- **High**: High priority task
- **Critical**: Urgent, critical priority task
#### Task Numbering
Each user has their own task numbering system starting from 1. Task numbers are unique per user and automatically assigned when creating new tasks.
#### Task Embeds
Tasks are displayed in rich Discord embeds showing:
- Title and description
- Category, status, and priority
- Due date, creation date, and last updated date
- Color-coded by status (red for TODO, orange for in-progress, yellow for in-review, green for complete)
### Subscription Model
Melody Iuvo operates on a premium subscription model. Users must subscribe to access the task management features. The subscription is managed through Discord's built-in premium subscription system.
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture Overview
Melody Iuvo is built as a Node.js Discord bot using the following technology stack:
- **Runtime**: Node.js with TypeScript
- **Discord Library**: Discord.js v14.18.0
- **Database**: MongoDB with Prisma ORM
- **Web Server**: Fastify (for health monitoring)
- **Logging**: Custom logger (@nhcarrigan/logger)
### Project Structure
```
src/
├── commands/ # Slash command definitions
├── modules/ # Command implementation logic
├── config/ # Configuration files (choices, names)
├── interfaces/ # TypeScript type definitions
├── db/ # Database connection
├── server/ # Web server for health monitoring
└── utils/ # Utility functions
```
### Key Components
#### Command System
The bot uses a modular command system where:
- `/src/commands/` contains Discord slash command definitions
- `/src/modules/` contains the actual command implementation logic
- Commands are registered in the main index file
#### Database Schema
The application uses a single `Tasks` model with the following fields:
- `id`: MongoDB ObjectId (primary key)
- `userId`: Discord user ID
- `number`: User-specific task number
- `title`: Task title
- `description`: Task description
- `category`: User-defined category
- `status`: Task status (enum)
- `priority`: Task priority (enum)
- `dueAt`: Due date
- `createdAt`: Creation timestamp
- `updatedAt`: Last update timestamp
#### Subscription System
The bot integrates with Discord's premium subscription system (Discord Store) to manage user access. All commands (except `/about`) require an active subscription.
#### Web Interface
A simple web server runs on port 5443 providing:
- Health monitoring endpoint
- Basic information page with links
- Discord bot invite link
### API Integration
The bot integrates with:
- Discord API (via Discord.js)
- Discord Store API (for subscriptions)
- MongoDB (via Prisma)
## 3. Legal Documentation
This section covers the legal policies and requirements specific to the Application.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Environment Variables
Required environment variables:
- `DISCORD_TOKEN`: Discord bot token
- `MONGO_URL`: MongoDB connection string
### Installation & Setup
1. Clone the repository
2. Install dependencies: `npm install`
3. Set up MongoDB database
4. Configure environment variables
5. Run database migrations: `npx prisma generate`
6. Build the project: `npm run build`
7. Start the bot: `npm start`
### Development
- **Build**: `npm run build` - Compiles TypeScript to JavaScript
- **Lint**: `npm run lint` - Runs ESLint with zero warnings policy
- **Start**: `npm start` - Runs the production build

158
src/content/docs/projects/mommy-bot.md Normal file
View File

@ -0,0 +1,158 @@
---
title: Mommy Bot
---
Mommy Bot (hereinafter the "Application") is a multi-platform bot application that provides encouraging and supportive messages across Discord, Slack, and Bluesky platforms. The bot delivers personalized "mommy" messages to users, creating a comforting and nurturing interaction experience.
## 1. User Documentation
### Discord Usage
- [Install the app](https://discord.com/oauth2/authorize?client_id=1347642447643017289)
- Use the `/mommy` slash command
- Optionally provide a name parameter: `/mommy name:YourName`
- The bot will respond with an encouraging message personalized to your name
### Slack Usage
- [Install the app](https://slack.com/oauth/v2/authorize?client_id=8569765106322.8554301974567&scope=commands&user_scope=)
- Use the `/mommy` command in any channel where the bot is installed
- Optionally provide a name: `/mommy YourName`
- The bot will respond with an encouraging message
### Bluesky Integration
- The bot automatically posts daily encouraging messages at 9:00 AM
- Follow [@mommy.naomi.party](https://bsky.app/profile/mommy.naomi.party) on Bluesky to see these posts
### Installation Links
Visit the bot's homepage to install:
- **Discord**: Add to your server via the Discord OAuth link
- **Slack**: Install via the Slack App Directory integration
- **Bluesky**: Follow the automated account for daily posts
## 2. Technical Documentation
### Architecture Overview
The Application is built using TypeScript and Node.js with the following key components:
#### Core Platforms
- **Discord**: Uses discord.js library for slash command integration
- **Slack**: Uses @slack/bolt framework for command handling
- **Bluesky**: Uses @atproto/api for automated posting
#### Main Components
**Application Entry Point (`src/index.ts`)**
- Initializes connections to all three platforms
- Sets up command handlers for Discord and Slack
- Configures scheduled posting for Bluesky (daily at 9:00 AM)
- Manages bot lifecycle and error handling
**Web Server (`src/server/serve.ts`)**
- Fastify-based HTTP server running on port 8009
- Serves a landing page with installation links
- Provides health monitoring endpoint
- Displays branding and social media links
**Message Generation (`src/utils/getMommy.ts`)**
- Fetches encouraging messages from external API
- Implements profanity filtering using no-profanity library
- Supports personalized name insertion
- Defaults to "dear" for filtered or empty names
**Logging (`src/utils/logger.ts`)**
- Uses @nhcarrigan/logger for structured logging
- Configured with application name "Mommy"
- Supports remote log token for centralized logging
#### Deployment
- Built using TypeScript compiler (`npm run build`)
- Production start script uses 1Password for environment management
- Runs as a persistent Node.js application
- Requires network access to Discord, Slack, and Bluesky APIs
#### Dependencies
Key production dependencies:
- `@atproto/api`: Bluesky/AT Protocol client
- `@slack/bolt`: Slack app framework
- `discord.js`: Discord API wrapper
- `fastify`: Web server framework
- `node-schedule`: Cron-like job scheduler
- `no-profanity`: Content filtering
## 3. Legal Documentation
### License
The Application is licensed under "Naomi's Public License" as specified in the source code headers.
### Copyright
All code is copyright © nhcarrigan (Naomi Carrigan).
### Third-Party Services
The Application integrates with:
- Discord API (subject to Discord's Terms of Service)
- Slack API (subject to Slack's API Terms)
- Bluesky/AT Protocol (subject to Bluesky's Terms)
- External message API (mommy.nhcarrigan.com)
### Data Handling
- User names are processed for profanity filtering
- No persistent user data storage
- Interaction data follows platform-specific retention policies
- Logs may contain interaction metadata
## 4. Contributing Documentation
#### Environment Variables
Required environment variables:
- `DISCORD_TOKEN`: Discord bot token
- `SLACK_CLIENT_ID`: Slack app client ID
- `SLACK_CLIENT_SECRET`: Slack app client secret
- `SLACK_SIGNING_SECRET`: Slack app signing secret
- `SLACK_STATE_SECRET`: Slack app state secret
- `BSKY_PASSWORD`: Bluesky account password
- `LOG_TOKEN`: Remote logging token (optional)
### Development Setup
1. Clone the repository
2. Install dependencies: `pnpm install`
3. Configure environment variables
4. Run in development mode: `npm run dev`
### Code Standards
- TypeScript with strict type checking
- ESLint configuration: @nhcarrigan/eslint-config
- Code must pass linting: `npm run lint`
- Follow existing code style and documentation patterns
### File Structure
```
src/
├── index.ts # Main application entry point
├── server/
│ └── serve.ts # Web server implementation
└── utils/
├── getMommy.ts # Core message functionality
└── logger.ts # Logging configuration
```
### Testing
- Currently no automated tests (test script returns success)
- Manual testing required for platform integrations
- Verify commands work on all supported platforms
### Deployment Process
1. Build production assets: `npm run build`
2. Ensure environment variables are configured
3. Start application: `npm start`
4. Monitor logs for successful platform connections
### Platform-Specific Considerations
- **Discord**: Requires bot permissions and slash command registration
- **Slack**: Needs app approval and workspace installation
- **Bluesky**: Requires valid account credentials and posting permissions
### Issue Reporting
Report bugs and feature requests through the project's issue tracker, including:
- Platform affected (Discord/Slack/Bluesky)
- Steps to reproduce
- Expected vs. actual behavior
- Environment details

189
src/content/docs/projects/mommy.md Normal file
View File

@ -0,0 +1,189 @@
---
title: Mommy
---
Mommy (hereinafter the "Application") is a web-based application that provides users with supportive and loving messages, optionally personalized with their name. The Application uses a Fastify-based backend server that serves both a landing page and an API endpoint, delivering encouraging phrases with configurable "mommy" personas. It is designed for ease of use, accessibility, and providing emotional support through positive reinforcement.
## 1. User Documentation
### How to Use Mommy
The Mommy application provides a simple web interface for receiving encouraging messages:
1. **Visit the Application**: Navigate to the [Mommy web application](https://mommy.nhcarrigan.com) in your browser
2. **Optional Name Entry**: Enter your name in the text field if you'd like personalized messages
3. **Request Love**: Click the "I need some love..." button to receive an encouraging message
4. **Receive Your Message**: A supportive phrase will appear, personalized with your name if provided
### Features
- **Personalized Messages**: Over 100 unique encouraging phrases that can be personalized with your name
- **Accessibility-Focused Design**: Uses OpenDyslexic font and high-contrast styling for better readability
- **Mobile-Friendly**: Responsive design that works on all device sizes
- **No Registration Required**: Instant access without any account creation
### API Endpoint
The application also provides a simple API:
- **Endpoint**: `/api`
- **Method**: GET
- **Optional Parameter**: `name` (string) - Your name for personalization
- **Response**: Plain text encouraging message
Example: `GET /api?name=Alex` returns a personalized encouraging message.
## 2. Technical Documentation
### Architecture Overview
Mommy is built using:
- **Backend**: Fastify web framework (Node.js/TypeScript)
- **Frontend**: Vanilla HTML/CSS/JavaScript (no frameworks)
- **Configuration**: Modular phrase and persona configuration files
### Project Structure
```
src/
├── index.ts # Main server entry point
├── config/
│ ├── html.ts # HTML template for landing page
│ ├── mommy.ts # Mommy persona names ("your mommy", "mama", etc.)
│ └── phrases.ts # 100+ encouraging phrase templates
```
### Server Implementation
The application uses Fastify to serve:
1. **Landing Page** (`/`): Returns the complete HTML interface
2. **API Endpoint** (`/api`): Returns personalized encouraging messages
### Message Generation
Messages are generated by:
1. Randomly selecting a phrase template from `phrases.ts`
2. Randomly selecting a "mommy" persona from `mommy.ts`
3. Interpolating `{{ name }}` and `{{ mommy }}` variables in the template
4. Converting to lowercase and returning as plain text
### Installation and Setup
#### Prerequisites
- Node.js (18+ recommended)
- pnpm package manager
#### Development Setup
```bash
# Install dependencies
pnpm install
# Run in development mode with auto-reload
pnpm dev
# Build for production
pnpm build
# Run production server
pnpm start
# Run tests
pnpm test
# Lint code
pnpm lint
```
#### Production Deployment
The server listens on port 8008 by default. For production deployment:
1. Build the project: `pnpm build`
2. Start the server: `pnpm start`
3. Configure reverse proxy (nginx/Apache) if needed
### Configuration
#### Adding New Phrases
Edit `src/config/phrases.ts` to add new encouraging messages. Use:
- `{{ name }}` for user's name interpolation
- `{{ mommy }}` for mommy persona interpolation
#### Adding New Mommy Personas
Edit `src/config/mommy.ts` to add new ways mommy refers to herself.
### Testing
The project includes comprehensive tests using Vitest:
- Server endpoint testing
- Configuration validation
- Phrase uniqueness verification
- HTML response validation
## 3. Legal Documentation
### License
This software is licensed under Naomi's Public License. Copyright held by Naomi Carrigan.
### Privacy
The application:
- Does not store user data persistently
- Does not use cookies or tracking
- Processes names only for message personalization
- Does not log personal information
### Content Policy
All phrases are designed to be:
- Supportive and encouraging
- Appropriate for all ages
- Non-discriminatory
- Focused on positive reinforcement
## 4. Contributing Documentation
### Development Workflow
1. **Fork and Clone**: Fork the repository and clone your fork
2. **Install Dependencies**: Run `pnpm install`
3. **Create Feature Branch**: `git checkout -b feature/your-feature`
4. **Make Changes**: Implement your changes with tests
5. **Test**: Run `pnpm test` and `pnpm lint`
6. **Commit**: Use conventional commit messages
7. **Pull Request**: Submit PR with clear description
### Code Standards
- **TypeScript**: Strict typing enabled
- **ESLint**: Uses @nhcarrigan/eslint-config
- **Testing**: Vitest with coverage requirements
- **Documentation**: JSDoc comments for all functions
### Adding Content
#### New Encouraging Phrases
To add new phrases to `src/config/phrases.ts`:
1. Follow the existing template format
2. Use `{{ name }}` and `{{ mommy }}` placeholders
3. Keep messages positive and supportive
4. Ensure phrases are appropriate for all audiences
5. Add tests to verify uniqueness
#### New Mommy Personas
To add new personas to `src/config/mommy.ts`:
1. Add family-friendly terms
2. Ensure they work grammatically in all phrase templates
3. Test with existing phrases
### Testing Guidelines
- All new features must include tests
- Maintain 100% test coverage
- Test both success and error cases
- Verify phrase interpolation works correctly
### Submission Guidelines
- Follow existing code style
- Include tests for new functionality
- Update documentation as needed
- Ensure all checks pass before submitting

112
src/content/docs/projects/portfolio.md Normal file
View File

@ -0,0 +1,112 @@
---
title: NHCarrigan Portfolio
---
NHCarrigan Portfolio (hereinafter the "Application") is a static HTML landing page that serves as the primary web presence for NHCarrigan, a software engineering and community management consulting firm. The Application provides information about the organization's services, contact methods, past clients, and founder, while serving as a gateway to the broader NHCarrigan ecosystem of tools and communities.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
### Current Live Instance
The Application is currently deployed and accessible at [nhcarrigan.com](https://nhcarrigan.com).
### Available Features
- **Company Information**: Overview of NHCarrigan's consulting services specializing in community management and software engineering
- **Service Offerings**: Details about tools and infrastructure development for online community management
- **Contact Options**: Multiple ways to reach the organization including:
- Public Discord community
- Forum for long-form discussions
- Commission inquiry form
- General contact form
- Paid meeting scheduling
- **Past Work**: Links to founder's resume, client testimonials, sitemap, and open source code
- **Founder Information**: Background about Naomi Carrigan and the organization's mission
- **Resource Links**: Access to documentation, policies, and educational content
## 2. Technical Documentation
:::note
This section is coming soon!
:::
This section is for those interested in running their own instance of the Application.
### Architecture
The Application is built as a simple static HTML website consisting of:
- Single `index.html` file located in the `site/` directory
- External CSS and JavaScript resources loaded from `cdn.nhcarrigan.com`
- No build process or dependencies required
### Deployment Requirements
- Static web hosting capable of serving HTML files
- No server-side processing required
- No database or runtime dependencies
### External Dependencies
- CSS styling loaded from `https://cdn.nhcarrigan.com/headers/index.js`
- Logo image served from `https://cdn.nhcarrigan.com/logo.png`
## 3. Legal Documentation
:::note
This section is coming soon!
:::
This section is for expansions to our legal policies specific to the Application.
### Current Legal Framework
The Application operates under NHCarrigan's standard legal documentation:
- **License**: Global software license (available at docs.nhcarrigan.com)
- **Copyright**: Held by Naomi Carrigan
- **Code of Conduct**: Available in repository and at docs.nhcarrigan.com
- **Privacy Policy**: Referenced on the website
- **Terms of Service**: Referenced on the website
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
### Current Contributing Guidelines
- Contributing guidelines available at: https://docs.nhcarrigan.com/#/contributing
- Code of Conduct must be followed (see CODE_OF_CONDUCT.md)
- Pull requests welcome for proposed changes
- Issues can be reported through the repository's issue tracker
- Community support available through Discord at chat.nhcarrigan.com
### Repository Structure
```
/
├── CODE_OF_CONDUCT.md # Community guidelines
├── CONTRIBUTING.md # Link to contributing guidelines
├── LICENSE.md # License information
├── PRIVACY.md # Privacy policy
├── README.md # Project overview
├── SECURITY.md # Security policies
├── TERMS.md # Terms of service
├── site/
│ └── index.html # Main website file
└── .gitea/ # Issue and PR templates
```
### Contact Information
- **Email**: contact@nhcarrigan.com
- **Discord**: https://chat.nhcarrigan.com
- **Website**: https://nhcarrigan.com

186
src/content/docs/projects/resume.md Normal file
View File

@ -0,0 +1,186 @@
---
title: Naomi's Resume
---
Naomi's Resume (hereinafter the "Application") is a static site generator that transforms a YAML or JSON resume source into a styled HTML resume website, along with downloadable formats. It is designed for easy customization and deployment, using TypeScript for parsing and rendering, and outputs a ready-to-host static site.
## 1. User Documentation
The Application generates a professional, accessible resume website from structured data. The live website displays:
### Features
- **Responsive Design**: Mobile-friendly layout that works on all devices
- **Print-Optimized**: Print or save as PDF with optimized styling
- **Multiple Formats**: Download resume data in YAML or JSON format
- **Professional Sections**: Employment, volunteer work, education, certifications, projects, and publications
- **Navigation Links**: Quick jump links to different resume sections
- **Contact Integration**: Direct links to testimonials and contact forms
### Using the Resume Website
1. **Browse Sections**: Use the navigation links to jump to specific sections (Employment, Education, etc.)
2. **Download Data**: Click "YAML" or "JSON" links to download the resume in structured formats
3. **Print/Save PDF**: Click the "print" link to open browser print dialog for PDF saving
4. **Contact**: Use the "submit your own request" link to contact for opportunities
### Resume Sections
- **Employment**: Current and past positions with company details, dates, and descriptions
- **Volunteer Work**: Community involvement and volunteer positions
- **Education**: Academic background and certifications
- **Certifications**: Professional certifications and credentials
- **Projects**: Notable projects and achievements
- **Publications**: Articles, papers, and published works
## 2. Technical Documentation
The Resume Builder is a Node.js-based static site generator that transforms YAML resume data into a complete website.
### Architecture
- **TypeScript Parser**: `src/parse.ts` - Main build script that processes YAML data
- **Data Schema**: `src/interfaces/resume.ts` - TypeScript interfaces defining resume structure
- **Source Data**: `src/source.yaml` - YAML file containing all resume information
- **Static Assets**: `src/static/` - CSS styles and JavaScript for the generated site
- **Output**: `site/` - Generated HTML, CSS, JS, YAML, and JSON files
### Requirements
- Node.js (latest LTS recommended)
- pnpm package manager
- TypeScript support via tsx
### Installation & Setup
```bash
# Clone the repository
git clone <repository-url>
cd resume
# Install dependencies
pnpm install
# Build the site
pnpm run build
```
### Available Scripts
- `pnpm run build` - Generate the static site from YAML data
- `pnpm run lint` - Run ESLint for code quality
- `pnpm run spelling` - Check spelling in source.yaml
- `pnpm run test` - Run validation tests
### Data Structure
The resume data follows this schema:
- `name`: Full name
- `contact`: Contact information
- `summary`: Professional summary
- `employment[]`: Array of employment positions
- `volunteer[]`: Array of volunteer positions
- `education[]`: Array of educational background
- `certifications[]`: Array of certifications
- `projects[]`: Array of notable projects
- `publications[]`: Array of publications
### Customization
1. **Content**: Edit `src/source.yaml` with your resume data
2. **Styling**: Modify `src/static/style.css` for visual customization
3. **Structure**: Update `src/parse.ts` to change HTML generation
4. **Types**: Extend `src/interfaces/resume.ts` for new data fields
### Deployment
The `site/` directory contains all files needed for static hosting:
- `index.html` - Main resume webpage
- `style.css` - Styling
- `dates.js` - JavaScript for date handling
- `resume.yaml` - YAML format download
- `resume.json` - JSON format download
Deploy to any static hosting service (Netlify, Vercel, GitHub Pages, etc.)
## 3. Legal Documentation
### License
This software is licensed under Naomi's Public License. Copyright held by Naomi Carrigan.
For complete legal terms, refer to:
- [Global Software License](https://docs.nhcarrigan.com/#/license)
- [LICENSE.md](LICENSE.md) in the repository
- [PRIVACY.md](PRIVACY.md) for privacy policy
- [TERMS.md](TERMS.md) for terms of service
- [SECURITY.md](SECURITY.md) for security policies
### Data Privacy
The resume website is a static site that:
- Does not collect user data
- Does not use cookies or tracking
- Does not store personal information
- Contains only publicly available professional information
### Third-Party Services
The generated website may include links to external services:
- Testimonials platform (testimonials.nhcarrigan.com)
- Contact forms (forms.nhcarrigan.com)
- External headers/scripts (cdn.nhcarrigan.com)
Users should review the privacy policies of any external services they choose to interact with.
## 4. Contributing Documentation
### Getting Started
1. Fork the repository
2. Clone your fork locally
3. Install dependencies: `pnpm install`
4. Make your changes
5. Test your changes: `pnpm run build && pnpm run test && pnpm run lint && pnpm run spelling`
6. Submit a pull request
### Contribution Guidelines
- Read the [Code of Conduct](CODE_OF_CONDUCT.md) before participating
- Follow the existing code style and conventions
- Only modify `src/source.yaml` for content changes
- Do not commit files in the `site/` directory (auto-generated)
- Ensure all tests pass before submitting
- Provide clear commit messages and PR descriptions
### Development Workflow
1. **Content Updates**: Edit `src/source.yaml` with new resume information
2. **Code Changes**: Modify TypeScript files in `src/` directory
3. **Styling**: Update CSS in `src/static/style.css`
4. **Testing**: Add tests in `test/` directory using Vitest
5. **Build**: Run `pnpm run build` to generate the site
### Quality Checks
All contributions must pass:
- **ESLint**: Code quality and style checking
- **Spelling**: cspell validation of YAML content
- **Tests**: Vitest validation of data structure
- **Build**: Successful site generation
### Reporting Issues
- Use GitHub Issues for bugs and feature requests
- Provide detailed reproduction steps for bugs
- Include relevant error messages and logs
- Tag issues appropriately (bug, enhancement, documentation)
### Contact
- [Chat Server](http://chat.nhcarrigan.com) for real-time discussion
- Email: contact@nhcarrigan.com for direct communication
- GitHub Issues for project-specific discussions
### Project Structure
```
src/
├── parse.ts # Main build script
├── source.yaml # Resume data (edit this)
├── interfaces/
│ └── resume.ts # TypeScript type definitions
└── static/
├── style.css # Website styling
└── dates.js # Date handling JavaScript
test/
└── validate.spec.ts # Validation tests
site/ # Generated output (do not edit)
├── index.html
├── style.css
├── dates.js
├── resume.yaml
└── resume.json
```

207
src/content/docs/projects/rosalia-nightsong.md Normal file
View File

@ -0,0 +1,207 @@
---
title: Rosalia Nightsong
---
Rosalia Nightsong (hereinafter the "Application") is a centralized alert server that receives and forwards application logs, errors, uptime notifications, Discord entitlements, and Stripe payment events to both email and Discord channels for real-time monitoring and notification purposes.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Overview
Rosalia Nightsong serves as a webhook endpoint and notification hub for various services. The application accepts HTTP POST requests containing structured data and forwards them as formatted notifications to configured email addresses and Discord channels.
### API Endpoints
The Application provides several webhook endpoints:
- **GET /** - Returns the application's homepage with basic information
- **POST /log** - Accepts application log messages
- **POST /error** - Accepts error reports with stack traces
- **POST /uptime** - Accepts uptime/health check notifications
- **POST /entitlement** - Handles Discord entitlement purchase notifications
- **POST /stripe** - Processes Stripe payment webhook events
### Authentication
All POST endpoints (except Stripe webhooks) require authentication via the `Authorization` header containing a valid API token. Discord entitlements use Ed25519 signature verification for security.
### Supported Applications
The server maintains a registry of supported Discord applications with their respective verification keys for entitlement webhook validation.
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture
Rosalia Nightsong is built using:
- **Runtime**: Node.js with TypeScript
- **Web Framework**: Fastify for high-performance HTTP handling
- **Email**: Nodemailer with SMTP transport
- **Discord Integration**: Discord API v10 for channel messaging
- **Payment Processing**: Stripe SDK for webhook handling
- **Webhook Verification**: discord-verify for Ed25519 signature validation
### Environment Configuration
The application requires the following environment variables:
```env
MATRIX_ACCESS_TOKEN="matrix_access_token"
MATRIX_ROOM_ID="matrix_room_id"
API_AUTH="api_authentication_token"
EMAIL_PASSWORD="smtp_password"
DISCORD_WEBHOOK_URL="discord_webhook_url"
STRIPE_SECRET_KEY="stripe_secret_key"
STRIPE_WEBHOOK_SECRET="stripe_webhook_secret"
DISCORD_TOKEN="discord_bot_token"
```
### Installation and Setup
1. **Prerequisites**
- Node.js 22+ with pnpm package manager
- TypeScript compiler
- Access to SMTP server for email notifications
- Discord bot token and channel access
- Stripe account with webhook configuration (if using payment features)
2. **Installation**
```bash
pnpm install
```
3. **Build**
```bash
pnpm run build
```
4. **Start**
```bash
pnpm start
```
The server will listen on port 5003 by default.
### API Schema Validation
The application uses JSON schema validation for incoming requests:
#### Log Endpoint (`/log`)
```typescript
{
application: string;
level: string;
message: string;
}
```
#### Error Endpoint (`/error`)
```typescript
{
application: string;
context: string;
message: string;
stack: string;
}
```
#### Uptime Endpoint (`/uptime`)
```typescript
{
application: string;
message: string;
}
```
### Notification Formats
**Email Notifications**: Plain text format sent to configured SMTP recipient
**Discord Notifications**: Rich embed format with structured components and markdown support
### Security Features
- API token authentication for log/error/uptime endpoints
- Ed25519 signature verification for Discord entitlements
- Stripe webhook signature validation
- Request body validation against JSON schemas
- Error handling with notification forwarding
### Monitoring and Logging
The application includes comprehensive error handling that forwards internal errors to the configured notification channels, ensuring operational visibility and quick incident response.
## 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 License. Copyright held by Naomi Carrigan.
### Data Handling
The Application processes and forwards notification data but does not persistently store user data. All webhook payloads are processed in memory and forwarded to configured notification channels.
### Third-Party Services
The Application integrates with:
- Discord API for message delivery
- Stripe API for payment webhook processing
- SMTP servers for email delivery
Users should review the privacy policies and terms of service for these third-party services.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Setup
1. **Clone the repository**
2. **Install dependencies**: `pnpm install`
3. **Configure environment variables** in `prod.env`
4. **Run linting**: `pnpm run lint`
5. **Build the project**: `pnpm run build`
6. **Start development server**: `pnpm start`
### Code Structure
```
src/
├── config/ # Application configuration and data
├── interfaces/ # TypeScript interface definitions
├── modules/ # Core functionality modules
├── schemas/ # JSON schema validation definitions
├── server/ # Fastify server setup and routing
└── utils/ # Utility functions
```
### Development Guidelines
- Follow the existing ESLint configuration (`@nhcarrigan/eslint-config`)
- Use TypeScript strict mode
- Include comprehensive error handling
- Add appropriate JSDoc comments for public functions
- Maintain the existing code style and structure
### Testing
Currently, no automated tests are configured. Contributors are encouraged to manually test all endpoints and error scenarios.
### Pull Request Process
1. Review the [contributing guidelines](CONTRIBUTING.md)
2. Follow the [Code of Conduct](CODE_OF_CONDUCT.md)
3. Create a feature branch from main
4. Make your changes with appropriate commit messages
5. Ensure linting passes
6. Submit a pull request with a clear description
### Contact
For questions or support, contact through the [Chat Server](http://chat.nhcarrigan.com) or email `contact@nhcarrigan.com`.

255
src/content/docs/projects/static-pages.md Normal file
View File

@ -0,0 +1,255 @@
---
title: Static Pages
---
Static Pages (hereinafter the "Application") is a collection of static HTML pages and related data/scripts for various small web utilities and content sections. The application provides interactive explorers for books and music libraries, product directories, games, chat services, testimonials, and other utility pages. It is designed to be easily synchronized to a production server using shell scripts and requires no backend or dynamic server-side logic.
## 1. User Documentation
The Application provides several interactive web utilities:
### Book Library
Visit at https://books.nhcarrigan.com
An interactive explorer for Naomi's book collection. Users can browse and search through the library of books with filtering capabilities by author. The interface displays book titles and authors extracted from digital book files.
### Music Library
Visit at https://music.nhcarrigan.com
An interactive explorer for Naomi's music collection. Similar to the book library, users can browse and search through songs with filtering by artist. The interface displays song titles and artists extracted from audio file metadata.
### Games
Visit at https://games.nhcarrigan.com
A landing page showcasing various games developed by NHCarrigan, including links to the Beccalia Series and other game projects.
### BlueSky Handle Generator
Visit at https://naomi.party
A service page for provisioning custom Bluesky handles under the naomi.party domain. Currently requires manual processing through the Discord support server.
### Testimonials
Visit at https://testimonials.nhcarrigan.com
A showcase page displaying testimonials from past clients about NHCarrigan's work and services.
### Link Redirector
Visit at https://nhcarrigan.link
A utility page that serves as a fallback for improperly configured subdomain redirects, providing users with support contact information.
This section is for those interacting with a live instance of the Application.
### User Manual
Visit at https://manual.nhcarrigan.com
A brief description of what it is like to work with Naomi, and how to cultivate an environment where she can thrive.
## 2. Technical Documentation
### System Requirements
- Unix-like operating system (Linux/macOS)
- Bash shell
- `rsync` for deployment
- `exiftool` for extracting book metadata
- `mid3v2` for extracting music metadata
- `jq` for JSON processing
- Access to Gitea API (for products functionality)
- Web server capable of serving static files
### Project Structure
```
├── books/ # Book library interface
│ ├── index.html # Main book explorer page
│ └── books.json # Generated book data
├── music/ # Music library interface
│ ├── index.html # Main music explorer page
│ └── songs.json # Generated music data
├── products/ # Product directory
│ ├── index.html # Product listing page
│ └── data.json # Generated product data
├── games/ # Games showcase
├── bsky/ # BlueSky handle service
├── testimonials/ # Client testimonials
├── link-redirector/ # Redirect fallback
├── mail/ # Mail service (manual sync)
├── manual/ # Manual/documentation
├── sitemap/ # Site navigation
├── books.sh # Book data generator script
├── songs.sh # Music data generator script
├── products.sh # Product data generator script
└── sync.sh # Deployment script
```
### Data Generation Scripts
**Book Library (`books.sh`)**
- Scans `/home/naomi/cloud/Books` directory for book files
- Extracts title and author metadata using `exiftool`
- Generates `books/books.json` with book data
- Handles files without metadata by using filenames
**Music Library (`songs.sh`)**
- Scans `/home/naomi/music` directory for audio files
- Extracts title and artist metadata using `mid3v2`
- Generates `music/songs.json` with song data
- Falls back to filename parsing for missing metadata
**Product Directory (`products.sh`)**
- Fetches repository data from Gitea API
- Organizes projects by category (public, games, private, archived)
- Generates `products/data.json` with project information
- Requires `GITEA_TOKEN` environment variable
### Deployment
The deployment process uses `sync.sh` which:
1. Syncs all directories to production server using `rsync`
2. Targets `prod:/home/nhcarrigan` for most content
3. Requires manual sync for `mail/index.html` to `mail:/home/user-data/www/default`
**Deployment Command:**
```bash
./sync.sh
```
### Running Your Own Instance
1. **Clone the repository**
2. **Install dependencies:**
```bash
# Ubuntu/Debian
sudo apt install exiftool python3-mutagen jq rsync
# macOS
brew install exiftool jq rsync
pip3 install mutagen
```
3. **Configure data sources:**
- Update paths in `books.sh` for your book collection
- Update paths in `songs.sh` for your music collection
- Set `GITEA_TOKEN` environment variable for products functionality
- Modify `products.sh` with your Gitea instance URL and organizations
4. **Generate data:**
```bash
./books.sh # Generate book library data
./songs.sh # Generate music library data
./products.sh # Generate product directory data
```
5. **Serve static files:**
```bash
# Simple Python server for testing
python3 -m http.server 8000
```
6. **Deploy to production:**
- Modify `sync.sh` with your server details
- Ensure SSH key authentication is configured
- Run `./sync.sh`
This section is for those interested in running their own instance of the Application.
## 3. Legal Documentation
The Application operates under NHCarrigan's standard legal framework:
### License
This software is licensed under the [global software license](https://docs.nhcarrigan.com/#/license). Copyright is held by Naomi Carrigan.
### Privacy Policy
Privacy considerations for the Application are covered under the [global privacy policy](PRIVACY.md).
### Terms of Service
Terms of service for the Application are outlined in [TERMS.md](TERMS.md).
### Code of Conduct
All interactions with the Application's community and codebase are governed by the [Code of Conduct](https://docs.nhcarrigan.com/#/coc), referenced in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
### Security Policy
Security reporting and handling procedures are documented in [SECURITY.md](SECURITY.md).
### Data Handling
- **Book Library**: Processes local book file metadata only
- **Music Library**: Processes local music file metadata only
- **Product Directory**: Fetches public repository information from Gitea API
- **BlueSky Service**: Collects handle requests through Discord (manual process)
- **No personal data**: The Application does not collect or store personal user data directly
This section is for expansions to our legal policies specific to the Application.
## 4. Contributing Documentation
### Getting Started
Contributors should review the [global contributing guidelines](https://docs.nhcarrigan.com/#/contributing) referenced in [CONTRIBUTING.md](CONTRIBUTING.md).
### Development Workflow
1. **Fork and Clone**
```bash
git clone https://github.com/your-username/Static Pages.git
cd Static Pages
```
2. **Set Up Development Environment**
- Install required dependencies (see Technical Documentation)
- Configure data source paths for testing
- Set up environment variables if working with products functionality
3. **Making Changes**
- **HTML Pages**: Edit individual `index.html` files in respective directories
- **Data Scripts**: Modify `*.sh` scripts for data generation logic
- **Deployment**: Update `sync.sh` for deployment configuration changes
4. **Testing Changes**
```bash
# Test data generation
./books.sh
./songs.sh
./products.sh
# Test locally
python3 -m http.server 8000
```
5. **Submitting Changes**
- Create feature branch: `git checkout -b feature/your-feature`
- Commit changes with descriptive messages
- Push to your fork and create a Pull Request
- Ensure all data generation scripts work correctly
### Code Style Guidelines
- **HTML**: Use semantic HTML5 elements, include proper meta tags
- **Shell Scripts**: Follow bash best practices, include error handling
- **JSON Data**: Ensure proper formatting and validation
- **Documentation**: Update relevant documentation for new features
### Areas for Contribution
- **UI/UX Improvements**: Enhance styling and user experience of static pages
- **Data Processing**: Improve metadata extraction and data generation scripts
- **New Features**: Add new utility pages or improve existing functionality
- **Documentation**: Expand user guides and technical documentation
- **Testing**: Add validation and testing for data generation processes
- **Accessibility**: Improve accessibility compliance across all pages
### Communication
- **Issues**: Report bugs and request features through GitHub Issues
- **Support**: Join the [chat server](https://chat.nhcarrigan.com) for discussion
- **Contact**: Reach out via email at `contact@nhcarrigan.com`
### Review Process
All Pull Requests are reviewed for:
- Code quality and adherence to project standards
- Functionality and testing
- Documentation updates
- Security considerations
- Compatibility with existing deployment process

320
src/content/docs/projects/website-headers.md Normal file
View File

@ -0,0 +1,320 @@
---
title: Website Headers
---
Website Headers (hereinafter the "Application") is a JavaScript/TypeScript library that injects standardized metadata, styles, and UI components (such as footers and modals) into web pages. It is designed to provide consistent branding, accessibility, and legal compliance for Naomi Carrigan's web properties. The Application dynamically adds Open Graph and Twitter meta tags, favicons, global styles, a themed footer, analytics scripts, and a community call-to-action modal. It also supports theme toggling and audio playback for enhanced user experience.
## 1. User Documentation
### What does this library do?
The Website Headers library automatically enhances any webpage by injecting:
- **SEO metadata**: Open Graph and Twitter Card meta tags for better social media sharing
- **Favicons**: Complete set of favicon files for various devices and platforms
- **Global styling**: Consistent branding with OpenDyslexic font, custom cursor, and themed UI
- **Footer component**: Standardized footer with copyright, social links, theme toggle, and donation button
- **Analytics**: Plausible Analytics integration with event tracking
- **Community features**: Periodic modal popup encouraging users to join the community
- **Theme support**: Light/dark theme toggle with localStorage persistence
- **Audio controls**: Optional theme music playback
- **TreeNation integration**: Carbon offset widget display
### Features
- **Accessibility-focused**: Uses OpenDyslexic font for improved readability
- **Responsive design**: Mobile-friendly layout with adaptive footer
- **Theme persistence**: Remembers user's theme preference across sessions
- **Privacy-respecting**: Uses privacy-focused Plausible Analytics
- **Performance optimized**: Minified production build with deferred script loading
- **Cross-platform**: Works on all modern browsers and devices
### Integration
Simply include the library script in your HTML:
```html
<script src="https://cdn.nhcarrigan.com/website-headers.js"></script>
```
The library will automatically enhance your page with all the features listed above.
## 2. Technical Documentation
### Prerequisites
- Node.js (latest LTS version recommended)
- pnpm package manager
- TypeScript knowledge for development
### Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd website-headers
```
2. Install dependencies:
```bash
pnpm install
```
### Development
#### Local Development Server
To work on the library locally with hot reloading:
```bash
pnpm dev
```
This command:
- Compiles TypeScript to JavaScript in watch mode
- Starts a development server on port 8080
- Serves a test HTML page at `http://localhost:8080`
- Automatically updates when you make changes
#### Building for Production
```bash
pnpm build
```
This command:
- Runs ESLint for code quality checks
- Compiles TypeScript to JavaScript
- Minifies the output using Terser
- Injects the current version number
- Outputs the final file to `prod/index.js`
#### Code Quality
```bash
pnpm lint
```
Runs ESLint with strict configuration to ensure code quality.
### Project Structure
```
src/
├── index.ts # Main library code
└── develop.ts # Development server
prod/
├── index.js # Production build output
└── develop.js # Development server build
build.ts # Build script with minification
index.html # Test page for development
package.json # Project configuration
tsconfig.json # TypeScript configuration
eslint.config.js # ESLint configuration
```
### Architecture
The library is structured as a single TypeScript file that:
1. **Metadata Injection**: Dynamically creates and injects meta tags for SEO and social sharing
2. **Asset Loading**: Loads external resources (fonts, scripts, stylesheets)
3. **Component Creation**: Builds UI components (footer, modal) and injects them into the DOM
4. **Event Handling**: Sets up interactive features (theme toggle, audio player, modal)
5. **State Management**: Manages theme preferences and modal display timing using localStorage
### Key Components
- **Meta Tags**: Open Graph and Twitter Card metadata
- **Favicon Management**: Complete favicon set for all platforms
- **Global Styles**: CSS-in-JS for consistent theming
- **Footer Component**: Branded footer with interactive elements
- **Modal System**: Community CTA with timing-based display logic
- **Theme System**: Light/dark mode with system preference detection
- **Analytics Integration**: Privacy-focused event tracking
### External Dependencies
The library loads several external resources:
- OpenDyslexic font for accessibility
- Font Awesome icons for UI elements
- Plausible Analytics for privacy-respecting tracking
- TreeNation widget for carbon offset display
- Google AdSense for monetization
### Environment Variables
- `npm_package_version`: Automatically injected during build process
## 3. Legal Documentation
### Licensing
This software is licensed under [Naomi's Public License](https://docs.nhcarrigan.com/legal/license).
**Copyright Notice**: Copyright held by Naomi Carrigan.
### Third-Party Services
The Application integrates with several third-party services that have their own terms of service and privacy policies:
#### Analytics and Tracking
- **Plausible Analytics**: Privacy-focused web analytics
- Domain: `analytics.nhcarrigan.com`
- Data collected: Page views, events, referrers (no personal data)
- Privacy policy: [Plausible Privacy Policy](https://plausible.io/privacy)
#### Advertising
- **Google AdSense**: Contextual advertising platform
- Client ID: `ca-pub-3569924701890974`
- May collect user data for ad personalization
- Privacy policy: [Google Privacy Policy](https://policies.google.com/privacy)
#### Environmental Impact
- **TreeNation**: Carbon offset and environmental impact tracking
- Widget code: `a17464e0cd351220`
- Purpose: Display environmental impact metrics
- Privacy policy: [TreeNation Privacy Policy](https://tree-nation.com/privacy)
#### Content Delivery
- **NHCarrigan CDN**: Custom content delivery network
- Domain: `cdn.nhcarrigan.com`
- Hosts: fonts, images, audio files, cursors
- Subject to NHCarrigan privacy policies
### Data Collection and Privacy
#### Local Storage Usage
The Application stores the following data in the user's browser:
- `theme`: User's preferred color scheme (light/dark)
- `naomi-community-cta`: Timestamp of last community modal display
#### External Resource Loading
The Application loads resources from external domains:
- Font files from `cdn.nhcarrigan.com`
- Analytics scripts from `analytics.nhcarrigan.com`
- Advertising scripts from `googlesyndication.com`
- Icons from Font Awesome CDN
### Compliance Considerations
Organizations using this library should be aware that it:
- Loads third-party tracking scripts
- May be subject to GDPR, CCPA, and other privacy regulations
- Includes advertising components that may require disclosure
- Collects analytics data that may need privacy policy updates
### Contact Information
For legal inquiries regarding this Application:
- Email: `contact@nhcarrigan.com`
- Community: [Chat Server](http://chat.nhcarrigan.com)
## 4. Contributing Documentation
### Getting Started
We welcome contributions to the website-headers project! Please review our [contributing guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before getting started.
### Development Workflow
1. **Fork the repository** and clone your fork locally
2. **Create a new branch** for your feature or bug fix:
```bash
git checkout -b feature/your-feature-name
```
3. **Install dependencies**:
```bash
pnpm install
```
4. **Start the development server**:
```bash
pnpm dev
```
5. **Make your changes** and test them at `http://localhost:8080`
6. **Run linting** to ensure code quality:
```bash
pnpm lint
```
7. **Build for production** to verify everything works:
```bash
pnpm build
```
8. **Commit your changes** and push to your fork
9. **Create a Pull Request** with a clear description of your changes
### Code Style and Standards
- **TypeScript**: All code must be written in TypeScript
- **ESLint**: Code must pass all linting rules (`@nhcarrigan/eslint-config`)
- **No warnings**: Build process fails if ESLint warnings are present
- **Comments**: Use JSDoc comments for functions and complex logic
- **Accessibility**: Maintain accessibility features (fonts, colors, ARIA labels)
### Testing
- **Manual Testing**: Use the development server to test changes
- **Cross-browser**: Test in multiple browsers when possible
- **Mobile Responsive**: Verify changes work on mobile devices
- **Theme Testing**: Test both light and dark themes
### Areas for Contribution
#### High Priority
- **Performance optimization**: Reduce bundle size, optimize loading
- **Accessibility improvements**: Enhanced ARIA support, keyboard navigation
- **Mobile experience**: Better responsive design, touch interactions
- **Browser compatibility**: Support for older browsers
#### Medium Priority
- **Documentation**: Improve inline code documentation
- **Error handling**: Add graceful fallbacks for external resource failures
- **Testing framework**: Implement automated testing
- **Configuration options**: Make the library more customizable
#### Low Priority
- **Additional themes**: More color scheme options
- **Animation effects**: Subtle transitions and animations
- **Internationalization**: Multi-language support
- **Advanced analytics**: More detailed event tracking
### Pull Request Guidelines
- **Clear title**: Descriptive title explaining the change
- **Detailed description**: Explain what changes were made and why
- **Screenshots**: Include before/after screenshots for UI changes
- **Testing notes**: Describe how you tested the changes
- **Breaking changes**: Clearly mark any breaking changes
- **Version impact**: Indicate if this should be a major, minor, or patch release
### Code Review Process
1. **Automated checks**: ESLint and build checks must pass
2. **Manual review**: Code will be reviewed for quality and functionality
3. **Testing**: Changes will be tested in various environments
4. **Feedback**: You may be asked to make additional changes
5. **Merge**: Once approved, changes will be merged to main branch
### Release Process
- **Semantic versioning**: We follow semver (major.minor.patch)
- **Automated builds**: Successful merges trigger automated builds
- **CDN deployment**: Production builds are deployed to CDN
- **Documentation updates**: Documentation is updated with releases
### Getting Help
- **Issues**: Open a GitHub issue for bugs or feature requests
- **Discussions**: Use GitHub Discussions for questions and ideas
- **Community**: Join our [chat server](http://chat.nhcarrigan.com) for real-time help
- **Email**: Contact us at `contact@nhcarrigan.com` for private inquiries
### Recognition
Contributors will be recognized in:
- Git commit history
- Release notes
- Project documentation
- Community acknowledgments