explain

[0xthrpw]

@efp-dev-ops can you please explain what this repo does

[efp-dev-ops]

Claude finished @0xthrpw's task —— View job

---

Understanding the EFP Services Repository

Todo List:

• Analyze repository structure and key files
• Review service architecture and core functionality
• Provide comprehensive explanation of the repository's purpose

---

What This Repository Does

This is the Ethereum Follow Protocol (EFP) Services repository - a backend service application that processes and caches data for the EFP ecosystem. EFP is "a native Ethereum protocol for following and tagging Ethereum accounts."

Core Purpose

The repository implements a service-based data processing system that:

• Continuously monitors and processes on-chain follow/unfollow activity
• Generates leaderboards and rankings for users
• Manages recommendation algorithms
• Caches data for performance optimization
• Fetches and stores ENS metadata

Architecture Overview

The application uses a Service Manager pattern (src/index.ts:15-44) that orchestrates multiple background services running at configurable intervals:

1. recentFollows (2850s interval) - Tracks recent follow activity from on-chain data
2. leaderboard (960s interval) - Generates user ranking data based on followers, following, mutuals
3. recommended (4260s interval) - Manages recommendation algorithms
4. ensMetadata (21600s interval) - Fetches ENS names, avatars, and metadata
5. heartbeat (290s interval) - Health monitoring service
6. efpCache (3600s interval) - Builds and maintains address cache for performance
7. mutuals (973s interval) - Processes mutual connection data

Technology Stack

• Runtime: Bun (JavaScript/TypeScript runtime)
• Database: PostgreSQL with Kysely query builder
• Blockchain: Ethereum integration via Viem library
• Logging: Consola structured logging
• Environment: TypeScript with strict mode

Key Functionality

Data Processing: The services query on-chain EFP data to:

• Track who follows whom (src/services/recentFollows/index.ts:12-26)
• Calculate leaderboard rankings (src/services/leaderboard/index.ts:14)
• Build address caches for performance (src/services/efpCache/index.ts:9-48)

Performance Optimization: Uses chunked batch processing (arrayToChunks utility) for handling large datasets efficiently.

Database Integration: Robust PostgreSQL connection with automatic reconnection handling and SQL template functions for complex queries.

This repository essentially serves as the data infrastructure backbone for the Ethereum Follow Protocol, continuously processing on-chain social graph data to power applications that display follower relationships, recommendations, and social metrics in the Ethereum ecosystem.

---