63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# 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)
|