⚠️Agentic AI disclaimer

Text in this section was added by a human as a project post-script.

This project was created as a hackathon exploration of Agentic AI's usability and limitations. The special restriction in place for this repository's development was that all changes must be made through an agentic AI development tool, in order to highlight the limitations of AI tool use in code development.

Documentation of the iterative development process, including takeaways and strategic examples of patterns and guidance for effective human-centric AI use, can be found in process.md.

The tool used for this project's development was Anthropic's Claude Code, primarily using the 3.7 Sonnet model.

---

Discord Analytics Dashboard

A full-stack application for processing and visualizing Discord user prediction data, consisting of a Java Spring Boot backend and React TypeScript frontend.

Overview

This application processes JSON files containing user predictions (gender, age, etc.) and provides:

• Web Interface: React-based dashboard for file upload and data visualization
• REST APIs: Backend services for data processing and analytics
• Data Visualization: Interactive charts and tables for prediction analysis
• CSV Export: Download processed data for further analysis

Quick Start

Prerequisites

• Java 21
• Maven 3.6+
• Node.js 18+
• npm 9+

Running the Application

# Start full development environment (recommended)
make up

# Or run services individually:
# Backend: mvn spring-boot:run (port 8080)
# Frontend: cd frontend && npm run dev (port 5173)

Access the application: http://localhost:5173

Other Commands

make down    # Stop all services
make build   # Build production artifacts
make status  # Check service status
make help    # Show all commands

Architecture

Frontend (React + TypeScript)

• Framework: React 19 with TypeScript and Vite
• Components: Modular design with reusable UI components
• Data Visualization: Recharts library for interactive charts
• Accessibility: ARIA labels and keyboard navigation support
• Testing: Vitest with React Testing Library (112 tests)

Backend (Java Spring Boot)

• Framework: Spring Boot 3.2 with Java 21
• Data Processing: JSON line-by-line parsing for memory efficiency
• API Design: RESTful endpoints with CSV and JSON responses
• Architecture: Service layer pattern with unified data pipeline

API Response Format

All API endpoints return responses wrapped in a consistent ApiResponseWrapper format:

{
  "success": true,
  "body": { /* endpoint-specific data */ },
  "code": 200,
  "messages": null
}

Exception: The CSV download endpoint (/api/analyze/{group}) returns raw CSV content for file download.

API Endpoints

POST /api/groups - Detect Available Groups

Analyzes uploaded file to detect available prediction groups.

• Request: Multipart file upload (file parameter)
• Body Format:

{
  "availableGroups": ["gender", "age"],
  "totalRecords": 1000
}

POST /api/analyze-json/{group} - Generate Structured Data

Returns structured data for specific prediction group (network-friendly).

• Request: Multipart file upload + group path parameter
• Body Format (CsvData):

{
  "headers": ["day_pt", "prediction", "prediction_confidence", "male", "female", "model_version", "user_id"],
  "rows": [["2023-01-01", "male", "0.75", "0.75", "0.25", "2023-01-01", "123"]],
  "filename": "gender.csv",
  "totalRecords": 1
}

POST /api/analyze/{group} - Download CSV (No Wrapper)

Generates CSV file for download as raw content.

• Request: Multipart file upload + group path parameter
• Response: Raw CSV file with download headers
• Content-Type: text/plain
• Content-Disposition: attachment; filename="gender.csv"

GET /api/health - Health Check

Simple health check endpoint.

• Body Format: "Service is healthy"

Example API Usage

1. Web Interface: Use the dashboard at http://localhost:5173 (recommended)

2. Direct API Access:

   # Detect available groups
   curl -X POST -F "file=@predictions.json" http://localhost:8080/api/groups
   
   # Generate analytics (JSON format)
   curl -X POST -F "file=@predictions.json" http://localhost:8080/api/analyze-json/gender
   
   # Download CSV file
   curl -X POST -F "file=@predictions.json" http://localhost:8080/api/analyze/gender -o gender.csv

Input Data Format

The service expects JSON files with one prediction record per line:

{"user_id":"123","predicted_gender":"male","probability":0.75,"prob_male":0.75,"prob_female":0.25,"model_version":"2023-01-01T00:00:00.000000Z","day_pt":"2023-01-01 00:00:00 UTC"}

Data Output Formats

CSV Export

Generated CSV files include columns in this order: day_pt, prediction, prediction_confidence, [sorted prob_ columns], model_version, user_id

CsvData Structure (Unified Pipeline)

The application uses a unified data pipeline with CsvData as the primary format:

Pipeline: PredictionRecord → CsvData → (CSV string | JSON response)

The CsvData wrapper provides:

• Network-friendly: Structured JSON eliminates large HTTP response issues
• Consistent format: Same data structure for both API and CSV generation
• Metadata included: Headers, row count, and filename information

Features

Data Processing

• Memory Efficient: Line-by-line JSON processing for large files
• Client-Side Filtering: Automatically processes large raw Discord files (up to 1GB) by filtering only lines containing "predicted_" before upload
• Smart File Handling: Files >1% of upload limit are automatically filtered using browser streaming API
• Early Exit Protection: Stops processing if filtered output would exceed upload limits
• Flexible Input: Handles variable prediction fields dynamically
• Data Validation: Robust error handling and validation
• Multiple Formats: Both CSV download and JSON API responses

User Interface

• Intelligent File Upload:
  • Drag & drop with visual feedback
  • Automatic filtering of large raw Discord files (handles files up to 1GB)
  • Processing indicators for large file operations
  • Helpful error messages with command-line alternatives
• Interactive Charts: Stacked bar charts and advanced visualizations
• Data Tables: Sortable, filterable table views
• Export Options: CSV download and chart image export
• Responsive Design: Works on desktop and mobile devices
• Backend Status Monitoring: Real-time Java backend health indicator (add ?status to URL for continuous monitoring; DOWN status always visible)

Network Resilience

• WAN Support: Python proxy for external access
• Retry Logic: Automatic retry with exponential backoff
• Connection Handling: Robust error handling and recovery
• Caching: Client-side caching for improved performance

Development

Detailed Documentation

• CLAUDE.md - Development commands and architecture details
• DEVELOPMENT.md - Comprehensive development guide
• process.md - Development process insights and lessons learned

Testing

• Backend: Maven Surefire with unit and integration tests
• Frontend: 112 tests with Vitest and React Testing Library
• Coverage: Comprehensive test coverage for all major features