Claprec: Product Overview (1/6)

This post begins a six-part series on Claprec, a review platform engineered to demonstrate scalable system design, complex data modeling, and machine learning integration.

While the surface-level product is a discovery tool for local businesses, the engineering goal was to build a resilient, distributed system capable of handling high-velocity user interactions, recursive data structures, and real-time event propagation.

Series Roadmap

• Product Overview (1/6)
• Architecture: N-Tier Design, Decoupling, and Microservices (2/6)
• Frontend: Angular SSR, NgRx, and OpenAPI Integration (3/6)
• Machine Learning in Practice (4/6)
• Database Design and Data Modeling (5/6)
• Engineering Tradeoffs: Limited Time vs. Ideal Architecture (6/6)

The Core System: Intelligence and Feedback Loops

Claprec is built around a feedback loop pattern. Unlike static directories, this system treats user interactions as first-class citizens that directly influence visibility and ranking.

Visibility is driven by a Machine Learning ranking model. Instead of relying only on simple chronological sorting or basic popularity metrics, the system analyzes engagement signals and behavioral patterns to surface content. This moves the platform toward adaptive, context-aware discovery - a significant architectural challenge compared to standard CRUD apps.

User Capabilities: Modeling Complex Interactions

The platform is user-driven, so I prioritized features that encourage interaction. The focus was on scalable engagement patterns - specifically, how to handle infinite nesting for discussions while keeping queries efficient.

Discovery & Search

• Business & Product Discovery: Users can browse robust entities with detailed attributes (hours, contact info, location links, exception dates, etc.). I implemented a filtering engine allowing users to sort by country, city, category, price range, and availability.
• Geolocation: The app integrates the Geolocation API to prioritize nearby reviews, with graceful fallbacks for permission denials.

Content Generation & Graph Structures

• Recursive Threading: The discussion system supports infinite nesting (Reddit-style). Users can drop comments on reviews, replies to comments, subreplies to replies, ad infinitum. This required implementing recursive structures in the database to handle depth without exploding latency.
• Rich Media Reviews: Users can submit reviews with 1-5 star ratings, descriptions, and multiple images.
• Reactions Layer: A lightweight engagement system allowing reactions on every node - reviews, comments, replies, and subreplies.

Media & Safety Pipeline

• Asset Management: Support for multiple images per entity (reviews, comments, businesses) with view-count tracking for viral detection.
• Proactive Moderation: I integrated an automated NSFW filter at the upload layer. It blocks high-risk content before it hits the storage bucket, preventing legal/PR liabilities before they start.

Real-Time Communication

• WebSockets: Both the notification system and private chat run over WebSockets. This ensures instant feedback for user actions and real-time messaging without the overhead of polling.
• User Controls: Users can manage their profiles (including avatar generation logic for those without photos) and block other users in private chat, balancing safety with open public discourse.

Trust & Verification Flow

To ensure accountability within the ecosystem, I implemented a verification layer. Users can upload identity documents (PDF/Images) to request verified status. Once verified, they unlock the ability to request elevated system roles - a necessary step to prevent bad actors from gaining high-level privileges.

Business Owners: Verification and Entity Management

Business owners get a permissioned slice of the system, centered on a verification workflow to lock down edits. It is a classic Role-Based Access Control (RBAC) pattern designed to prevent the chaos of unchecked distributed edits.

Entity Creation

Owners can model their real-world presence by creating Businesses, Addresses, and Products.

• Hierarchical Products: Products can be linked to multiple addresses and have parent-child relationships (e.g., "Lunch Menu" -> "Burgers").
• Rich Metadata: Owners manage granular details like working hours, exception dates (for holidays), and feature tags (e.g., "Offers Delivery", "Good for Groups").

Ownership Verification

To claim a business, owners must upload verification documents (PDF/Images) proving their authority. This creates a pending state that requires administrative review before full edit permissions are granted. The system supports multi-owner setups, handling concurrent permissions for a single verified entity.

Specialized Roles: RBAC and Operational Scaling

Claprec leans on a granular Role-Based Access Control (RBAC) system to delegate tasks without bottlenecks. This prevents "privilege creep" and ensures the platform scales operationally.

Bot & Human Scrapers

These roles mirror business owners but are restricted to unclaimed entities.

• Note: Bots are granted looser rate limits at the API layer to allow for automated data ingestion, while humans operate under standard throttling constraints.

Moderators

The first line of defense. Their scope includes:

• Reviewing reports on user-generated content (reviews, comments, replies).
• Deleting content that violates policy.
• Managing the moderation queue.

Elevated Moderators

A tier up, handling higher-stakes operations and trust verification:

• Reviewing reports on Businesses and Products (deleting content that violates policy).
• Approving Business Ownership Claims: Reviewing uploaded documents to verify a user's right to claim a business entity.
• User Identity Verification: Validating user-submitted documents to grant "Verified" status.
• Deleting users and broadcasting custom notifications (app-wide or email).

Admins

The top-level authority. While Elevated Moderators handle verification, only Admins can authorize role changes.

• Role Assignment: Approving or rejecting requests for roles (Scraper, Moderator, Elevated Moderator, Admin) once a user has been verified.
• Full spectrum access - the "break glass in case of emergency" role with override capabilities across the entire system.

What's Next

This overview covers the functional scope of Claprec, but the real engineering challenges lie under the hood. In the next post, "Inside the Architecture", we'll look at how I structured the backend to handle these complex relationships and decoupled services.

I'd love to hear your thoughts or questions about the project, so feel free to leave a comment below.