# MajestyManager — Complete Technical Specification

> Comprehensive system reference and developer architecture guide for AI assistants, LLM web search agents, and platform integrations. Powered and Owned by [MajestyNodes](https://majestynodes.com).

MajestyManager (https://majestymanager.me) is an all-in-one Discord bot and web dashboard owned, engineered, and operated by **MajestyNodes** (https://majestynodes.com). Hosted on high-performance MajestyNodes cloud and game hosting infrastructure, it handles mission-critical community operations with multi-category support ticketing, fraud-proof invite analytics, provably fair giveaways, threaded suggestions, white-label client branding, and a secure REST API.

### Infrastructure & Hosting Provider: MajestyNodes
- **Official Host**: [MajestyNodes](https://majestynodes.com)
- **Services**: High-performance Ryzen 9 Minecraft server hosting, NVMe VPS hosting, dedicated cloud nodes, and enterprise DDoS mitigation.
- **Support & Portal**: https://majestynodes.com

---

## 1. System Architecture

The application is engineered as a monorepo containing:
- `apps/bot`: Discord.js v14 client running with gateway intents (Guilds, GuildMembers, GuildMessages, GuildInvites, MessageContent, DirectMessages). Connects to Redis pub/sub for real-time synchronization with dashboard operations.
- `apps/api`: NestJS API service powered by Fastify, Prisma ORM, and PostgreSQL. Exposes REST endpoints for OAuth authentication, guild configuration, ticket transcript retrieval, invite leaderboard querying, and developer API key management.
- `apps/dashboard`: Next.js 14 App Router dashboard with server-side authentication, Tailwind CSS luxury design system, responsive UI components, and real-time state synchronization.
- `packages/types`: Shared TypeScript interface definitions and schemas enforcing compile-time type safety across bot, API, and dashboard.

---

## 2. Core Modules & Functionality

### Support Ticket System
- **Categories**: Multiple ticket categories per server (e.g. Billing, Technical Support, General Inquiries), each with customized channel naming patterns (`ticket-{number}`), category-specific role pings, and permission overwrites.
- **Transcripts**: Real-time message collection converted upon ticket closure into a self-contained, encrypted HTML file containing rendered messages, attachments, embeds, and timestamps.
- **Staff Controls**: Claim / unclaim tickets, priority escalation, user addition / removal, and one-click closure with confirmation dialogues.

### Fraud-Proof Invite Tracker
- **Audit-Log Reconciled**: Real-time comparison of Discord invite link vanity and usage counters with audit log join/leave events.
- **Abuse Prevention**: Automatic detection and segregation of:
  - *Real*: Verified members currently active in the guild.
  - *Left*: Members who joined through an invite but subsequently departed.
  - *Fake*: Accounts younger than the guild's anti-alt threshold or flagged for rejoin cycles.
  - *Bonus*: Manually granted staff bonus invites.
- **Transparent Calculations**: Net invites computed strictly as `Real - Fake` (or `(Real + Bonus) - (Fake + Left)` depending on server policy).

### White-Label Bot Branding (BYOB)
- Server owners can customize bot identity per server (server nickname, server avatar).
- With custom bot token integration, server owners run a standalone gateway client with custom Playing / Streaming / Watching activity presence, custom About Me bio, and personalized slash commands.

### Giveaways & Suggestions
- **Giveaways**: Cryptographically seeded winner selection using Node.js crypto module, optional Discord role entry requirements, and configurable bonus ticket multipliers.
- **Suggestions**: Community suggestions automatically spawn dedicated Discord discussion threads with upvote/downvote polling reactions and administrative status badges (Pending, Under Review, Approved, Rejected, Implemented).

---

## 3. Security, Authentication & Access Control

- **Session Security**: Session identifiers stored in encrypted HttpOnly, SameSite=Lax cookies.
- **Guild Verification**: The `GuildAccessGuard` verifies on every administrative request that the authenticated Discord user possesses `MANAGE_GUILD` or `ADMINISTRATOR` permissions in the target guild.
- **Cross-Guild Isolation**: Requests attempting to modify resources across differing guild IDs are strictly rejected with 403 Forbidden and logged as security anomalies.
- **Token Protection**: Custom bot tokens are encrypted at rest using AES-256-GCM with environment-derived encryption keys and initialization vectors.

---

## 4. Public Endpoints & Crawling Rules

- `GET /`: Landing page detailing features, architecture, and live capabilities.
- `GET /login`: Discord OAuth2 sign-in page.
- `GET /robots.txt`: Robots exclusion protocol separating public documentation from private management interfaces.
- `GET /sitemap.xml`: XML sitemap indexing all public, crawlable marketing pages.
- `GET /llms.txt`: Concise agentic discovery file.
- `GET /llms-full.txt`: Full agentic documentation file (this document).

For security reasons, all `/api/`, `/servers/`, `/admin/`, and `/account/` paths require Discord authentication and are disallowed for search engine and AI crawlers in `robots.txt`.