Neura Market
Back to .md Directory
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

ahzan-dev
May 2, 2026
0 downloads
1 views
ai agent llm rag claude
View source

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a Review Analyzer API built with Jaclang (JAC) - a graph-based programming language with native AI integration. The system analyzes Google Maps reviews using a multi-agent pipeline and provides detailed business intelligence reports.

Production API: https://review-analysis-server.trynewways.com/

Core Architecture

Graph-Based Data Model

The application uses JAC's graph database paradigm:

  • Nodes = Data entities (Business, Review, Theme, Analysis, Report, UserProfile)
  • Edges = Relationships between nodes
  • Walkers = Agents that traverse the graph and perform operations
  • Automatic Persistence = Nodes connected to root are auto-saved

Multi-Agent Analysis Pipeline

DataFetcherAgent → SentimentAnalyzerAgent → PatternAnalyzerAgent → ReportGeneratorAgent → RecommendationAgent
       │                    │                        │                      │                     │
       ▼                    ▼                        ▼                      ▼                     ▼
   Business              Reviews                 Themes               Analysis              Report
    Node               Analyzed               Created/Updated           Node                 Node

Pipeline Stages:

  1. DataFetcherAgent (walkers.jac:253) - Fetches business data and reviews from SERP API
  2. SentimentAnalyzerAgent (walkers.jac:599) - Analyzes sentiment, themes, keywords, emotions using LLM
  3. PatternAnalyzerAgent (walkers.jac:732) - Identifies patterns, sub-themes, and metrics across reviews
  4. ReportGeneratorAgent (walkers.jac:1129) - Generates comprehensive analysis report with SWOT, trends, health scores
  5. RecommendationAgent (walkers.jac:1255) - Creates actionable recommendations based on analysis

File Structure

jac-review-analysis/
├── main.jac              # Entry point, AnalyzeUrl walker, module imports
├── models.jac            # Node definitions, edges, enums, type mappings
├── walkers.jac           # Agent walkers (the 5-stage pipeline)
├── api_walkers.jac       # API endpoints (GetBusinesses, GetReport, GetReviews, Reanalyze, DeleteBusiness, GetStats)
├── auth_walkers.jac      # Authentication (create_user_profile, get_user_profile, update_subscription, admin operations)
├── Dockerfile            # Production deployment with jac-scale
├── docker-compose.yml    # Local development environment
└── requirements.txt      # Python dependencies (jaseci, jac, jac-byllm, jac-scale)

Development Commands

Running the Application

# Interactive mode (for testing/debugging)
jac run main.jac

# Development API server (deprecated - use jac start instead)
jac serve main.jac

# Production API server with jac-scale (recommended)
jac start main.jac --port 8000

# Compile to bytecode (required before production deployment)
jac build main.jac

Docker Deployment

# Build and run with docker-compose
docker-compose up --build

# Build Docker image
docker build -t review-analyzer .

# Run container
docker run -p 8000:8000 \
  -e SERPAPI_KEY=your_key \
  -e OPENAI_API_KEY=your_key \
  -e LLM_MODEL=gpt-4o-mini \
  review-analyzer

Environment Variables

Required:

  • SERPAPI_KEY - SerpAPI key for fetching Google Maps data
  • OPENAI_API_KEY - OpenAI API key for LLM operations
  • LLM_MODEL - Default: gpt-4o-mini (can use gpt-4, gpt-4-turbo, etc.)

Optional:

  • PORT - Server port (default: 8000)
  • DEBUG - Enable debug mode (default: false)

Key JAC Concepts

Graph Traversal Syntax

