NeonFlux

A multi functional bot for Fluxer

    

Initial Plan

NeonFlux is planned as a Fluxer bot with a web dashboard and Convex-backed live dashboard data.

It supports two modes:

• Single instance: one bot for one configured guild.
• Multi instance: one bot can serve multiple guilds.

The planned feature areas are:

• Autorole
• Bot installation sync and reconciliation
• Command help
• Convex dashboard data
• Dashboard access for single and multi instance
• Dashboard audit events
• Dashboard server overview and growth tracking
• Docker / GHCR deployment
• Free game alerts
• Fumadocs documentation under /docs
• Giveaways
• Import/export for roles, channels, categories, emojis, and permissions
• Invite tracker
• Logging
• Message and embed posting
• Moderation
• OAuth login, sessions, and refreshed permissions
• Profile / about me embed builder
• Public/private tickets
• Public web URL and generated links
• Reaction roles
• Suggestion voting
• Verification reaction roles
• Voice channel generator
• XP / levels

The goal is to build the bot in small, clear pieces and keep shared logic reusable between the bot and web app.

Repo Beats

Star Map

Project Shape

The main workspace is in Projects.

• apps/bot: Fluxer bot process
• apps/web: web dashboard
• packages/config: shared env parsing
• packages/convex: shared Convex client and JWT helpers
• convex: Convex functions and the generated @neonflux/convex-api workspace package
• packages/db: runtime database boundary
• packages/core: shared bot/web rules
• packages/fluxer: Fluxer API and permission helpers

Environment Setup

Use pnpm from the Projects folder. Environment values live in Projects/.env; the tracked template is Projects/.env.example.

Start a local env file:

cd Projects
cp .env.example .env

On Windows PowerShell, use Copy-Item .env.example .env.

Generate separate secrets for every environment. Do not reuse dev values in production.

pnpm generate:session-secret
pnpm generate:token-encryption-key
pnpm generate:convex-private-key

Put those outputs in SESSION_SECRET, FLUXER_TOKEN_ENCRYPTION_KEY, and NEONFLUX_AUTH_JWT_PRIVATE_KEY.

After NEONFLUX_AUTH_JWT_PRIVATE_KEY and the intended NEONFLUX_AUTH_JWT_ISSUER are set, generate the public JWKS value:

pnpm --silent generate:convex-jwks

Put the output in NEONFLUX_AUTH_JWT_JWKS. Convex receives issuer, audience, and this public JWKS value only. Do not send NEONFLUX_AUTH_JWT_PRIVATE_KEY, SESSION_SECRET, Fluxer secrets, or token encryption keys to Convex.

Development

For local development, keep the app issuer local and point OAuth back to localhost:

APP_ENV=development
NODE_ENV=development
PUBLIC_WEB_URL=
FLUXER_OAUTH_REDIRECT_URL=http://localhost:3000/auth/fluxer/callback
NEONFLUX_AUTH_JWT_ISSUER=http://localhost:3000/auth
NEONFLUX_AUTH_JWT_AUDIENCE=neonflux-convex
CONVEX_DEPLOYMENT=<dev Convex deployment>
CONVEX_URL=<dev Convex URL>
VITE_CONVEX_URL=<dev Convex URL>

Then validate the selected Convex target and run the processes you need:

pnpm convex:check-auth-env
pnpm dev:bot
pnpm dev:web

For dashboard routes, start the bot before the web app so the bot can bootstrap deployment config and runtime guild state. The homepage and docs can run with only pnpm dev:web. Local development does not require app Postgres. Convex is the durable store target.

Production

Production uses the same variable names with production values:

APP_ENV=production
NODE_ENV=production
PUBLIC_WEB_URL=https://<your NeonFlux web host>
FLUXER_OAUTH_REDIRECT_URL=https://<your NeonFlux web host>/auth/fluxer/callback
NEONFLUX_AUTH_JWT_ISSUER=https://<your NeonFlux web host>/auth
NEONFLUX_AUTH_JWT_AUDIENCE=neonflux-convex
CONVEX_DEPLOYMENT=<production Convex deployment>
CONVEX_URL=<production Convex URL>
VITE_CONVEX_URL=<production Convex URL>

NEONFLUX_AUTH_JWT_ISSUER is a NeonFlux issuer, not the Fluxer OAuth host. Use protected environment variables or a secret store for production secrets. Keep CONVEX_DEPLOY_KEY protected for deploy automation.

Dry-run the public Convex auth update before applying it:

pnpm convex:configure-auth-env -- --issuer https://<your NeonFlux web host>/auth --deployment <production Convex deployment>

Apply only after the dry-run targets the intended deployment:

pnpm convex:configure-auth-env -- --issuer https://<your NeonFlux web host>/auth --deployment <production Convex deployment> --apply --confirm-apply-target <production Convex deployment>
pnpm convex:check-auth-env -- --compare-deploy-env
pnpm convex:deploy

See Docs/Convex.md for the full Convex auth and deploy workflow.

Convex

NeonFlux uses Convex for durable state and live dashboard data. To self-host Convex separately from NeonFlux app data, see Docs/Convex.md.

Docker

Docker users can run NeonFlux with the published GHCR images for the bot and web app.

See Docs/Docker.md for the Docker Compose guide, including environment setup through Projects/.env.example. The main stack is Projects/docker-compose.yml; the optional Convex stack is Projects/docker-compose.convex.yml.