MMR SaaS Agent Ecosystem¶

Version: 2.0.0 Project: MMR Multi-Tenant SaaS Platform Stack: NestJS + Next.js 15 + Turborepo Total Agents: 16 (10 Frontend + 6 Backend)

📦 Agent System Overview¶

This directory contains specialized Claude AI agents organized into two independent ecosystems:

• Frontend Agents (.claude/agents/frontend/) - Automate UI module development (Next.js, React, TanStack Query)
• Backend Agents (.claude/agents/backend/) - Automate API module development (NestJS, TypeORM, REST)

This separation provides developer-friendly organization with clear boundaries between frontend and backend concerns.

🎭 Frontend Agent Roster (10 Agents)¶

Located in: .claude/agents/frontend/

See: frontend/README.md for detailed frontend agent documentation.

⚙️ Backend Agent Roster (6 Agents)¶

Located in: .claude/agents/backend/

See: backend/README.md for detailed backend agent documentation.

🧭 Decision Guide: Frontend vs Backend Agent?¶

Use Frontend Agents when: - Building UI components, pages, forms - Creating React hooks or API client services - Generating TypeScript types for frontend - Working on Next.js routes or app structure - Example: "Create a users list page with filters"

Use Backend Agents when: - Creating database entities and migrations - Building REST API endpoints - Implementing business logic and services - Writing backend DTOs and validation - Example: "Create a products API with CRUD endpoints"

Quick Reference: - Frontend work → @orchestrate (frontend orchestrator) - Backend work → @backend-orchestrate (backend orchestrator)

🚀 Quick Start¶

Create a Complete Frontend Module¶

@orchestrate create users module

This will: 1. Design module architecture 2. Generate TypeScript types 3. Create Zod validation schemas 4. Build API service layer 5. Generate TanStack Query hooks 6. Create React components (List, Form, Details) 7. Build Next.js pages (list, create, [id], [id]/edit) 8. Run quality validation

Output: 12+ production-ready frontend files

Create a Complete Backend Module¶

@backend-orchestrate create products module

This will: 1. Generate TypeORM entity (extends BaseEntity for multi-tenancy) 2. Create DTOs (Create, Update, Response, Query) with validation 3. Build NestJS service with CRUD operations 4. Generate REST controller with guards and Swagger docs 5. Create unit tests and E2E tests

Output: 8+ production-ready backend files

🏗️ Module Structure Generated¶

Frontend Module Structure¶

For a frontend module named "users":

apps/web/src/modules/users/
├── components/
│   ├── UserList.tsx           # Data table with search/filter
│   ├── UserForm.tsx            # Create/edit form with validation
│   └── UserDetails.tsx         # Detail view with actions
├── hooks/
│   ├── useUsers.ts             # List query hook
│   ├── useUser.ts              # Single query hook
│   ├── useCreateUser.ts        # Create mutation hook
│   ├── useUpdateUser.ts        # Update mutation hook
│   └── useDeleteUser.ts        # Delete mutation hook
├── services/
│   └── user.service.ts         # API client methods
├── schemas/
│   └── user.schema.ts          # Zod validation schemas
├── types/
│   └── user.types.ts           # Module-specific types
└── utils/
    └── user.utils.ts           # Helper functions (optional)

apps/web/src/app/(dashboard)/users/
├── page.tsx                    # List page
├── create/
│   └── page.tsx               # Create page
└── [id]/
    ├── page.tsx               # Detail page
    └── edit/
        └── page.tsx           # Edit page

Backend Module Structure¶

For a backend module named "products":

apps/backend/src/modules/products/
├── entities/
│   └── product.entity.ts       # TypeORM entity (extends BaseEntity)
├── dto/
│   ├── create-product.dto.ts   # Create DTO with validation
│   ├── update-product.dto.ts   # Update DTO (PartialType)
│   ├── product-response.dto.ts # Response DTO for API
│   └── product-query.dto.ts    # Query/filter DTO
├── products.service.ts          # Business logic & CRUD
├── products.service.spec.ts     # Unit tests
├── products.controller.ts       # REST endpoints with guards
├── products.controller.spec.ts  # Controller unit tests
└── products.module.ts           # NestJS module definition

apps/backend/test/
└── products.e2e-spec.ts         # E2E integration tests

📋 Workflows¶

Frontend 6-Step Workflow¶

Step 1: Type Architect - Input: Module name, entity structure - Output: types/[module].types.ts - Generates TypeScript interfaces, DTOs, filter types

Step 2: Schema Engineer - Input: Generated types - Output: schemas/[module].schema.ts - Creates Zod validation schemas for forms

Step 3: Service Builder - Input: Types and schemas - Output: services/[module].service.ts - Builds API service layer with CRUD operations

Step 4: Hook Factory - Input: Service methods - Output: hooks/use[Module].ts, etc. - Generates TanStack Query hooks (queries + mutations)

Step 5: Component Builder - Input: Hooks and schemas - Output: components/[Module]List.tsx, etc. - Creates List, Form, Details components

Step 6: Page Generator - Input: Components - Output: 4 Next.js pages - List, Create, Detail, Edit pages

Backend 5-Step Workflow¶

