# AGENTS.md — MengStack AI-Native Developer Guide

## Project Overview
MengStack is a multi-tenant SaaS development framework built with Go/Gin/PostgreSQL.
It follows a 3-layer architecture: **Kernel** (zero business semantics) → **Middle Platform** (shared capabilities) → **Applications** (business-specific).

## Architecture
```
internal/
  kernel/       # Core shared packages (errors, response, model, tenant)
  app/          # App infrastructure (database, cache, middleware, health)
  modules/      # Business modules, each with 4 layers:
    <module>/
      domain/          # Entities + interfaces (ZERO external deps)
      application/     # Business logic + DTOs
      infrastructure/  # DB/Redis implementations
      interfaces/      # HTTP handlers + routes + fx Module
```

## Key Rules
1. **Dependency direction**: interfaces → application → domain ← infrastructure
2. **Domain layer has ZERO external imports** (no gin, gorm, zap, redis)
3. **tenantID is always an explicit method parameter** — never from context in domain layer
4. **All DB queries must include tenant_id** — multi-tenant isolation is mandatory
5. **All responses use kernel/response** — unified format with trace_id
6. **All errors use kernel/errors** — error codes, not raw strings
7. **bcrypt cost ≥ 12** for password hashing
8. **Redis keys must include tenant_id**: `{app}:{module}:{tenant_id}:{biz}:{id}`

## Tech Stack
- Go 1.23+ / Gin / GORM v2 / PostgreSQL 16 / Redis 7
- uber-go/fx for dependency injection
- uber-go/zap for structured logging
- spf13/viper for configuration
- golang-jwt/jwt/v5 for JWT

## Commands
- `make dev` — Run development server
- `make test` — Run all tests with race detection
- `make build` — Build binary
- `make swagger` — Regenerate Swagger API docs (requires `swag` CLI)
- `make docker-up` — Start PostgreSQL + Redis via Docker Compose
- `make lint` — Run golangci-lint

## Configuration
- Config files: `configs/config.yaml` (base) + `configs/config.{env}.yaml` (overrides)
- Environment variables: prefix `MENGSTACK_`, separator `_` (e.g., `MENGSTACK_DATABASE_HOST`)
- Sensitive values: environment variables only, never in config files or git

## Adding a New Module
1. Create `internal/modules/<name>/` with 4 subdirectories
2. Define entities and interfaces in `domain/` (no external deps)
3. Implement business logic in `application/`
4. Implement repositories in `infrastructure/` (uses GORM)
5. Create HTTP handlers and routes in `interfaces/`
6. Export `fx.Module` from `interfaces/module.go`
7. Add module to `internal/app/app.go` NewApp()

## Testing
- Unit tests: `_test.go` files alongside source (same package)
- Integration tests: `test/` directory
- Always test multi-tenant isolation (two tenants, verify data separation)