Content Policy Platform - Complete Documentation

📋 Project Overview

🌐

API Gateway & User Portal

Full-stack application built with Ballerina backend and Next.js frontend providing user authentication, API key management, and usage analytics.

🔐 JWT Authentication System
🔑 API Key Management (Max 3/user)
📊 Usage Analytics & Quota Tracking
💻 React-based Web Dashboard

🐍

Python RAG API

FastAPI-based content moderation service with AI-powered analysis using Google Gemini and ChromaDB vector database.

🛡️ AI-Powered Content Moderation
📚 Vector Database Integration
🎯 Custom Rule Management
🔒 Multi-User Environment Support

🏗️ System Architecture

High-Level Architecture

Frontend Layer

Next.js 15 with React 19, TypeScript, and Tailwind CSS for modern, responsive UI

API Gateway Layer

Ballerina Swan Lake backend with SQLite database and JWT authentication

AI Moderation Layer

FastAPI with ChromaDB vector database and Google Gemini AI integration

🎥 Video Demo

Platform Walkthrough

Watch this comprehensive demo to see the Content Policy Platform in action, including user authentication, API key management, content moderation setup, and real-time testing of the AI-powered moderation system.

User Portal Demo API Key Creation Content Moderation Real-time Testing

📁 Project Structure

Complete Project Layout

The project consists of two main applications with comprehensive documentation and testing scripts.

                                    
                                    
                                    
                                
Project Directory Tree

                                📂 Moderato/
├── 📁 apigateway-v1/                    // API Gateway & User Portal
│   ├── 📁 .github/workflows/
│   │   └── 📄 ci.yml                   // GitHub Actions CI/CD
│   ├── 📁 ballerina-backend/            // Ballerina API Service
│   │   ├── 📁 database/
│   │   │   ├── 📄 schema.sql
│   │   │   └── 📄 sqlite-schema.sql
│   │   ├── 📄 main.bal                 // HTTP service & endpoints
│   │   ├── 📄 auth.bal                 // JWT authentication
│   │   ├── 📄 database.bal             // SQLite operations
│   │   ├── 📄 apikeys.bal              // API key management
│   │   ├── 📄 quota.bal                // Usage tracking
│   │   ├── 📄 types.bal                // Data models
│   │   ├── 📄 utils.bal                // Utilities
│   │   ├── 📄 api-endpoints.bal        // Public API endpoints
│   │   ├── 📄 Ballerina.toml           // Project configuration
│   │   └── 📄 README.md
│   ├── 📁 userportal/                   // Next.js Frontend
│   │   ├── 📁 app/                     // Next.js app router
│   │   │   ├── 📁 api-testing/
│   │   │   ├── 📁 apikeys/
│   │   │   ├── 📁 auth/
│   │   │   ├── 📁 docs/
│   │   │   ├── 📁 settings/
│   │   │   ├── 📄 layout.tsx
│   │   │   └── 📄 page.tsx
│   │   ├── 📁 components/               // React components
│   │   │   ├── 📄 ApiKeyManagement.tsx
│   │   │   ├── 📄 DashboardHome.tsx
│   │   │   ├── 📄 LoginForm.tsx
│   │   │   └── 📄 ... (15+ components)
│   │   ├── 📁 hooks/                   // Custom React hooks
│   │   ├── 📁 lib/                     // Utility libraries
│   │   ├── 📄 package.json
│   │   └── 📄 tsconfig.json
│   ├── 📄 API_DOCUMENTATION.md          // Complete API docs
│   ├── 📄 README.md                    // Main documentation
│   └── 📄 *.bat, *.sh, *.ps1           // Testing & setup scripts
├── 📁 python-rag-api/                  // AI Content Moderation API
│   ├── 📁 app/
│   │   ├── 📁 core/
│   │   │   └── 📄 config.py            // Environment configuration
│   │   ├── 📁 endpoints/
│   │   │   └── 📄 moderation.py        // API endpoints
│   │   ├── 📄 main.py                  // FastAPI application
│   │   ├── 📄 services.py              // Business logic
│   │   └── 📄 schemas.py               // Pydantic models
│   ├── 📁 chroma_db/                   // Vector database storage
│   ├── 📄 requirements.txt             // Python dependencies
│   ├── 📄 test_client.html             // HTML test interface
│   └── 📄 README.md
├── 📁 docs/                            // Documentation Website
│   ├── 📄 index.html                   // Main documentation page
│   ├── 📄 styles.css                   // Dark theme styling
│   └── 📄 script.js                    // Interactive functionality
└── 📄 COMPLETE_PROJECT_DOCUMENTATION.md // Comprehensive guide
                            

