PigBot

A multi-service appliance for Bleu Pigs community management, built with BleuMoon (Luau Runtime).

Overview

PigBot is designed to run as microservices within Docker containers, providing:

• Membership Application Process — Quality-controlled community onboarding with voting, probation, and maintenance tracking
• Roblox News Updates — Automated monitoring and distribution of official Roblox announcements
• Community Engagement — Activity tracking, weekly challenges, member spotlights, rewards, and inactivity management
• Audit Logging — Comprehensive event tracking far beyond Discord's native audit log
• Case-Based Framework — Structured management for applications, moderation, change requests, features, bugs, and appeals

Architecture

PigBot runs as 7 microservices communicating via an HTTP event bus:

Service	Description	Port
Gateway	Discord WebSocket connection, event fanout, REST proxy	4000
Audit	Event capture, storage, log feeds, alerts	4001
Cases	Case lifecycle, slash commands, threads	4002
Membership	Applications, probation, web UI (membership.bleupigs.club)	4003
Engagement	Activity tracking, challenges, rewards, VC notifications	4004
News	Roblox source polling, categorization, distribution	4005
Admin	Community Admin Center web UI (admin.bleupigs.club)	4006

All services share a PostgreSQL database. The Gateway service is the sole Discord WebSocket connection and distributes events to subscriber services via HTTP POST.

Prerequisites

• BleuMoon v1.0.0 or later
• StyLua (for code formatting)
• Docker & Docker Compose (for deployment)
• PostgreSQL 16+ (external, or via Docker Compose for development)

Tip: If you have Nix with flakes enabled, BleuMoon and StyLua are provided automatically via nix develop.

Getting Started

1. Clone and set up

git clone https://git.ds.reinitialized.net/bleupigs.club/pigbot.git
cd pigbot
nix develop  # or install BleuMoon + StyLua manually

2. Install dependencies

bleumoon pkg install

3. Configure environment

cp .env.example .env
# Edit .env with your Discord bot token, Roblox API keys, database URL, etc.

4. Run with Docker Compose (development)

docker compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml up --build

This starts all 7 microservices plus PostgreSQL 16 in Docker containers with hot-reload volume mounts.

5. Run with Docker Compose (production)

# Copy and fill in production secrets
cp docker/environments/prod.env.example docker/environments/prod.env

# Pull pre-built images and start
docker compose -f docker/docker-compose.yml -f docker/docker-compose.prod.yml up -d

Production assumes an external PostgreSQL instance configured via DATABASE_URL in prod.env.

6. Build and push images to Forgejo registry

# Build the image
docker build -f docker/Dockerfile.service -t git.ds.reinitialized.net/bleupigs.club/pigbot:latest .

# Tag a version
docker tag git.ds.reinitialized.net/bleupigs.club/pigbot:latest \
  git.ds.reinitialized.net/bleupigs.club/pigbot:1.0.0-alpha.6

# Push
docker push git.ds.reinitialized.net/bleupigs.club/pigbot:latest
docker push git.ds.reinitialized.net/bleupigs.club/pigbot:1.0.0-alpha.6

7. Run a single service locally

bleumoon run src/gateway

Running Tests

bleumoon run tests/init

Formatting

stylua --check .   # Check
stylua .           # Apply

Project Structure

├── bleumoon.toml              # Project manifest & dependencies
├── .env.example               # Environment variable template
├── .dockerignore              # Docker build context ignore rules
├── docs/
│   ├── architecture/          # Architecture Decision Records
│   └── investigations/        # Bug investigation write-ups
├── docker/
│   ├── Dockerfile.service     # Multi-service Dockerfile
│   ├── docker-compose.yml     # Base service definitions
│   ├── docker-compose.dev.yml # Development overrides (+ PostgreSQL)
│   ├── docker-compose.prod.yml# Production overrides
│   └── environments/
│       ├── dev.env            # Dev environment (tracked in git)
│       └── prod.env.example   # Production template (prod.env is gitignored)
├── src/
│   ├── main.luau              # Entry point (prints version info)
│   ├── shared/                # Shared modules (config, database, eventbus, templates, types)
│   ├── gateway/               # Gateway service (Discord connection + event fanout)
│   ├── audit/                 # Audit Logging service
│   ├── cases/                 # Case Framework service
│   ├── membership/            # Membership Application service + web UI
│   ├── engagement/            # Community Engagement service
│   ├── news/                  # Roblox News service
│   └── admin/                 # Community Admin Center web UI
├── tests/                     # Test suites (bleutest)
├── planning/                  # Implementation plans
├── packages/                  # Installed dependencies (gitignored)
└── types/                     # Auto-generated type definitions (gitignored)

License

This project is licensed under the MIT License.