Step 1: Entity Builder - Input: Module name, entity structure - Output: entities/[module].entity.ts - Generates TypeORM entity extending BaseEntity (auto tenant_id)

Step 2: DTO Builder - Input: Entity definition - Output: dto/*.dto.ts (4 files) - Creates Create, Update, Response, Query DTOs with class-validator

Step 3: Service Builder - Input: Entity and DTOs - Output: [module].service.ts - Implements CRUD operations, query building, pagination

Step 4: Controller Builder - Input: Service methods - Output: [module].controller.ts - Creates REST endpoints with guards, Swagger docs

Step 5: Test Builder - Input: Service and controller - Output: *.spec.ts, *.e2e-spec.ts - Generates unit tests (mocked) and E2E tests (test DB)

🎯 Pattern Enforcement¶

Frontend Patterns¶

• ✅ TypeScript strict mode (no any types)
• ✅ Service layer pattern (all API calls through services)
• ✅ TanStack Query for server state management
• ✅ React Hook Form + Zod for form validation
• ✅ Shadcn/UI components with proper accessibility
• ✅ Loading/error/empty states for all data components
• ✅ Tenant context from auth store
• ✅ JSDoc comments for complex logic

Backend Patterns¶

• ✅ All entities extend BaseEntity for automatic multi-tenancy
• ✅ DTOs with class-validator decorators
• ✅ Services use repository pattern (TypeORM)
• ✅ Controllers have JwtAuthGuard + RolesGuard
• ✅ Swagger/OpenAPI annotations on all endpoints
• ✅ Proper HTTP status codes (201, 404, 400, etc.)
• ✅ Unit tests with mocked dependencies
• ✅ E2E tests verify multi-tenant isolation
• ✅ UUID validation on ID parameters

📖 Usage Examples¶

Frontend Examples¶

Create a Complete Frontend Module:

@orchestrate create products module

Add a Feature to Existing Module:

@architecture design export functionality for users
# Review plan
@service-builder add export method to user.service.ts
@hook-factory create useExportUsers hook
@component-builder add export button to UserList

Review Frontend Code:

@quality review src/modules/users/components/UserForm.tsx

Backend Examples¶

Create a Complete Backend Module:

@backend-orchestrate create orders module

Add Individual Backend Components:

@entity-builder create category entity
@dto-builder create DTOs for categories
@service-builder implement category service with CRUD
@controller-builder create category REST endpoints
@test-builder generate tests for categories

Create Backend API Endpoint:

@controller-builder add GET /products/top-selling endpoint
@service-builder implement getTopSellingProducts method
@test-builder add E2E test for top-selling endpoint

🔍 Agent Communication¶

Frontend Workflow Chain¶

Frontend Orchestrator
  ↓ (module design)
Architecture Agent
  ↓ (entity blueprint)
Type Architect
  ↓ (types file path)
Schema Engineer
  ↓ (schemas file path)
Service Builder
  ↓ (service file path)
Hook Factory
  ↓ (hooks file paths)
Component Builder
  ↓ (component file paths)
Page Generator
  ↓ (page file paths)
Quality Agent
  ↓ (validation report: PASS/FAIL)

Backend Workflow Chain¶

Backend Orchestrator
  ↓ (module design)
Entity Builder
  ↓ (entity file path)
DTO Builder
  ↓ (DTO file paths)
Service Builder
  ↓ (service file path)
Controller Builder
  ↓ (controller file path)
Test Builder
  ↓ (test file paths)
Module Integration
  ↓ (complete backend module ready)

📚 Reference Documentation¶

• Architecture Plan: /.claude/plans/sharded-whistling-crescent.md
• Section 9: Claude Sub-Agent Guide for Frontend Development
• Multi-Tenancy: Row-level isolation with AsyncLocalStorage
• Auth System: JWT with tenant context

🛠️ Troubleshooting¶

Agent Not Activating¶

Ensure you're using the correct invocation:

@[agent-name] [command]

Pattern Violations¶

Run quality agent:

@quality review [module-name]

Missing Dependencies¶

Check that all shared packages are installed:

pnpm install

📝 Notes¶

• Organization: Frontend agents in frontend/, backend agents in backend/
• Invocation: Use @orchestrate for frontend, @backend-orchestrate for backend
• Architecture Plan: Agents read from .claude/plans/sharded-whistling-crescent.md
• Multi-Tenancy: All backend entities automatically enforce tenant isolation via BaseEntity
• Testing: Backend E2E tests verify multi-tenant data isolation
• Workflows: Follow 6-step (frontend) or 5-step (backend) workflow in order
• Quality: Run quality agent after module completion for validation
• Shared Packages: @mmr/types and @mmr/schemas used across frontend/backend

📚 Additional Documentation¶

• Frontend Agent Guide: frontend/README.md
• Backend Agent Guide: backend/README.md
• Architecture Plan: .claude/plans/sharded-whistling-crescent.md (Section 9 & 14)
• Multi-Tenancy: Row-level isolation with AsyncLocalStorage
• Auth System: JWT with tenant context

Version: 2.0.0 Last Updated: 2026-06-17 Created By: Claude Sonnet 4.5 Total Agents: 16 (10 Frontend + 6 Backend)