K - Next Stack: Frontend migration from Django to Next.js/TypeScript on Cloudflare Pages

[DonnieBLT]

Core BLT frontend Migration to BLT Cloudflare from Django to Next.js/TypeScript

INTRODUCTION

The OWASP Bug Logging Tool (BLT) is a critical platform for security researchers to report, track, and manage vulnerability discoveries across organizations. This idea proposes a comprehensive migration of the BLT platform from its current Django-based monolithic architecture to a modern, edge-optimized Next.js/TypeScript stack deployed on Cloudflare Pages. The migration will transform Django template-based pages into React components while maintaining full feature parity with the existing Django REST API backend. With the exponential growth in edge computing and the need for zero-latency global access to security vulnerability data, this migration positions BLT to serve a worldwide community of security researchers with instant page loads, improved SEO, and enhanced developer experience through strict TypeScript type safety.

OBJECTIVE

Primary Goal

Migrate the complete OWASP BLT platform to Next.js 15/TypeScript/Cloudflare Pages while achieving 100% feature parity, zero data loss, sub-200ms global page load times, comprehensive test coverage, and production-grade error handling and accessibility compliance.

Specific Objectives

Architecture Migration:

• Migrate all 90+ Django template pages to Next.js App Router components with comprehensive implementation details
• Convert all Django views to Next.js API proxy routes with robust error handling, retry logic, and rate limiting
• Implement TanStack Query for client-side data fetching with optimistic updates, caching strategies, and stale-while-revalidate patterns
• Establish TypeScript interfaces mirroring all 25+ Django model schemas with extensive JSDoc documentation
• Create shared UI component library (50+ components) with Storybook documentation
• Implement comprehensive error boundaries at multiple levels (page, section, component)

Performance Optimization & Monitoring:

• Achieve Lighthouse performance score >95 on all key pages (Current Django: ~60)
• Reduce Time to First Byte (TTFB) to <50ms via Cloudflare edge caching with cache invalidation strategies
• Implement ISR (Incremental Static Regeneration) with fallback rendering for dynamic content
• Build custom performance monitoring dashboard with Core Web Vitals tracking
• Optimize bundle size with code-splitting, dynamic imports, and image optimization
• Implement service worker for offline functionality and advanced caching strategies

Developer Experience & Maintainability:

• Create comprehensive TypeScript type definitions with strict null checks and branded types
• Build 20+ reusable custom hooks with extensive unit tests and Storybook stories
• Establish ESLint/Prettier/TypeScript strict config with pre-commit validation
• Create comprehensive migration pattern documentation with real code examples

Feature Parity with Enhanced Functionality:

• Preserve all 40+ Django REST API endpoints with proxy routes including error handling
• Implement robust JWT token management with refresh rotation and automatic retry interceptors
• Replicate Django's 8+ permission system variants with role-based access control (RBAC)
• Add optimistic UI updates for all mutation operations

PROJECT TIMELINE(~350hrs)

PHASE 1: Architecture & Foundation (Weeks 1-3, ~40 hrs)

Week 1: Comprehensive Analysis & Setup (~10 hrs)

1. Codebase Analysis, Documentation & Setup

   • Deep dive into Django BLT repository structure
   • Map all 90+ pages with detailed feature requirements
   • Document API contract specifications from Django models
   • Identify edge cases and complex business logic
   • Create detailed architecture decision records (ADRs)
   • Configure CI/CD pipeline with GitHub Actions
   • Establish local development workflow with hot reloading
   • Create pre-commit hooks and linting rules

2. Documentation & Knowledge Transfer

   • Create detailed API reference documentation
   • Document Django model schemas and relationships
   • Write architecture decision records
   • Set up Storybook for component documentation
   • Create developer onboarding guide

Week 2: Type System & Core Infrastructure (~10 hrs)

1. Comprehensive TypeScript Type Definitions

   • Analyze all 25+ Django models
   • Create branded types to prevent common errors
   • Define union types for status/state fields
   • Write JSDoc comments with examples
   • Set up automated type generation from API responses
   • Build type utilities for common patterns

2. API Client & Interceptors

   • Create Axios client with auth interceptors
   • Implement JWT token refresh logic with race condition handling
   • Build retry logic with exponential backoff
   • Add request/response logging for debugging
   • Implement CORS error handling
   • Create network error recovery strategies

