Humane Backend powers the server-side infrastructure of Humane, a human-first social platform focused on meaningful interactions, positive behavior, and real-world connection rather than attention-driven engagement. It is built as a scalable, event-driven microservices system. The platform uses Apache Kafka for asynchronous service communication, Kubernetes for orchestration, and a polyglot persistence strategy to balance consistency, performance, and scalability, while following Clean / Hexagonal Architecture principles for long-term maintainability.

Open in interactive mode

• Authentication & Authorization: JWT-based auth with Google OAuth integration
• User Profiles: Customizable profiles with avatar and cover photos
• Friend System: Send/accept friend requests, manage relationships
• Password Management: Secure password hashing, reset, and change functionality
• Email Verification: Verification emails via nodemailer

• Posts: Create, update, delete posts with text and media attachments
• Comments: Commenting system with like/unlike functionality
• Likes: Like/unlike comments with real-time updates
• Hashtags: Automatic hashtag extraction and indexing
• Visibility Controls: Public and friends-only post visibility
• Media Upload: Pre-signed URL generation for secure client-side uploads

• AI-Powered Moderation: Automated NSFW detection using pre-build CNN model
• Video Processing: Frame extraction and analysis using FFmpeg
• Multi-frame Analysis: Identifies "hottest" frames in video content
• Configurable Thresholds: Admin-adjustable sensitivity for content flagging
• User Notifications: Alerts for flagged or failed moderation

• 1-1 Messaging: WebSocket-based instant messaging via Socket.IO
• Online Status: Real-time user presence tracking
• Read Receipts: Conversation-level read tracking (timestamp-based)
• Message Persistence: Reliable message delivery with acknowledgments
• Reward Integration: Gamified engagement for active conversations

• Real-time Delivery: WebSocket-based instant notifications
• Event-driven: Kafka consumers trigger notifications for various events
• Types Supported: Friend requests, comments, likes, moderation alerts
• Pagination: Efficient infinite scroll for notification history

• Full-text Search: Elasticsearch-powered search for posts, comments, users
• User Timeline: Paginated user post history
• Feed Optimization: Redis-cached personalized feeds

• Humane Score: Point system for user engagement
• Configurable Rewards: Admin-configurable point values for actions
• Activity Tracking: Automated reward distribution via Kafka events
• Leaderboards: Platform-wide reward statistics

• Prometheus Metrics: Custom metrics for all services
• Grafana Dashboards: Visualization and monitoring
• Distributed Logging: Centralized logging with Grafana Alloy and Loki
• Service Health: Readiness and liveness probes

• Batch Processing: Batching likes, comments, and reward count updates for efficiency
• Kubernetes Orchestration: Automated deployment, scaling, and management
• Event-driven Architecture: Loose coupling via Kafka for scalability
• Polyglot Persistence: Optimized data storage strategies per service

• Node.js 22+
• Docker & Docker Compose
• Kubernetes (Docker Desktop, k3s or Minikube)
• Skaffold CLI
• kubectl

git clone https://github.com/abhiram-ar/humane-backend.git
cd humane-backend

git submodule update --init --recursive

Manually start the infrastructure comonents like kafka, elasticsearch, databases, Api gateway etc. using the manifests or helper scripts in infra/k8s-dev-manual/.

skaffold dev

This command will:

• Build all microservices
• Deploy to local Kubernetes cluster
• Enable hot-reloading for development when code changes are detected

skaffold run --config skaffold.prod.yaml

This command will:

• Pull pre-built Docker images from Docker Hub
• Deploy to local Kubernetes cluster

• Frontend: http://localhost:5173 (via humane-frontend submodule)
• API Gateway: Available via Kubernetes ingress
• Grafana: Port-forward to access dashboards

Each service requires specific environment variables. Refer to individual service README files for details:

• Writer Service
• Chat Service
• Moderation Service
• And more...

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow code style and linting rules (Prettier config included)
4. Write unit and integration tests
5. Document API changes and data schema modifications
6. Submit a pull request

• Use TypeScript strict mode
• Follow existing architectural patterns (Clean Architecture/Hexagonal)
• Write meaningful commit messages
• Keep services decoupled and event-driven

• Architecture Diagrams
• Observability Setup

• NSFWJS for NSFW image classification model
• The open-source community for amazing tools and libraries
• Inspired by modern social that drifed from what social media should be.