🛠️ Technology Stack

Backend

Ballerina Swan Lake FastAPI SQLite ChromaDB Google Gemini AI

Frontend

Next.js 15 React 19 TypeScript Tailwind CSS 4 Heroicons

Security

JWT Tokens SHA256 Hashing API Key Auth CORS Environment Variables

🌐 API Gateway & User Portal

🔐 Authentication System

User Registration/Login: Email validation and secure password handling
JWT Token Management: 1-hour expiry with secure token tracking
Password Security: SHA256 hashing with salt protection
Token Revocation: Immediate invalidation on logout

🔑 API Key Management

Secure Generation: 32-character hash with 'ak_' prefix
User Limits: Maximum 3 API keys per user account
Status Control: Active/inactive/revoked states
Usage Tracking: Lifetime and monthly statistics

📊 Quota System

Monthly Limits: 100 requests per API key per month
Auto Reset: Automatic quota reset on first day of month
Real-time Monitoring: Live usage updates and warnings
Enforcement: HTTP 429 when quota exceeded

🐍 Python RAG API

🤖 AI-Powered Moderation

Google Gemini Integration: Advanced language model for content analysis
Semantic Rule Matching: Vector similarity search for relevant rules
Multi-Rule Evaluation: Comprehensive analysis against multiple policies
Confidence Scoring: Detailed reasoning for moderation decisions

📚 Vector Database

ChromaDB Integration: Efficient semantic search capabilities
Rule Storage: Persistent storage with metadata and context
Top-K Retrieval: Finds 5 most relevant rules per query
Auto Initialization: Automatic database setup and management

🎯 Custom Rules

User-Specific Rules: Organized by API key and user ID
CRUD Operations: Complete rule lifecycle management
Flexible Format: Support for complex, multi-paragraph policies
Real-time Updates: No service restart required for rule changes

🚀 Quick Start Guide

1

Prerequisites

# Required Software
- Ballerina Swan Lake (2201.10.0+)
- Node.js (18.0+)
- Python (3.11+)
- Java (11+) for Ballerina

2

Start API Gateway

# Backend (Ballerina)
cd apigateway-v1/ballerina-backend
bal run

# Frontend (Next.js)
cd apigateway-v1/userportal
npm install
npm run dev

3

Start Python RAG API

# Setup Environment
cd python-rag-api
python -m venv .venv
.venv\Scripts\activate  # Windows

# Install & Configure
pip install -r requirements.txt
# Create .env with GEMINI_API_KEY

# Start Service
uvicorn app.main:app --reload

4

Access Applications

🌐 User Portal localhost:3000 ⚡ API Gateway localhost:8080 🐍 Python API 127.0.0.1:8000

📚 API Documentation

API Gateway Endpoints (Port 8080)

Authentication

POST /api/auth/register User registration

POST /api/auth/login User login

GET /api/auth/profile User profile (protected)

API Key Management

POST /api/apikeys Create API key

GET /api/apikeys List user's keys

PUT /api/apikeys/{id}/status Enable/disable key

Python RAG API Endpoints (Port 8000)

Rule Management

POST /add-rule/ Add moderation rule

GET /rules/{user_id}/{api_key}/ Get user's rules

DELETE /delete-rule/{rule_id}/ Delete specific rule

Content Moderation

POST /moderate/ Moderate text content

🎯 Use Cases

📱

Social Media Platform

AI-powered content moderation for user-generated content with custom community guidelines and real-time analysis.

Real-time Moderation Custom Rules Multi-language

🏢

Enterprise SaaS

Multi-tenant content policy management with client isolation and environment-specific rule sets.

Client Isolation Environment Separation Compliance

💻

Developer Platform

API key management with quota tracking and usage analytics for development teams.

Quota Management Team Access Analytics