HexFeed Documentation Hub

Welcome to the comprehensive documentation for the HexFeed Java Feed System Service. This directory contains all technical documentation, guides, and reference materials.

📚 Documentation Index

🚀 Quick Start & Setup

Project_Startup_Instructions.md - Complete guide to setting up and running the project
STARTUP_SUCCESS_SUMMARY.md - Current system status and operational validation

🔧 Technical Fixes & Solutions

KAFKA_DESERIALIZATION_FIX.md - v1.7.8: Comprehensive Kafka consumer deserialization fix
KAFKA_FIX_QUICK_REFERENCE.md - Quick reference for Kafka troubleshooting

📊 Architecture & Analysis

ClassArchitectureDiagram.md - System architecture and class relationships
Codebase_Analysis_Report.md - Detailed codebase analysis and structure
ANALYSIS_SUMMARY.md - Summary of system analysis

🧪 Testing & Validation

API_Testing_Status.md - Current status of API endpoint testing
../hexfeed-backend/WEBSOCKET_TESTING_GUIDE.md - WebSocket testing procedures
../hexfeed-backend/WEBSOCKET_QUICKSTART.md - Quick WebSocket testing guide

🚢 Deployment & Integration

DeploymentGuide.md - Production deployment instructions
Publishing_and_Frontend_Integration_Guide.md - Frontend integration guide

📖 Documentation by Category

🔴 Critical Issues & Fixes

v1.7.8 - Kafka Deserialization Fix (Oct 21, 2025)

Issue: Kafka consumer crashing with IllegalStateException: No type information in headers

Solution: Added comprehensive consumer configuration with ErrorHandlingDeserializer

📄 Read: KAFKA_DESERIALIZATION_FIX.md

🔧 Quick Fix: KAFKA_FIX_QUICK_REFERENCE.md

✅ Status: STARTUP_SUCCESS_SUMMARY.md

🏗️ System Architecture

The HexFeed system follows a microservices architecture with:

Spring Boot 3.2.x backend
PostgreSQL 15 for relational data
Redis 7.x for caching
Apache Kafka for event streaming
H3 Spatial Indexing for location-based features
WebSocket for real-time updates

📄 Read: ClassArchitectureDiagram.md

🧪 Testing Documentation

API Testing

REST endpoint testing with Postman
Authentication flow validation
Feed aggregation testing
Rate limiting verification

📄 Read: API_Testing_Status.md

WebSocket Testing

Real-time message broadcasting
Connection management
Subscription handling
Heartbeat mechanisms

📄 Read: ../hexfeed-backend/WEBSOCKET_TESTING_GUIDE.md

🚀 Getting Started

First Time Setup

Prerequisites

- Java 17+
- Maven 3.8+
- Docker & Docker Compose
- PostgreSQL 15
- Redis 7.x
- Apache Kafka

Quick Start

# Clone the repository
git clone <repository-url>
cd Java-Feed-System-Service

# Start services
./start-hexfeed.sh

Verify Setup

# Health check
curl http://localhost:8080/actuator/health

📄 Full Guide: Project_Startup_Instructions.md

📊 Key Features

Location-Based Feed System

H3 Hexagonal Spatial Indexing - Resolution 7 (~2.5km edge length)
K-Way Merge Algorithm - Efficient merging of 7 hexagon feeds
Real-time Updates - WebSocket broadcasting for instant notifications
Cursor-Based Pagination - Efficient feed scrolling

Performance Optimizations

Multi-layer Caching - Redis caching with configurable TTL
Parallel Queries - CompletableFuture for concurrent database access
Rate Limiting - Token bucket algorithm with Redis
Connection Pooling - HikariCP for optimal database performance

Security & Reliability

JWT Authentication - Stateless token-based auth
Rate Limiting - Prevents abuse and ensures fair usage
Error Handling - Comprehensive exception handling with ErrorHandlingDeserializer
Manual Acknowledgment - Kafka consumer reliability

🔧 Troubleshooting Guides

Common Issues

Issue: Kafka Consumer Errors

Solution: See KAFKA_DESERIALIZATION_FIX.md

Issue: Database Connection Failures

Solution: Ensure Docker services are running

docker-compose up -d postgres redis kafka

Issue: WebSocket Connection Drops

Solution: See ../hexfeed-backend/WEBSOCKET_TESTING_GUIDE.md

📈 Version History

Current Release: v1.7.8 (Oct 21, 2025)

✅ Fixed Kafka consumer deserialization errors
✅ Added ErrorHandlingDeserializer configuration
✅ Enhanced consumer factory with proper settings
✅ Created comprehensive documentation

Previous Release: v1.7.7 (Oct 11, 2025)

✅ Fixed null user data in feed responses
✅ Enhanced feed aggregation with @EntityGraph
✅ Improved JPQL queries for PostgreSQL JSONB

See ../CHANGELOG.md for complete version history.

🛠️ Utility Scripts

Located in project root and hexfeed-backend/:

start-hexfeed.sh - Automated startup with dependency checking
hexfeed-backend/reset-kafka-consumer.sh - Kafka consumer group management
hexfeed-backend/test-api.sh - API testing automation
hexfeed-backend/test-websocket.sh - WebSocket testing

📝 Development Guidelines

Code Standards

Follow SOLID principles
Maintain high cohesion and low coupling
Use Lombok for boilerplate reduction
Constructor injection for dependencies
Comprehensive error handling
JavaDoc for public methods

Testing Requirements

Unit tests for service layer
Integration tests for repositories
API endpoint testing with Postman
80%+ code coverage target

Git Workflow

Feature branches from develop
Descriptive commit messages
Pull requests for review
No direct commits to main

🤝 Contributing

When adding new documentation:

Place in appropriate category
Update this README index
Follow markdown formatting standards
Include code examples where relevant
Add to CHANGELOG.md

📞 Support

For issues, questions, or contributions:

Create an issue in the GitHub repository
Tag with appropriate labels
Provide detailed context and logs

📚 External Resources

Spring Boot

Technologies

📊 Quick Stats

Total Lines of Code: 10,000+
Number of Tests: 100+
API Endpoints: 15+
Code Coverage: 80%+
Documentation Files: 15+

Last Updated: October 21, 2025
Version: 1.7.8
Status: ✅ Production Ready

For the most up-to-date system status, see STARTUP_SUCCESS_SUMMARY.md

FilesExpand file tree

README.md

Latest commit

History