mmap/CLAUDE.md

CLAUDE.md

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

Project Overview

MAPP (Map Application Server) is a modern GraphQL-based map application server written in Rust. It features:

• GraphQL API with async-graphql
• RBAC permission management using Casbin
• Kafka message queue integration
• PostgreSQL database with migrations
• CLI management tools
• Blog system with categories and tags
• Rate limiting and authentication
• Multi-tenant architecture support

Development Commands

Build & Run

# Development build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

# Code linting
cargo clippy

# Start development server with auto-migration
./target/release/mapp serve --dev --verbose

# Start production server
./target/release/mapp serve

# Start with Kafka integration
./target/release/mapp serve --kafka

Database Management

# Run database migrations
./target/release/mapp migrate

# Check migration status (dry run)
./target/release/mapp migrate --dry-run

# Force re-run migrations
./target/release/mapp migrate --force

Permission Management

# List all permission policies
./target/release/mapp permissions list

# Add permission policy
./target/release/mapp permissions add --role admin --resource users --action delete

# Assign role to user
./target/release/mapp permissions assign-role --user-id user123 --role editor

# Check user permissions
./target/release/mapp permissions check --user-id user123 --resource pages --action write

# Reload permission policies
./target/release/mapp permissions reload

Blog Management

# Create blog post
./target/release/mapp blog create --title "Post Title" --slug "post-slug" --content '{"type":"doc","content":[]}' --user-id user123

# List blog posts
./target/release/mapp blog list --page 1 --limit 10

# Show blog post details
./target/release/mapp blog show post-slug --detail

# Create blog category
./target/release/mapp blog create-category --name "Tech" --slug "tech" --user-id user123

# View blog statistics
./target/release/mapp blog stats

Configuration

# Show current configuration
./target/release/mapp config

# Show version information
./target/release/mapp version

Architecture Overview

Core Modules

• app.rs: Application router configuration and HTTP server setup
• auth.rs: Authentication and authorization middleware
• cli.rs: Command-line interface definitions
• config.rs: Configuration management from environment variables
• db.rs: Database connection pool and migration handling

GraphQL Layer

• graphql/: Complete GraphQL implementation
  • queries.rs: Query resolvers for data retrieval
  • mutations.rs: Mutation resolvers for data modification
  • guards.rs: Permission guards for access control
  • types/: GraphQL type definitions (users, blog, config, permissions)
  • subscription.rs: Real-time subscriptions

Data Layer

• models/: Database models and schemas
  • user.rs: User authentication and profile models
  • blog.rs: Blog posts, categories, and tags
  • config.rs: System configuration settings
  • page_block.rs: Page content management
  • invite_code.rs: User invitation system

Service Layer

• services/: Business logic and data operations
  • casbin_service.rs: RBAC permission management
  • blog_service.rs: Blog content management
  • config_service.rs: Configuration management
  • user_service.rs: User management operations
  • mosaic_service.rs: Tile server proxy operations

Infrastructure

• listener/: Kafka message queue integration
• migrations/: Database schema migrations (PostgreSQL)

Key Configuration

Required Environment Variables

• DATABASE_URL: PostgreSQL connection string
• JWT_SECRET: JWT signing secret
• TILE_SERVER: Map tile server URL

Optional Environment Variables

• PORT: Server port (default: 3000)
• KAFKA_BROKERS: Kafka cluster addresses (default: localhost:9092)
• KAFKA_TOPIC: Kafka topic name (default: mapp-events)
• KAFKA_GROUP_ID: Kafka consumer group (default: mapp-group)
• KAFKA_SKIP_HISTORICAL: Skip historical messages on restart (default: true)

Permission System

The application uses Casbin for RBAC (Role-Based Access Control):

Default Resources

• users: User management operations
• pages: Page content management
• page_blocks: Page block operations
• blogs: Blog management
• categories: Blog category management
• tags: Blog tag management
• settings: System configuration

Default Actions

• read: View/list operations
• write: Create/update operations
• delete: Delete operations
• admin: Administrative operations

Common Roles

• admin: Full system access (* resource, * action)
• editor: Content management (pages, blogs read/write)
• viewer: Read-only access (pages, blogs read)

Blog System

The blog system supports:

• Rich content with JSON structure
• Categories with hierarchical organization
• Tags for content classification
• Draft/Published/Archived status workflow
• Featured content highlighting
• SEO metadata (meta_title, meta_description)
• View tracking and statistics

Settings System

Comprehensive configuration management with:

• Multiple data types (string, number, boolean, json)
• Category-based organization
• System vs user configuration separation
• Encryption support for sensitive data
• History tracking and audit trail
• GraphQL API for management

Development Notes

• The application automatically runs migrations in development mode (--dev)
• Use --verbose flag for detailed debugging information
• Kafka integration is optional and can be enabled with --kafka flag
• All CLI commands require proper database configuration
• GraphQL playground available at /graphql in development mode
• The system supports both UUID-based and slug-based content access