ShadowCore

Discord server management dashboard with real-time moderation, roles, configuration, automations, analytics, logs, and announcements.

Overview

ShadowCore is a single-guild Discord operations panel built as a full-stack application:

• client: Next.js 16 dashboard (App Router, TypeScript, Tailwind)
• server: Express API + Discord bot runtime (Node.js, discord.js)
• shared: Shared contracts and constants used across client and server

The system is designed for one configured guild (DISCORD_GUILD_ID) and role-gated access using Discord OAuth2.

Core Capabilities

• Moderation: Kick, ban, timeout, unban, member history, live updates
• Roles: Create, edit, delete, assign, remove, managed/custom role views
• Configuration: Logging channels, moderation defaults, welcome/leave, anti-spam
• Automations: Trigger-action workflows with runtime stats and execution history
• Announcements: Channel posting, embed composer, history, reuse, delete
• Analytics: Guild health, member/channel/role metrics, service status snapshot
• Audit Logs: Filterable event timeline with structured details

Architecture

Browser (Next.js client)
        |
        | HTTP + Cookies (session auth)
        v
Express API (server)
        |
        | MongoDB (persistence)
        v
Database

Express API <-> Socket.IO <-> Browser (live updates)
Express API <-> Discord.js Bot <-> Discord API

Tech Stack

• Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS
• Backend: Express, Node.js, JavaScript (ESM)
• Bot: discord.js v14
• Database: MongoDB + Mongoose
• Auth: Discord OAuth2 + session cookies
• Realtime: Socket.IO

Project Structure

Shadowcore/
├── client/
│   ├── app/
│   ├── components/
│   ├── hooks/
│   ├── lib/
│   ├── public/
│   └── types/
├── server/
│   ├── src/
│   ├── scripts/
│   └── logs/
└── shared/
    └── contracts/

Prerequisites

• Node.js 18 or newer
• pnpm
• MongoDB (local or Atlas)
• Discord application with bot + OAuth2 configured

Environment Setup

Create and fill:

• server/.env
• client/.env.local

Server (server/.env)

NODE_ENV=development
PORT=5000
MONGODB_URI=mongodb://localhost:27017/shadowcore

DISCORD_BOT_TOKEN=your_bot_token
DISCORD_CLIENT_ID=your_client_id
DISCORD_CLIENT_SECRET=your_client_secret
DISCORD_GUILD_ID=your_guild_id
OAUTH_REDIRECT_URI=http://localhost:3000/auth/callback

SESSION_SECRET=your_session_secret
JWT_SECRET=your_jwt_secret
AUTHORIZED_ROLES=role_id_1,role_id_2
CLIENT_URL=http://localhost:3000

Client (client/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_SOCKET_URL=http://localhost:5000
NEXT_PUBLIC_DISCORD_CLIENT_ID=your_client_id
NEXT_PUBLIC_GUILD_ID=your_guild_id

Installation

pnpm --dir server install
pnpm --dir client install

Development

Run server and bot:

pnpm --dir server dev

Run client in a second terminal:

pnpm --dir client dev

Default local URLs:

• Client: http://localhost:3000
• API: http://localhost:5000

Validation

pnpm --dir client lint
pnpm --dir client build

Notes

• Backend API and Discord bot run in the same Node.js process.
• Socket events are used extensively for real-time dashboard sync.
• Current design target is one guild per deployment.

License

MIT