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

Dependency direction: interfaces → application → domain ← infrastructure
Domain layer has ZERO external imports (no gin, gorm, zap, redis)
tenantID is always an explicit method parameter — never from context in domain layer
All DB queries must include tenant_id — multi-tenant isolation is mandatory
All responses use kernel/response — unified format with trace_id
All errors use kernel/errors — error codes, not raw strings
bcrypt cost ≥ 12 for password hashing
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

Create internal/modules/<name>/ with 4 subdirectories
Define entities and interfaces in domain/ (no external deps)
Implement business logic in application/
Implement repositories in infrastructure/ (uses GORM)
Create HTTP handlers and routes in interfaces/
Export fx.Module from interfaces/module.go
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)

2.7 KiB Raw Blame History