3. Authentication & Authorization Layer

   • Implement auth provider with context
   • Build JWT token persistence (cookie + localStorage hybrid)
   • Create permission checking utilities
   • Build role-based access control (RBAC) helpers
   • Implement auth redirects for protected routes
   • Set up logout and token expiration handlers

Week 3: Shared Components & Hooks Infrastructure (~20 hrs)

1. Base UI Component Library

   • Build 20-30 foundational components (Button, Card, Modal, Input, etc.)
   • Implement responsive design system
   • Create dark mode support
   • Add loading/skeleton states
   • Build error states and fallback UIs
   • Document all components in Storybook with examples

2. Custom Hooks Development

   • Implement useAuth hook with comprehensive testing
   • Build useApi hook for common fetch patterns
   • Create useDebounce, useLocalStorage, usePrevious utilities
   • Implement useInfiniteScroll for pagination
   • Build useForm hook for complex forms
   • Create useMediaQuery for responsive behavior
   • Write unit tests for all hooks

3. Error Handling & Logging

   • Create error boundary components
   • Implement error boundary with Sentry integration
   • Build error logging infrastructure
   • Create user-friendly error messages
   • Implement error recovery strategies
   • Add error tracking dashboard

---

PHASE 2: High-Priority Page Migration (Weeks 4-6, ~100 hrs)

Week 4: User & Authentication Pages (~36 hrs)

1. User Profile Pages

   • Migrate /profile/[username] with complex stat calculations
   • Handle missing user edge cases
   • Implement profile image optimization
   • Build social links display
   • Add achievements/badges section
   • Create follower/following systems
   • Write integration tests for profile variations
   • Implement performance optimization for badge rendering

2. Authentication Pages

   • Build comprehensive login form with validation
   • Implement sign-up flow with email verification
   • Create forgot password recovery flow
   • Build two-factor authentication UI
   • Add remember-me functionality
   • Implement social login integration UI
   • Write E2E tests for full auth flow

3. Account Settings Pages

   • Build profile edit form with image upload
   • Create password change form with validation
   • Implement email change with verification
   • Build notification preference panels
   • Create privacy settings UI
   • Add data export functionality
   • Implement account deletion with confirmation flow

Week 5: Issue Management & Reporting (~32 hrs)

1. Issue Listing & Filtering

   • Build issue list with server-side pagination
   • Implement 15+ filter combinations (severity, status, date range, domain)
   • Create advanced search with saved filters
   • Build sorting options (newest, most commented, most critical)
   • Implement infinite scroll with cache management
   • Add bulk actions (select, assign, tag)
   • Write tests for all filter combinations

2. Issue Detail & Interaction

   • Build comprehensive issue detail page
   • Implement comments/discussion thread system
   • Create nested reply functionality
   • Build comment editing and deletion
   • Implement up-vote/helpful system
   • Add attachment viewing and zooming
   • Create timeline view for status changes
   • Build activity audit log

3. Issue Creation & Editing

   • Build multi-step issue creation form
   • Implement file upload with validation
   • Create screenshot editor with annotations
   • Build issue template system
   • Implement auto-save drafts
   • Create duplicate detection
   • Add form validation with real-time feedback
   • Build submission confirmation and error recovery

Week 6: Organization & User Dashboard (~32 hrs)

1. Organization Pages

   • Build organization profile with team display
   • Create organization settings with admin controls
   • Build domain management interface
   • Implement hunt management dashboard
   • Create team member management UI
   • Build organization analytics
   • Implement role-based organization access
   • Write comprehensive tests for org workflows

2. User Dashboard & Profile

   • Build comprehensive user dashboard
   • Create personal statistics dashboard
   • Implement activity timeline
   • Build recommendation system for new issues
   • Create saved filters/bookmarks system
   • Build upcoming deadlines widget
   • Implement notification center
   • Create personal analytics page

---

PHASE 3: Medium-Priority Pages & Advanced Features (Weeks 7-9, ~70 hrs)

Week 7: Blog, Search & Discovery (~12 hrs)

