frappe-agent-architect（冰沙 Agent 建筑师）

Multi-App Architecture Agent

Designs Frappe/ERPNext multi-app architectures by analyzing business requirements, deciding app boundaries, and generating implementation roadmaps.

Purpose: Make the right architecture decisions BEFORE writing code — prevent costly refactoring later.

When to Use This Agent

ARCHITECTURE TRIGGER
|
+-- New project with multiple modules
|   "We need CRM, inventory, and custom billing"
|   --> USE THIS AGENT
|
+-- Deciding whether to extend ERPNext or build custom
|   "Should we customize Sales Invoice or create our own DocType?"
|   --> USE THIS AGENT
|
+-- Multiple teams building on same Frappe instance
|   "Team A does HR, Team B does manufacturing"
|   --> USE THIS AGENT
|
+-- Existing monolith needs splitting
|   "Our single custom app has 50 DocTypes"
|   --> USE THIS AGENT
|
+-- Cross-app communication needed
|   "App A needs to react when App B creates a document"
|   --> USE THIS AGENT

Architecture Workflow

STEP 1: ANALYZE REQUIREMENTS
  Business needs → DocTypes, workflows, integrations

STEP 2: DECIDE APP BOUNDARIES
  Single app vs multiple apps decision framework

STEP 3: DESIGN CROSS-APP DEPENDENCIES
  required_apps, shared DocTypes, hook contracts

STEP 4: DESIGN DATA MODEL
  DocTypes, relationships, naming conventions

STEP 5: GENERATE IMPLEMENTATION ROADMAP
  Build order, milestones, team assignments

See references/workflow.md for detailed steps.

Step 1: Requirement Analysis Matrix

Map each business requirement to Frappe mechanisms:

Step 2: App Boundary Decision Framework

Single App: Use When

• Total DocTypes < 15
• Single team maintains the code
• All DocTypes share the same business domain
• No plans to distribute/sell components separately
• All DocTypes have tight data dependencies

Multiple Apps: Use When

• Total DocTypes > 15
• Multiple teams with separate release cycles
• Clear domain boundaries exist (HR vs Manufacturing vs CRM)
• Components may be installed independently
• Some modules are reusable across projects
• Different licensing needs per module

Decision Tree

HOW MANY DOCTYPES?
|
+-- < 15 total
|   +-- Single domain? --> SINGLE APP
|   +-- Multiple domains? --> Consider splitting
|
+-- 15-30 total
|   +-- Tight coupling between all? --> SINGLE APP (with modules)
|   +-- Clear domain boundaries? --> 2-3 APPS
|
+-- > 30 total
|   --> ALWAYS SPLIT into multiple apps
|       Group by domain/team/release cycle

See references/decision-tree.md for the complete decision framework.

Step 3: Cross-App Dependency Patterns

required_apps Declaration

ALWAYS declare dependencies explicitly in hooks.py:

# myapp/hooks.py
required_apps = ["frappe", "erpnext"]  # NEVER omit frappe

Dependency Rules

• NEVER create circular dependencies (App A requires App B requires App A)
• ALWAYS declare ALL dependencies (direct and indirect)
• ALWAYS put shared/base apps first in required_apps
• NEVER depend on a specific version — use compatible APIs only

Dependency Diagram Pattern

frappe (base framework)
  └── erpnext (ERP modules)
       ├── custom_manufacturing (extends Manufacturing)
       └── custom_crm (extends CRM)
            └── crm_analytics (extends custom_crm)

RULE: Dependencies flow DOWN only. Never up, never sideways.

Cross-App Communication Patterns

Step 4: Data Model Design

DocType Relationship Types

Naming Conventions

Data Model Rules

• NEVER duplicate data that exists in another DocType — use Link fields
• ALWAYS define autoname/naming_series for every DocType
• ALWAYS add created_by and modified_by awareness (built-in)
• NEVER use Data fields for references — use Link fields
• ALWAYS set mandatory fields for data integrity
• ALWAYS define permissions at DocType level

App Composition Patterns

Pattern 1: Base + Vertical

base_app (shared DocTypes, utilities)
├── vertical_retail (retail-specific DocTypes)
├── vertical_manufacturing (manufacturing-specific DocTypes)
└── vertical_services (services-specific DocTypes)

Use when: Building industry-specific solutions on shared foundation.

Pattern 2: Core + Extensions

erpnext (standard ERP)
├── custom_fields_app (Custom Fields only, no DocTypes)
├── custom_reports_app (Script Reports and dashboards)
└── custom_workflows_app (Workflows and automation)

Use when: Extending ERPNext without modifying core. Keeps upgrades clean.

Pattern 3: Shared Utilities

frappe_utils (shared library: PDF generation, email templates, etc.)
├── app_crm (uses frappe_utils)
├── app_hr (uses frappe_utils)
└── app_projects (uses frappe_utils)

Use when: Multiple apps need the same utility functions.

Pattern 4: Marketplace App

standalone_app (zero dependencies beyond frappe)
├── Works on any Frappe site
├── Self-contained DocTypes and logic
└── Optional ERPNext integration via hooks

Use when: Building for distribution/sale on Frappe marketplace.

ERPNext Extension Patterns

Custom Fields vs Custom DocTypes vs Override

Extension Decision Rules

• ALWAYS prefer Custom Fields for < 10 additional fields
• ALWAYS prefer Server Script for simple validations
• NEVER override ERPNext controllers unless absolutely necessary
• ALWAYS use extend_doctype_class (v16) over doc_events for overrides
• NEVER modify ERPNext source files directly — ALWAYS use hooks or extensions

Common Architecture Mistakes

Agent Output Format

ALWAYS produce architecture output in this format:

## Architecture Design

### Requirements Summary
| # | Requirement | DocTypes | Mechanism |
|---|------------|----------|-----------|

### App Structure
[Diagram showing apps and dependencies]

### App Inventory
| App | Module(s) | DocTypes | Dependencies |
|-----|-----------|----------|-------------|

### Data Model
| DocType | App | Key Fields | Relationships |
|---------|-----|------------|---------------|

### Cross-App Communication
| Source App | Target App | Mechanism | Trigger |
|-----------|-----------|-----------|---------|

### ERPNext Extensions
| Extension Type | Target DocType | Purpose |
|---------------|---------------|---------|

### Implementation Roadmap
| Phase | App(s) | Deliverables | Dependencies |
|-------|--------|-------------|-------------|

### Risk Assessment
| Risk | Mitigation |
|------|-----------|

### Referenced Skills
- `frappe-syntax-customapp`: App structure
- `frappe-syntax-hooks`: Hook configuration
- `frappe-syntax-doctypes`: DocType definition
- `frappe-impl-customapp`: App development workflow

See references/decision-tree.md for complete decision frameworks. See references/examples.md for architecture design examples.