How to Build a Social Graph Service (Follow/Unfollow, Newsfeed) via Harper's HTTP API

Building social features with traditional stacks means dealing with complexity that scales exponentially. You start with a simple database and API server. Then you need caching for performance, so you add Redis. Real-time notifications require a message broker like Kafka. Load balancing needs session stores. Each component solves a specific problem, but now you're managing data consistency across multiple systems, debugging network timeouts between services, and writing integration code that's often more complex than your actual business logic.

‍

The architecture works, obviously. Twitter and Facebook built massive platforms this way. But the operational overhead is enormous. Every new feature requires coordinating updates across multiple services. A simple follow action might update three databases, invalidate four cache keys, and publish two events. When something breaks at 3 AM, you're troubleshooting whether it's a database lock, a cache miss, or a message queue backup.

‍

Harper changes the game completely. Instead of orchestrating a symphony of separate services, everything runs in one process. Database, cache, messaging, application logic, all fused together. This approach eliminates the network overhead and coordination complexity that makes traditional social architectures so brittle.

‍

The Real Cost of Distributed Social Architecture

The hidden expense isn't just in infrastructure costs or development time. It's in the cognitive load of maintaining consistency across systems that were never designed to work together. Your follow service needs to know about your notification service. Your feed generator needs to coordinate with your cache invalidation logic. Your real-time updates need to stay synchronized with your database writes.

‍

Engineers spend more time writing glue code between services than building actual features. A notification that someone liked your post involves updating counters in the database, clearing cached feed data, publishing events to subscribers, and hoping all these operations complete successfully. When they don't, debugging becomes an exercise in distributed systems archaeology.

‍

Setting Up Your Social Graph Schema

Harper uses GraphQL syntax to define your data model, but here's the cool part, it automatically generates REST endpoints from your schema. No more writing boilerplate API routes.

type User @table @export {
  id: ID @primaryKey
  username: String @indexed
  email: String @indexed
  displayName: String
  bio: String
  avatar: String
  createdAt: String
  followingIds: [ID] @indexed
  followerIds: [ID] @indexed
  followers: [User] @relationship(from: followerIds)
  following: [User] @relationship(from: followingIds)
}

type Post @table @export {
  id: ID @primaryKey
  authorId: ID @indexed
  content: String
  imageUrl: String
  createdAt: String
  likesCount: Int
  commentsCount: Int
  author: User @relationship(from: authorId)
}

type Follow @table @export {
  id: ID @primaryKey
  followerId: ID @indexed
  followeeId: ID @indexed
  createdAt: String
  follower: User @relationship(from: followerId)
  followee: User @relationship(from: followeeId)
}

‍

The @export directive is doing the heavy lifting here. As soon as you define this schema, Harper creates REST endpoints at /User/, /Post/, and /Follow/. The @relationship directive sets up joins that actually work fast because everything is in the same process.

Writing API controllers for basic CRUD operations becomes unnecessary. The schema definition handles all the boilerplate.

Building Follow/Unfollow That Actually Works

Here's how clean the follow functionality becomes:

POST /Follow/
Content-Type: application/json

{
  "followerId": "user123",
  "followeeId": "user456",
  "createdAt": "2024-08-05T10:30:00Z"
}

DELETE /Follow/follow_id_here

‍

What's happening under the hood is beautiful. That POST request doesn't just insert a record. Harper is simultaneously updating any relevant caches, notifying real-time subscribers, and keeping everything consistent. In a traditional setup, you'd need custom code to coordinate all this. Harper handles it automatically.

Building Efficient Newsfeeds

Building newsfeeds used to mean complex caching strategies, background jobs, and crossing your fingers that everything stayed in sync. Harper makes it straightforward with its query parameters:

GET /Follow/?followerId=user123&limit=1000
GET /Post/?authorId=user456&authorId=user789&sort=createdAt&order=desc&limit=20
GET /Post/?authorId=user456&likesCount=gt=10&createdAt=ge=2024-08-01T00:00:00Z

‍

These might look like multiple database calls, but remember - everything is happening in the same process. No network latency between these operations. Harper's query engine can optimize these requests in ways that separate services never could.

The syntax Harper uses for querying is actually pretty powerful. You can build complex filters for engagement-based feeds, content type preferences, whatever your algorithm needs.

Real-Time Features

Harper has WebSockets, MQTT, and Server-Sent Events built right into the database. The MQTT topics map directly to your database resources:

SUBSCRIBE Follow/user123
ws://localhost:9926/User/user123

‍

Subscribe to Follow/${userId} and you get notified whenever someone follows or unfollows that user. No separate message broker to maintain, no complex routing logic.

Why This Architecture Matters

Harper's single-process architecture addresses the core challenges of social platform development: performance, complexity, and operational overhead. Instead of managing multiple services that need to stay synchronized, you get sub-millisecond response times from a single system that handles data, caching, and real-time updates together.

‍

The development experience reflects this simplicity. Schema definitions automatically generate REST endpoints. Real-time features work without separate message brokers. Caching happens transparently at the storage level. You spend time building social features instead of debugging distributed system edge cases.

‍

For social applications where user engagement depends on instant feedback and real-time interactions, Harper's performance characteristics translate directly into better user experiences. Follow buttons feel responsive. Notifications arrive immediately. Feeds load without delays that cause users to abandon interactions.

‍

The architecture scales naturally through Harper's mesh networking, allowing global distribution while maintaining the performance benefits of the unified system. Social platforms can serve users worldwide without the complexity typically associated with distributed architectures.

‍

Our Story