🛡️ Radix Abuse Mitigation System

A comprehensive full-stack solution for tracking and managing domain abuse reports with automated risk assessment and enterprise-grade dashboard

---

📋 Overview

This monorepo contains a complete Trust & Safety platform with two main components:

• Backend API - RESTful API with JWT authentication, automated risk detection, and comprehensive report management
• Frontend Dashboard - Professional web interface for monitoring and managing abuse reports

---

🚀 Quick Start

Prerequisites

• Node.js v18.17.0 or higher
• npm v9.0.0 or higher

Installation

# 1. Install backend dependencies
cd backend
npm install

# 2. Configure backend environment
cp .sample.env .env
# Edit .env with your configuration

# 3. Start backend server (Port 3000)
npm run dev

# 4. In a new terminal, install frontend dependencies
cd ../frontend
npm install

# 5. Start frontend (Port 3001)
npm run dev

Access the Application

• Frontend Dashboard: http://localhost:3001
• Backend API: http://localhost:3000
• Default Credentials:
  • Username: admin
  • Password: admin123

---

📂 Project Structure

radix-assignment/
├── backend/                    # Express.js REST API
│   ├── config/                # Database and constants
│   ├── controller/            # Business logic
│   ├── middleware/            # Auth, logging, error handling
│   ├── routes/                # API endpoints
│   ├── tests/                 # Jest test suite (110 tests)
│   ├── database/              # SQLite database
│   ├── .env.example           # Environment template
│   ├── package.json
│   ├── server.js              # Entry point
│   └── README.md              # 📖 Detailed backend documentation
│
├── frontend/                   # Next.js 15 Dashboard
│   ├── app/                   # Next.js App Router
│   ├── components/            # React components
│   ├── lib/                   # API client, auth, utilities
│   ├── public/                # Static assets
│   ├── package.json
│   └── README.md              # 📖 Detailed frontend documentation
│
└── README.md                   # This file

---

📚 Documentation

Each component has comprehensive documentation:

🔧 Backend Documentation

Location: backend/README.md

Topics Covered:

• Complete API reference with cURL examples
• Authentication & JWT configuration
• Database schema and initialization
• Risk assessment algorithm
• Testing guide (87% coverage)
• Security features and best practices
• Troubleshooting common issues

Quick Links:

• API Endpoints
• Environment Setup
• Running Tests
• Security Features

---

🎨 Frontend Documentation

Location: frontend/README.md

Topics Covered:

• User interface walkthrough
• Component architecture
• CSV bulk upload guide
• Deployment instructions (Vercel, Netlify)
• Environment configuration
• Troubleshooting UI issues

Quick Links:

• User Guide
• Component Structure
• Deployment Guide
• API Integration

---

🔑 Key Features

Backend API

• ✅ JWT authentication with bcrypt password hashing
• ✅ Automated risk assessment (High/Medium/Low)
• ✅ Bulk report processing (up to 100 per request)
• ✅ Advanced filtering and pagination
• ✅ Comprehensive test coverage (110 tests)
• ✅ Winston-based structured logging
• ✅ SQL injection protection

Frontend Dashboard

• ✅ Real-time analytics with interactive charts
• ✅ CSV bulk upload with validation
• ✅ Domain-specific detailed views
• ✅ Status management workflow
• ✅ Responsive design (mobile-ready)
• ✅ Professional admin UI with shadcn/ui
• ✅ Toast notifications and error handling

---

🛠️ Technology Stack

Component	Technologies
Backend	Node.js, Express.js, SQLite, JWT, bcryptjs, Winston
Frontend	Next.js 15, React 19, TypeScript, Tailwind CSS v4, shadcn/ui
Testing	Jest, Supertest (87% coverage)
Data	Axios, React Hook Form, Zod, PapaParse, Recharts

---

🧪 Testing

# Run backend tests
cd backend
npm test

# Run tests with coverage
npm test -- --coverage

# Watch mode
npm run test:watch

Test Coverage: 87.54% (110 tests across 6 suites)

---

🚀 Deployment

Backend Deployment

The backend can be deployed to:

• Railway
• Render
• Heroku
• AWS EC2
• DigitalOcean

Environment Variables Required:

PORT=3000
JWT_SECRET=your_production_secret
ADMIN_USERNAME=admin
ADMIN_PASSWORD=secure_password
NODE_ENV=production

Frontend Deployment

Recommended: Vercel (one-click deploy)

Required Environment Variable:

NEXT_PUBLIC_API_URL=https://your-backend-api.com

For detailed deployment instructions, see frontend/README.md#deployment

---

🔒 Security Considerations

• 🔐 Change default admin credentials immediately
• 🔑 Use strong JWT secrets (minimum 32 characters)
• 🌐 Configure CORS for production origins
• 🛡️ Enable HTTPS in production
• 📊 Review security headers (Helmet.js configured)
• 🔄 Implement rate limiting for production
• 🔍 Regular security audits with npm audit

---

🐛 Common Issues

Backend Won't Start

# Check if port 3000 is in use
netstat -ano | findstr :3000

# Verify .env file exists
ls backend/.env

# Reinstall dependencies
cd backend && rm -rf node_modules && npm install

Frontend Can't Connect to Backend

• Verify backend is running at http://localhost:3000
• Check NEXT_PUBLIC_API_URL in .env.local
• Confirm no CORS errors in browser console
• Test API directly: curl http://localhost:3000/health

Authentication Issues

• Clear browser localStorage
• Generate new JWT token via /api/login
• Verify JWT_SECRET matches in backend .env

For comprehensive troubleshooting, see:

• Backend Troubleshooting
• Frontend Troubleshooting

---

📖 API Quick Reference

Authentication

POST /api/login
Body: { "username": "admin", "password": "admin123" }

Reports

GET    /api/reports                # List all reports
GET    /api/report/:domain         # Get domain-specific reports
POST   /api/report                 # Create single report
POST   /api/reports/bulk           # Bulk create (CSV upload)
POST   /api/report/:id/status      # Update case status

Full API documentation: backend/README.md#api-documentation

---

🤝 Contributing

This is an assignment project. For any questions or issues:

1. Check the detailed README files in backend/ and frontend/
2. Review the test files for usage examples
3. Consult the API documentation sections

📞 Support

For detailed information, refer to the component-specific README files:

• Backend: backend/README.md - API reference, testing, security
• Frontend: frontend/README.md - UI guide, deployment, troubleshooting

---

Built with ❤️ for Trust & Safety Teams

Backend Docs · Frontend Docs