1. Blog System

   • Build blog listing with pagination and search
   • Create blog post detail with markdown rendering
   • Implement comment system on posts
   • Build author profile integration
   • Create blog category/tag system
   • Implement related posts suggestions
   • Build social sharing functionality
   • Add blog search with highlighting
   • Create RSS feed generation

2. Global Search System

   • Build unified search across issues, users, domains, projects
   • Implement search debouncing and caching
   • Create search result ranking algorithm
   • Build search filters for each entity type
   • Implement saved searches
   • Create search history with clearing option
   • Build autocomplete suggestions
   • Write performance tests for large result sets

Week 8: Leaderboard & Gamification (~28 hrs)

1. Leaderboard System

   • Build global leaderboard with sorting options
   • Create monthly leaderboard with time-period selection
   • Build organizational leaderboards
   • Implement leaderboard filtering (bug hunters, reporters, etc.)
   • Create leaderboard analytics and trends
   • Build personal ranking display
   • Implement leaderboard historical data
   • Add leaderboard CSV export
   • Create leaderboard visualization charts

2. Badges & Achievement System

   • Build badges showcase page
   • Create badge detail with earning criteria
   • Implement badge notifications when earned
   • Build achievement unlock animations
   • Create badge filtering and sorting
   • Implement badge rarity system
   • Build profile badge display
   • Create badge earning progress tracking

3. Analytics & Reporting

   • Build user activity analytics dashboard
   • Create bug reporting trends visualization
   • Implement domain vulnerability analytics
   • Build leaderboard historical analysis
   • Create revenue/payout analytics
   • Implement custom report generation
   • Build data export functionality
   • Add analytics caching and optimization

Week 9: Advanced Features & Tools (~30 hrs)

1. Time Tracking System

   • Build time entry creation form
   • Implement time tracking calendar view
   • Create time entry editing/deletion
   • Build time tracking reports and exports
   • Implement project time allocation
   • Create time tracking analytics
   • Build hourly rate calculations
   • Add time approval workflow

2. Referral & Affiliate System

   • Build referral link generation
   • Create referral tracking dashboard
   • Implement referral reward display
   • Build referral sharing UI
   • Create referral history tracking
   • Implement commission calculations
   • Build referral analytics
   • Add referral code validation

3. User Profile Enhancements

   • Build user network (followers/following)
   • Implement user activity timeline
   • Create user comparison tool
   • Build user achievement badges
   • Implement user mentions and tagging
   • Create user messaging/notification system
   • Build user profile customization
   • Add user public/private profile toggle

4. Community & Forum

   • Build forum category system
   • Create forum thread listing with search
   • Implement forum thread detail with nested replies
   • Build forum moderation tools
   • Create forum pinned posts
   • Implement forum tags and categories
   • Build forum reputation system
   • Add forum thread archiving

5. Staking & Finance System

   • Build staking interface
   • Create stake pool selection
   • Implement staking rewards calculation
   • Build un-staking flow with lock periods
   • Create financial dashboard
   • Implement transaction history
   • Build reward tracking
   • Add financial reporting

---

PHASE 4: Low-Priority Pages & Refinement (Weeks 10, ~50 hrs)

Week 10: Admin Tools & Moderation (~25 hrs)

1. Admin Dashboard

   • Build admin user management interface
   • Create user role assignment
   • Implement user ban/suspend functionality
   • Build content moderation queue
   • Create reported content review system
   • Implement content takedown workflow
   • Build admin analytics dashboard
   • Create system health monitoring
   • Add audit log viewer

2. Moderation & Content Control

   • Build content flagging system
   • Implement inappropriate content blocking
   • Create comment moderation interface
   • Build spam detection UI
   • Implement content appeals workflow
   • Create moderation rules editor
   • Build automated flagging rules
   • Add moderation metrics

Week 10: Static Pages, SEO & Legal (~25 hrs)

1. Static & Legal Pages

   • Build about page with team/history
   • Create contact form with backend integration
   • Build FAQ with search and categories
   • Implement privacy policy page
   • Create terms of service page
   • Build security policy page
   • Implement cookie consent banner
   • Add legal page versioning

