Skip to content

README.md

Latest commit

 

History

History
261 lines (184 loc) · 7.58 KB

README.md

File metadata and controls

261 lines (184 loc) · 7.58 KB

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

🔧 Technical Fixes & Solutions

📊 Architecture & Analysis

🧪 Testing & Validation

🚢 Deployment & Integration

📖 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

  1. Prerequisites

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

  2. Quick Start

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

# Start services
./start-hexfeed.sh

  3. 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:

  1. Place in appropriate category
  2. Update this README index
  3. Follow markdown formatting standards
  4. Include code examples where relevant
  5. 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