# CLAUDE.md

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

## Project Overview

VBase is a Go-based identity authentication and permission management framework built on the [Vigo](https://github.com/veypi/vigo) web framework (onion-model middleware architecture). It provides user management, scoped RBAC permissions, and OAuth2 authentication services.

- **Language**: Go 1.24+
- **Framework**: Vigo (onion-model middleware)
- **ORM**: GORM (MySQL, PostgreSQL, SQLite supported)
- **Authentication**: JWT + OAuth2
- **Permissions**: Scoped RBAC (Role-Based Access Control)
- **Frontend**: vhtml (embedded HTML-based UI at `/vb/`)

## Common Commands

```bash
# Run development server (default port 4001)
make run

# Database operations
go run ./cli/main.go db migrate
go run ./cli/main.go db drop

# Run integration tests
go test -v ./tests/...
```

## Architecture

### Onion Model Request Flow

```
Request -> [Global Before Middlewares] -> [Router] -> [Handler] -> [Service] -> [Model] -> Database
                                              |
Response <- [Global After Middleware] <--------+
```

### Directory Structure

```
├── api/              # REST API handlers and routing
│   ├── auth/         # Login, register, refresh token
│   ├── oauth/        # OAuth2 provider endpoints
│   ├── role/         # Role management
│   ├── user/         # User management
│   └── init.go       # Router aggregation
├── auth/             # Core Scoped RBAC permission system
│   ├── auth.go       # Permission checking implementation
│   └── design.md     # Permission system design doc
├── cfg/              # Configuration (DB, Redis, JWT settings)
├── models/           # GORM data models
│   ├── auth.go       # Role, Permission, UserRole models
│   ├── user.go       # User, Identity, Session models
│   └── init.go       # Model registration and migrations
├── libs/             # Utilities (cache, crypto, jwt, sms, email)
├── ui/               # Frontend admin interface (vhtml framework)
├── cli/              # Application entry point
└── tests/            # Go integration tests
```

### Permission System (Scoped RBAC)

The system uses a scoped permission model where permissions are isolated by `Scope` (e.g., "vb" for VBase, "app1" for external apps).

**Permission Format**: `resource:instance:sub-resource:sub-instance` (Tree structure)

**Levels**:
- Level 1: Create (Odd layers)
- Level 2: Read (Even layers)
- Level 4: Write (Even layers)
- Level 7: Admin (Even layers, inherited downwards)

**Key Interfaces**:
- `auth.Factory.New(scope)`: Get scoped auth instance.
- `auth.PermRead(code)`, `auth.PermWrite(code)`: Middleware checks.
- `auth.Grant(ctx, userID, permID, level)`: Grant permission.

### API Response Format

All responses are JSON formatted by `common.JsonResponse` middleware:

**Success:**
```json
{"code": 200, "data": { ... }}
```

**Error:**
```json
{ "code": 40001, "message": "Error description" }
```

### Frontend (vhtml)

The admin UI is in `ui/` using the vhtml framework:
- Access UI at `/vb/` path when server is running
- Routes defined in `ui/routes.js`