2. SEO & Social Integration

   • Implement dynamic sitemap generation
   • Create robots.txt with proper rules
   • Build structured data (JSON-LD) for all pages
   • Implement Open Graph meta tags with image generation
   • Create Twitter Card implementation
   • Build breadcrumb schema markup
   • Implement canonical tags
   • Add schema markup testing

---

PHASE 5: Comprehensive Testing (Weeks 11 ~80 hrs)

Week 11: Unit & Integration Testing (~80 hours)

1. Unit Test Coverage

   • Write tests for all custom hooks
   • Create tests for utility functions
   • Build tests for TypeScript types and guards
   • Implement tests for form validation
   • Create tests for error handling
   • Build tests for authentication logic
   • Implement permission checking tests
   • Create tests for data transformation functions

2. Integration Testing

   • Test API proxy routes with mocked Django backend
   • Create integration tests for complex user flows
   • Build tests for state management
   • Test error recovery mechanisms
   • Create tests for cache invalidation
   • Build tests for optimistic updates
   • Test authentication refresh flows
   • Create tests for multi-step forms

PHASE 6: Performance Optimization (Weeks 12 ~40 hrs)

Week 12: Performance Optimization (~40 hrs)

1. Bundle & Code Analysis

   • Analyze bundle size with webpack-bundle-analyzer
   • Identify and remove unused dependencies
   • Implement code splitting for route-based chunks
   • Create dynamic imports for heavy components
   • Optimize image delivery (WebP, AVIF)
   • Implement image lazy loading
   • Create font optimization strategy
   • Build tree-shaking verification

2. Rendering & Runtime Performance

   • Profile React rendering with DevTools
   • Implement memo and useMemo where beneficial
   • Optimize component re-renders
   • Implement virtualization for long lists
   • Create performance monitoring
   • Build performance budgets
   • Implement cache strategies
   • Optimize database queries on backend

3. Network & Caching Optimization

   • Configure Cloudflare caching rules
   • Implement edge function optimization
   • Build service worker with offline support
   • Create stale-while-revalidate strategies
   • Implement request deduplication
   • Build prefetching strategies
   • Create cache invalidation logic
   • Implement CDN optimization

---

TIMELINE OVERVIEW BY CATEGORY

• Architecture & Infrastructure: ~60 hrs
• Page Development & UI: ~220 hrs
• Testing & QA: ~60 hrs
• Performance & Optimization: ~40 hrs

---

ARCHITECTURE MIGRATION

Module	Core BLT	BLT-on-Cloudflare	Why this change?
Language	Python	TypeScript (TSX)	Ensures strict "data contracts" between the API and the UI, reducing runtime crashes.
Framework	Django (Monolithic)	Next.js (App Router)	Provides SEO-friendly Static Generation (SSG) and instant page transitions.
Hosting	VPS / Docker	Cloudflare Pages	Zero-latency global delivery via Cloudflare’s Edge network; infinite scalability.
UI/Styling	CSS	Tailwind CSS	Drastically reduces CSS bundle size by stripping unused styles at build time.
API Layer	Django Templates	Django REST Framework (DRF)	Converts Python logic into JSON, making the data accessible to any frontend.
Data Fetching	Server-Side Querying	TanStack Query (React Query)	Handles caching, loading states, and "optimistic updates" for a seamless UI.
Authentication	Session Cookies	JWT (JSON Web Tokens)	Allows secure authentication across different domains (.org to .dev).
Icons/Assets	FontAwesome / PNG	FontAwesome for now (can be used Lucide React)	Lightweight, tree-shakeable SVG icons optimized for React.

CONCLUSION

This migration strategically positions OWASP BLT as a modern, high-performance platform for global security research. By combining Next.js, TypeScript, and Cloudflare's edge network with the existing Django backend, we'll deliver superior user experience and performance. The phased approach with live initial pages validates the architecture, establishing BLT as a reference implementation that will attract a new generation of contributors.

---

[DonnieBLT]

We decided to go as much vanilla / html / htmx as possible and avoid the npm ecosystem so closing this

[nishantxraghav]

fetch only rejects on network failure.

A 404/500 is still a successful HTTP request, so you must
check response.ok manually:

const res = await fetch(url)

if (!res.ok) {
throw new Error(HTTP error! status: ${res.status})
}

const data = await res.json()