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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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