# Get all connected nodes of a specific type
businesses = [root -->(`?Business)];              # All businesses from root
reviews = [business -->(`?Review)];               # All reviews from business
themes = [business -->(`?Theme)];                 # All themes from business

# Connect nodes (creates edge)
root ++> business;                                # Connect and create edge
business ++> review;                              # Connect review to business

Walker Invocation

# Spawn walker on a node
spawn DataFetcherAgent(url=url, max_reviews=100) on business;

# Walker navigates to specific node types
can start with `root entry { ... }               # Entry point at root
can analyze with Business entry { ... }          # Entry point at Business nodes

LLM Integration (by llm)

# Define LLM-powered function (no prompt engineering needed!)
obj ReviewSentiment {
    has sentiment: str;          # "positive", "negative", "neutral"
    has sentiment_score: float;  # -1.0 to 1.0
    has themes: list[str];
    has keywords: list[str];
    has emotion: str;
}

def analyze_review_sentiment(
    review_text: str,
    star_rating: int
) -> ReviewSentiment by llm();

# The `by llm` operator:
# - Automatically generates prompts from function signature
# - Handles JSON parsing and type validation
# - Returns structured output matching the return type

Critical Fixes & Known Issues

Theme Duplication on Reanalysis

Issue: The Reanalyze walker (api_walkers.jac:367) was creating duplicate themes.

Fix: Added cleanup phase at lines 395-410 to delete old Theme, Analysis, and Report nodes before re-running the analysis pipeline:

# Delete old analysis artifacts to prevent duplicates
old_themes = [target_biz -->(`?Theme)];
old_analyses = [target_biz -->(`?Analysis)];
old_reports = [target_biz -->(`?Report)];

for theme in old_themes { del theme; }
for analysis in old_analyses { del analysis; }
for report in old_reports { del report; }

Review Metadata Fields

Fields: Each Review node stores:

  • review_link - Direct Google Maps review URL (from SERP API link field)
  • author_image - Reviewer profile image URL (from SERP API user.thumbnail field)

These fields are captured in DataFetcherAgent (walkers.jac:526) and returned by GetReviews API (api_walkers.jac:320-321).

Authentication & User Management

User Isolation

  • Each authenticated user has an isolated root node
  • UserProfile is connected to the user's root (root --> UserProfile)
  • All businesses, reviews, analyses are scoped to that user's graph
  • No username parameters needed - authentication context provides isolation

Subscription Tiers

Defined in models.jac:12-16:

  • FREE: 5 businesses, 10 analyses/day
  • PRO: 50 businesses, 100 analyses/day
  • ENTERPRISE: Unlimited businesses and analyses

Limits are enforced in AnalyzeUrl walker before running the pipeline.

API Endpoints

When running jac start main.jac, the API is available at http://localhost:8000:

Core Analysis

  • POST /walker/AnalyzeUrl - Analyze a Google Maps URL (runs full pipeline)
  • POST /walker/Reanalyze - Re-run analysis on existing business data

Data Retrieval

  • POST /walker/GetBusinesses - List analyzed businesses with pagination
  • POST /walker/GetReport - Get full report for a business
  • POST /walker/GetReviews - Get reviews with filters (sentiment, rating, date)
  • POST /walker/GetStats - Get user statistics (total businesses, analyses today)

User Management

  • POST /walker/create_user_profile - Create user profile after registration
  • POST /walker/get_user_profile - Get current user profile and limits
  • POST /walker/update_subscription - Update subscription tier (admin)

Review Reply Generation

  • POST /walker/SaveReplyPromptConfig - Save/update reply generation preferences
  • POST /walker/GetReplyPromptConfig - Get current reply configuration
  • POST /walker/GenerateReviewReply - Generate AI reply for a single review (0.25 credits)
  • POST /walker/BulkGenerateReviewReplies - Generate replies for multiple reviews
  • POST /walker/RegenerateReviewReply - Regenerate reply with current settings (0.25 credits)
  • POST /walker/GetReviewReplies - Get all generated replies for a business
  • POST /walker/DeleteReviewReply - Delete a generated reply

Content Generation

  • POST /walker/GetResponseTemplates - Browse/filter response templates (FREE)
  • POST /walker/CreateResponseTemplate - Create custom response template (FREE)
  • POST /walker/ApplyTemplate - Apply template to a review with rule-based placeholder filling (FREE, stores ReviewReply)
  • POST /walker/GetSuggestedTemplates - Get templates matching a review's sentiment/rating (FREE)
  • POST /walker/DeleteResponseTemplate - Delete user-created template (FREE)
  • POST /walker/GenerateActionPlan - Generate improvement roadmap (0.5 credits)
  • POST /walker/GetActionPlans - Get action plans for a business
  • POST /walker/DeleteActionPlan - Delete an action plan
  • POST /walker/SuggestSocialMediaConfig - FREE: Auto-generate smart config suggestions from business analysis data (brand voice, personality traits, hashtags, audience, keywords, tone examples, CTA, recommended post types)
  • POST /walker/SaveSocialMediaPostConfig - Save social media branding preferences (enhanced: brand_personality_traits, target_audience, industry_keywords, avoid_words, tone_examples, language)
  • POST /walker/GetSocialMediaPostConfig - Get current social media config
  • POST /walker/GenerateSocialMediaPosts - Generate social posts from reviews (0.25 credits/batch). Supports post_type (testimonial, question_engagement, tips_based, milestone_celebration, aggregate_insight, story_narrative, before_after), hook_style (auto, bold_statement, curiosity, social_proof, question, quote_first, data_point), variants_count (1-3 A/B variants), 6 platforms (twitter, facebook, instagram, linkedin, tiktok, google_business_profile)
  • POST /walker/GetSocialMediaPosts - Get generated posts for business (filter by platform, post_type)
  • POST /walker/DeleteSocialMediaPost - Delete a generated post
  • POST /walker/SaveMarketingCopyConfig - Save brand/ad preferences
  • POST /walker/GetMarketingCopyConfig - Get current marketing config
  • POST /walker/GenerateMarketingCopy - Generate ad copy variants (0.25 credits/batch)
  • POST /walker/GetMarketingCopies - Get generated copy for business
  • POST /walker/DeleteMarketingCopy - Delete generated copy
  • POST /walker/SaveBlogPostConfig - Save writing preferences
  • POST /walker/GetBlogPostConfig - Get current blog config
  • POST /walker/GenerateBlogPost - Generate a blog post (1.0 credits)
  • POST /walker/GetBlogPosts - Get blog posts for business
  • POST /walker/DeleteBlogPost - Delete a blog post

Utilities

  • POST /walker/DeleteBusiness - Delete a business and all related data
  • POST /walker/health_check - Health check endpoint

API documentation is auto-generated at http://localhost:8000/docs (FastAPI/Swagger UI).

Business Type Detection

The system auto-detects business types from Google Maps categories using BUSINESS_TYPE_MAP (models.jac:29-110):

  • RESTAURANT - Restaurants, cafes, bakeries, bars
  • HOTEL - Hotels, resorts, lodging
  • RETAIL - Stores, shops, supermarkets
  • SALON - Beauty salons, spas, barber shops
  • HEALTHCARE - Hospitals, clinics, dentists
  • ENTERTAINMENT - Museums, theaters, amusement parks
  • AUTO_SERVICE - Car repair, dealerships, gas stations
  • GYM - Gyms, fitness centers
  • GENERIC - Fallback for unmatched types

Business type determines which sub-themes are analyzed (e.g., "Food Quality" for restaurants, "Room Quality" for hotels).

Review Reply Generation System

The system supports AI-powered review reply generation with customizable settings.

Credit Cost

  • 0.25 credits per reply (single or bulk)
  • Credits are float values to support fractional costs

Graph Structure

Review ──(HasReply)──> ReviewReply
   │                        ├── reply_text: str
   │                        ├── generated_at: str
   │                        └── credits_used: float (0.25)
   │
Business ──(HasReplyConfig)──> ReplyPromptConfig
                                    ├── tone: str (friendly, formal, casual, friendly_professional)
                                    ├── max_length: str (short, medium, long)
                                    ├── include_name: bool
                                    ├── offer_resolution: bool
                                    └── custom_instructions: str

Reply Configuration Options

  • tone: friendly, formal, casual, friendly_professional (default)
  • max_length: short (1-2 sentences), medium (2-3), long (3-4)
  • include_name: Include reviewer's name in reply
  • offer_resolution: Offer resolution for negative reviews
  • sign_off: Custom sign-off text
  • custom_instructions: Additional LLM instructions

Context-Aware Generation

Replies are generated using:

  1. Review data: text, rating, sentiment, themes, emotion
  2. Business context: name, type, strengths (delighters), known issues (pain points)
  3. User config: tone, length, and custom instructions

Content Generation System

The system includes 5 content generation features in content_walkers.jac:

Credit Costs

  • Response Template Library: FREE (browse/create/apply with rule-based placeholder filling)
  • Action Plan Generator: 0.5 credits per plan
  • Social Media Post Generator: 0.25 credits per batch (up to 5 posts, with A/B variants)
  • Marketing Copy Generator: 0.25 credits per batch (up to 3 A/B variants)
  • Blog Post Generator: 1.0 credits per post

Graph Extensions

root ──> ResponseTemplate (system + user-created templates)
root ──> SocialMediaPostConfig / MarketingCopyConfig / BlogPostConfig
Business ──> ActionPlan / SocialMediaPost / MarketingCopy / BlogPost

Social Media Post Generator (Enhanced)

Post Types: testimonial, question_engagement, tips_based, milestone_celebration, aggregate_insight, story_narrative, before_after

Hook Styles: auto, bold_statement, curiosity, social_proof, question, quote_first, data_point

Platforms: twitter, facebook, instagram, linkedin, tiktok, google_business_profile

A/B Variants: variants_count (1-3) generates multiple versions with different hooks/angles

Enhanced Config (SocialMediaPostConfig):

  • brand_voice: Base voice preset or custom descriptive text
  • brand_personality_traits: e.g. ["warm", "expert", "local"]
  • target_audience: e.g. "young families in urban areas"
  • industry_keywords: Terms to naturally incorporate
  • avoid_words: Words/phrases to never use
  • tone_examples: Example sentences showing desired voice
  • language: Output language (supports transcreation, not just translation)

Post Output includes visual_suggestion (image description) and graphic_type (photo/text_overlay/carousel/video/reel)

LLM Framework: Every post follows Hook-Story-CTA structure with platform-specific emoji counts, hashtag targets, and character windows.

File

  • content_walkers.jac - All 22 content generation walker definitions

Important Notes

Security

  • Never expose API keys in walker properties - They get serialized in responses
  • API keys should only be in environment variables or passed as walker parameters that are not part of output
  • UserProfile nodes handle authentication context - no manual username passing needed

Performance

  • Reviews are cached after first fetch - use force_refresh=True to re-fetch
  • freshness_days parameter controls cache validity (default: 7 days)
  • Large businesses (500+ reviews) may take 2-3 minutes for full analysis due to LLM calls
  • Consider pagination for GetReviews when dealing with businesses that have 100+ reviews

Data Cleanup

When deleting a business (DeleteBusiness walker), all related nodes are deleted:

  • All Review nodes
  • All Theme nodes
  • All Analysis nodes
  • All Report nodes
  • The Business node itself

This prevents orphaned data in the graph.

PRD Documentation

Frontend PRD documents are available in /prd-docs/:

  • 01-OVERVIEW.md - Product goals, target users
  • 02-TECH-STACK.md - Vite, React, shadcn/ui stack
  • 03-ARCHITECTURE.md - Frontend folder structure
  • 04-API-SERVICE.md - API client implementation
  • 05-AUTHENTICATION.md - JWT handling, login flows
  • 06-PAGES.md - All page specifications
  • 07-COMPONENTS.md - Reusable component library
  • 08-REPORT-DISPLAY.md - Report visualization strategy
  • 09-ADMIN-PANEL.md - Admin features
  • 10-BRANDING.md - Theming and white-labeling
  • 11-RESPONSIVE.md - Mobile/tablet responsive design
  • 12-DEPLOYMENT.md - Build and deployment guide

The backend API is production-ready and hosted at https://review-analysis-server.trynewways.com/.

Related Documents

CLAUDE.md

Claude AI Git Workflow Integration

When working with git repositories and suggesting commit workflows, always recommend using the `git-ai-commit` CLI tool for creating commit messages.

airagclaude
0
9
the-cafe
CLAUDE.md

Code indexing for AI agents: summarization strategies and evaluation systems

**The most effective code indexing systems combine hierarchical LLM-generated summaries with AST structural data and vector embeddings through hybrid retrieval—achieving up to 80% codebase reduction while maintaining high accuracy for AI coding agents.** Leading tools like Cursor, Sourcegraph Cody, and Continue.dev demonstrate that no single retrieval method suffices; production systems require semantic search, keyword matching, and structural queries working together. For evaluation, the field

aiagentllm
0
9
MadAppGang
CLAUDE.md

Missing Business Agents Research — FLUXION 2026

> Deep Research CoVe 2026 | Date: 2026-03-23

aiagentrag
0
8
lukeeterna
CLAUDE.md

write-script

Write a full video script for @SketchySurvival101 following all rules in CLAUDE.md.

airagclaude
0
5
anurieli