GuardDen/DEV_GUIDE.md

GuardDen Development Guide

This guide provides everything you need to start developing GuardDen locally.

🚀 Quick Start

# 1. Clone the repository
git clone <repository-url>
cd GuardDen

# 2. Set up development environment
./scripts/dev.sh setup

# 3. Configure environment variables
cp .env.example .env
# Edit .env with your Discord bot token and other settings

# 4. Start development environment
./scripts/dev.sh up

# 5. Run tests to verify setup
./scripts/dev.sh test

📋 Development Commands

The ./scripts/dev.sh script provides comprehensive development automation:

Environment Management

./scripts/dev.sh setup           # Set up development environment
./scripts/dev.sh up              # Start development containers
./scripts/dev.sh down            # Stop development containers
./scripts/dev.sh logs [service]  # Show logs (optional service filter)
./scripts/dev.sh clean           # Clean up development artifacts

Code Quality

./scripts/dev.sh test            # Run tests with coverage
./scripts/dev.sh lint            # Run code quality checks
./scripts/dev.sh format          # Format code with ruff
./scripts/dev.sh security        # Run security scans

Database Management

./scripts/dev.sh db migrate      # Run database migrations
./scripts/dev.sh db revision "description"  # Create new migration
./scripts/dev.sh db reset        # Reset database (destructive)

Health & Monitoring

./scripts/dev.sh health check    # Run health checks
./scripts/dev.sh health json     # Health checks with JSON output

Docker Operations

./scripts/dev.sh build           # Build Docker images (bot + dashboard)

🐳 Development Services

When you run ./scripts/dev.sh up, the following services are available:

Service	URL	Purpose
GuardDen Bot	-	Discord bot with hot reloading
Dashboard	http://localhost:8080	Web interface
PostgreSQL	localhost:5432	Database
Redis	localhost:6379	Caching & sessions
PgAdmin	http://localhost:5050	Database administration
Redis Commander	http://localhost:8081	Redis administration
MailHog	http://localhost:8025	Email testing

🖥️ Dashboard Frontend

The dashboard backend serves static assets from dashboard/frontend/dist.

Build the static assets:

cd dashboard/frontend
npm install
npm run build

Or run the Vite dev server for UI iteration:

cd dashboard/frontend
npm install
npm run dev

The Vite dev server runs at http://localhost:5173.

The Vite dev server proxies /api and /auth to http://localhost:8000. If you're using the Docker dev stack (dashboard at http://localhost:8080), either run the dashboard backend locally on port 8000 or update the proxy target.

🧪 Testing

Running Tests

# Run all tests with coverage
./scripts/dev.sh test

# Run specific test files
pytest tests/test_config.py

# Run tests with verbose output
pytest -v

# Run tests in parallel (faster)
pytest -n auto

Test Structure

• tests/conftest.py - Test fixtures and configuration
• tests/test_*.py - Test modules
• Test coverage reports in htmlcov/

Writing Tests

• Use pytest with async support (pytest-asyncio)
• Comprehensive fixtures available for database, Discord mocks, etc.
• Follow naming convention: test_* functions in Test* classes

🔧 Code Quality

Pre-commit Hooks

Pre-commit hooks are automatically installed during setup:

• Ruff: Code formatting and linting
• MyPy: Type checking
• Tests: Run tests on relevant changes

Manual Quality Checks

# Run all quality checks
./scripts/dev.sh lint

# Format code
./scripts/dev.sh format

# Type checking only
mypy src

# Security scanning
./scripts/dev.sh security

Code Style

• Line Length: 100 characters (configured in pyproject.toml)
• Imports: Sorted with ruff
• Type Hints: Required for all public functions
• Docstrings: Google style for modules and classes

📊 Monitoring & Debugging

Structured Logging

from guardden.utils.logging import get_logger, bind_context

logger = get_logger(__name__)

# Log with context
bind_context(user_id=123, guild_id=456)
logger.info("User performed action", action="kick", target="user#1234")

Metrics Collection

from guardden.utils.metrics import get_metrics

metrics = get_metrics()
metrics.record_command("ban", guild_id=123, status="success", duration=0.5)

Health Checks

# Check application health
./scripts/dev.sh health check

# Get detailed JSON health report
./scripts/dev.sh health json

🗄️ Database Development

Migrations

# Create new migration
./scripts/dev.sh db revision "add new table"

# Run migrations
./scripts/dev.sh db migrate

# Rollback one migration
./scripts/dev.sh db downgrade

Database Access

• PgAdmin: http://localhost:5050 (admin@guardden.dev / admin)
• Direct connection: localhost:5432 (guardden / guardden_dev)
• Test database: In-memory SQLite for tests

🐛 Debugging

Debug Mode

Development containers include debugging support:

• Bot: Debug port 5678
• Dashboard: Debug port 5679

VS Code Configuration

Add to .vscode/launch.json:

{
    "name": "Attach to Bot",
    "type": "python",
    "request": "attach",
    "host": "localhost",
    "port": 5678
}

Log Analysis

# Follow all logs
./scripts/dev.sh logs

# Follow specific service logs
./scripts/dev.sh logs bot
./scripts/dev.sh logs dashboard

🔐 Security

Environment Variables

• Required: GUARDDEN_DISCORD_TOKEN
• Database: GUARDDEN_DATABASE_URL (auto-configured for development)
• AI: GUARDDEN_ANTHROPIC_API_KEY or GUARDDEN_OPENAI_API_KEY

Security Best Practices

• Never commit secrets to version control
• Use .env for local development secrets
• Run security scans regularly: ./scripts/dev.sh security
• Keep dependencies updated

🚀 Deployment

Building for Production

# Build optimized image
docker build -t guardden:latest .

# Build with AI dependencies
docker build --build-arg INSTALL_AI=true -t guardden:ai .

CI/CD Pipeline

• GitHub Actions: Automated testing, security scanning, and deployment
• Quality Gates: 75%+ test coverage, type checking, security scans
• Automated Deployments: Staging (develop branch) and production (releases)

🆘 Troubleshooting

Common Issues

Port conflicts:

# Check what's using a port
lsof -i :5432

# Use different ports in .env
POSTGRES_PORT=5433
REDIS_PORT=6380

Permission errors:

# Fix Docker permissions
sudo chown -R $USER:$USER data logs

Database connection errors:

# Reset development environment
./scripts/dev.sh down
./scripts/dev.sh clean
./scripts/dev.sh up

Test failures:

# Run tests with more verbose output
pytest -vvs

# Run specific failing test
pytest tests/test_config.py::TestSettingsValidation::test_discord_token_validation_valid -vvs

Getting Help

1. Check logs: ./scripts/dev.sh logs
2. Run health check: ./scripts/dev.sh health check
3. Verify environment: ./scripts/dev.sh setup
4. Check GitHub Issues for known problems

---

Happy coding! 🎉