/frappe-agent-architect

name: frappe-agent-architect
description: >
  Use when designing multi-app Frappe architectures, deciding whether to split functionality into separate apps, or implementing cross-app communication patterns.
  Prevents monolithic app sprawl, circular dependencies between apps, and broken override chains.
  Covers multi-app architecture decisions, app dependency management, cross-app hooks, override patterns, when to split vs extend, shared DocType strategies.
  Keywords: architecture, multi-app, app splitting, cross-app, dependencies, override, extend, monolith, modular, how to structure frappe apps, when to split apps, app design, multi-app planning..
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

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](references/workflow.md) for detailed steps.

Step 1: Requirement Analysis Matrix

Map each business requirement to Frappe mechanisms:

| Requirement Type | Frappe Mechanism | Example | |-----------------|-----------------|---------| | Data storage | DocType | "Track customer contracts" | | Business rules | Controller/Server Script | "Auto-calculate totals" | | Approval flow | Workflow | "Manager must approve orders >10k" | | Scheduled tasks | Scheduler/hooks.py | "Daily report email" | | External sync | Integration/API | "Sync with Shopify" | | Custom UI | Client Script/Page | "Dashboard for warehouse" | | Reports | Script Report/Query Report | "Monthly sales by region" | | Permissions | Role Permission | "Sales team sees own data only" | | Print output | Print Format (Jinja) | "Custom invoice layout" | | Portal access | Website/Portal | "Customer can view orders" |

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](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

| Pattern | Mechanism | Use When | |---------|-----------|----------| | **Hook Events** | `doc_events` in hooks.py | App B reacts to App A's documents | | **Shared DocType** | Link fields to other app's DocTypes | Apps share reference data | | **API Call** | `frappe.call()` to whitelisted method | Loose coupling between apps | | **Custom Fields** | `fixtures` with Custom Field | Extend another app's DocType without modifying it | | **Override** | `extend_doctype_class` (v16) or `doc_events` | Modify another app's behavior | | **Signals** | `frappe.publish_realtime()` | Real-time notifications between apps |

Step 4: Data Model Design

DocType Relationship Types

| Relationship | Implementation | Example | |-------------|---------------|---------| | One-to-Many | Child Table DocType | Invoice → Invoice Items | | Many-to-One | Link field | Invoice → Customer | | Many-to-Many | Link DocType (intermediary) | Student → Course (via Enrollment) | | One-to-One | Link field + unique validation | Empl