Quick Start

Prerequisites

Before getting started, ensure you have the following installed on your machine:

• Docker & Docker Compose
• uv (Python package installer and resolver)
• PostgreSQL with pgvector (The backend requires vector similarity features for content detection)

Installation

1. Clone the repository:

   git clone https://github.com/JadoreThompson/gova-backend.git
   cd gova-backend
   

2. Install dependencies using uv:

   uv sync
   

3. Configure environment variables: Create a .env file in the root directory. You will need to provide credentials for your database, Discord Application, Stripe, and Kafka.

   DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/gova
   STRIPE_API_KEY=your_stripe_key
   DISCORD_CLIENT_ID=your_id
   DISCORD_CLIENT_SECRET=your_secret
   KAFKA_BOOTSTRAP_SERVERS=localhost:9092
   

Running with Docker

The easiest way to start the required infrastructure (Database, Vector store, and Kafka) is via Docker Compose:

docker-compose up -d

This will spin up:

• PostgreSQL with the pgvector extension.
• Kafka & Zookeeper for event-driven moderation tasks.

Starting the API

Once your infrastructure is live, start the FastAPI server using the built-in runner:

uv run python -m runners.api_runner

By default, the API will be available at http://localhost:8000. You can access the interactive Swagger documentation at http://localhost:8000/docs.

Core Workflow Example

1. Register and Authenticate

Create a user account to receive your JWT.

curl -X 'POST' \
  'http://localhost:8000/auth/register' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "admin_user",
  "email": "admin@example.com",
  "password": "SecurePassword123!!"
}'

2. Connect a Platform

Link your Discord account via the OAuth flow. The backend handles the handshake and encrypts your credentials.

• Navigate to: http://localhost:8000/auth/discord/oauth

3. Create a Moderator

Initialize an automated moderator for a specific Discord server.

curl -X 'POST' \
  'http://localhost:8000/moderators/' \
  -H 'Authorization: Bearer <YOUR_JWT>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "General Chat Sentry",
  "platform": "discord",
  "platform_server_id": "1234567890",
  "conf": {
    "rules": ["no toxicity", "no spam"],
    "threshold": 0.8
  }
}'

4. Approve Pending Actions

When the AI detects a violation that requires manual approval, use the actions endpoint:

curl -X 'POST' \
  'http://localhost:8000/actions/<action_id>/approve' \
  -H 'Authorization: Bearer <YOUR_JWT>'