Skip to content

Commit a90b121

Browse files
FreekHeijtingclaude
FreekHeijting
and
claude
committed
feat: V2.5 complete - all 25 new skills with full content
Final batch (9 skills): Ops skills: - frappe-ops-deployment: production setup, Docker, SSL, security hardening - frappe-ops-backup: automated backups, S3, encryption, disaster recovery - frappe-ops-performance: MariaDB/Redis/Gunicorn tuning, monitoring - frappe-ops-upgrades: v14->v15->v16 migration, breaking changes database - frappe-ops-frontend-build: esbuild [v15+], build.json [v14], SCSS, Frappe UI - frappe-ops-cloud: Frappe Cloud, Press, managed vs self-hosted Agent skills: - frappe-agent-debugger: 5-step systematic debugging workflow - frappe-agent-migrator: version migration with breaking change detection - frappe-agent-architect: multi-app architecture decision framework All 53 skills now have full content. V2.5 complete. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 9f9c83b commit a90b121

34 files changed

Lines changed: 7721 additions & 62 deletions

File tree

‎skills/source/agents/frappe-agent-architect/SKILL.md‎

Lines changed: 300 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,310 @@ metadata:
1212
version: "2.0"
1313
---
1414

15-
# Multi-App Architecture
15+
# Multi-App Architecture Agent
1616

17-
> **STATUS**: Stub - content pending V2.5 development phase.
17+
Designs Frappe/ERPNext multi-app architectures by analyzing business requirements, deciding app boundaries, and generating implementation roadmaps.
1818

19-
## Quick Reference
19+
**Purpose**: Make the right architecture decisions BEFORE writing code — prevent costly refactoring later.
2020

21-
_Content to be developed._
21+
## When to Use This Agent
2222

23-
## Decision Tree
23+
```
24+
ARCHITECTURE TRIGGER
25+
|
26+
+-- New project with multiple modules
27+
| "We need CRM, inventory, and custom billing"
28+
| --> USE THIS AGENT
29+
|
30+
+-- Deciding whether to extend ERPNext or build custom
31+
| "Should we customize Sales Invoice or create our own DocType?"
32+
| --> USE THIS AGENT
33+
|
34+
+-- Multiple teams building on same Frappe instance
35+
| "Team A does HR, Team B does manufacturing"
36+
| --> USE THIS AGENT
37+
|
38+
+-- Existing monolith needs splitting
39+
| "Our single custom app has 50 DocTypes"
40+
| --> USE THIS AGENT
41+
|
42+
+-- Cross-app communication needed
43+
| "App A needs to react when App B creates a document"
44+
| --> USE THIS AGENT
45+
```
2446

25-
_Content to be developed._
47+
## Architecture Workflow
2648

27-
## See Also
49+
```
50+
STEP 1: ANALYZE REQUIREMENTS
51+
Business needs → DocTypes, workflows, integrations
2852
29-
_Cross-references to be added._
53+
STEP 2: DECIDE APP BOUNDARIES
54+
Single app vs multiple apps decision framework
55+
56+
STEP 3: DESIGN CROSS-APP DEPENDENCIES
57+
required_apps, shared DocTypes, hook contracts
58+
59+
STEP 4: DESIGN DATA MODEL
60+
DocTypes, relationships, naming conventions
61+
62+
STEP 5: GENERATE IMPLEMENTATION ROADMAP
63+
Build order, milestones, team assignments
64+
```
65+
66+
See [references/workflow.md](references/workflow.md) for detailed steps.
67+
68+
## Step 1: Requirement Analysis Matrix
69+
70+
Map each business requirement to Frappe mechanisms:
71+
72+
| Requirement Type | Frappe Mechanism | Example |
73+
|-----------------|-----------------|---------|
74+
| Data storage | DocType | "Track customer contracts" |
75+
| Business rules | Controller/Server Script | "Auto-calculate totals" |
76+
| Approval flow | Workflow | "Manager must approve orders >10k" |
77+
| Scheduled tasks | Scheduler/hooks.py | "Daily report email" |
78+
| External sync | Integration/API | "Sync with Shopify" |
79+
| Custom UI | Client Script/Page | "Dashboard for warehouse" |
80+
| Reports | Script Report/Query Report | "Monthly sales by region" |
81+
| Permissions | Role Permission | "Sales team sees own data only" |
82+
| Print output | Print Format (Jinja) | "Custom invoice layout" |
83+
| Portal access | Website/Portal | "Customer can view orders" |
84+
85+
## Step 2: App Boundary Decision Framework
86+
87+
### Single App — Use When
88+
89+
- Total DocTypes < 15
90+
- Single team maintains the code
91+
- All DocTypes share the same business domain
92+
- No plans to distribute/sell components separately
93+
- All DocTypes have tight data dependencies
94+
95+
### Multiple Apps — Use When
96+
97+
- Total DocTypes > 15
98+
- Multiple teams with separate release cycles
99+
- Clear domain boundaries exist (HR vs Manufacturing vs CRM)
100+
- Components may be installed independently
101+
- Some modules are reusable across projects
102+
- Different licensing needs per module
103+
104+
### Decision Tree
105+
106+
```
107+
HOW MANY DOCTYPES?
108+
|
109+
+-- < 15 total
110+
| +-- Single domain? --> SINGLE APP
111+
| +-- Multiple domains? --> Consider splitting
112+
|
113+
+-- 15-30 total
114+
| +-- Tight coupling between all? --> SINGLE APP (with modules)
115+
| +-- Clear domain boundaries? --> 2-3 APPS
116+
|
117+
+-- > 30 total
118+
| --> ALWAYS SPLIT into multiple apps
119+
| Group by domain/team/release cycle
120+
```
121+
122+
See [references/decision-tree.md](references/decision-tree.md) for the complete decision framework.
123+
124+
## Step 3: Cross-App Dependency Patterns
125+
126+
### required_apps Declaration
127+
128+
ALWAYS declare dependencies explicitly in `hooks.py`:
129+
130+
```python
131+
# myapp/hooks.py
132+
required_apps = ["frappe", "erpnext"] # NEVER omit frappe
133+
```
134+
135+
### Dependency Rules
136+
137+
- NEVER create circular dependencies (App A requires App B requires App A)
138+
- ALWAYS declare ALL dependencies (direct and indirect)
139+
- ALWAYS put shared/base apps first in required_apps
140+
- NEVER depend on a specific version — use compatible APIs only
141+
142+
### Dependency Diagram Pattern
143+
144+
```
145+
frappe (base framework)
146+
└── erpnext (ERP modules)
147+
├── custom_manufacturing (extends Manufacturing)
148+
└── custom_crm (extends CRM)
149+
└── crm_analytics (extends custom_crm)
150+
151+
RULE: Dependencies flow DOWN only. Never up, never sideways.
152+
```
153+
154+
### Cross-App Communication Patterns
155+
156+
| Pattern | Mechanism | Use When |
157+
|---------|-----------|----------|
158+
| **Hook Events** | `doc_events` in hooks.py | App B reacts to App A's documents |
159+
| **Shared DocType** | Link fields to other app's DocTypes | Apps share reference data |
160+
| **API Call** | `frappe.call()` to whitelisted method | Loose coupling between apps |
161+
| **Custom Fields** | `fixtures` with Custom Field | Extend another app's DocType without modifying it |
162+
| **Override** | `extend_doctype_class` (v16) or `doc_events` | Modify another app's behavior |
163+
| **Signals** | `frappe.publish_realtime()` | Real-time notifications between apps |
164+
165+
## Step 4: Data Model Design
166+
167+
### DocType Relationship Types
168+
169+
| Relationship | Implementation | Example |
170+
|-------------|---------------|---------|
171+
| One-to-Many | Child Table DocType | Invoice → Invoice Items |
172+
| Many-to-One | Link field | Invoice → Customer |
173+
| Many-to-Many | Link DocType (intermediary) | Student → Course (via Enrollment) |
174+
| One-to-One | Link field + unique validation | Employee → User |
175+
| Self-referential | Link to same DocType | Employee → Reports To (Employee) |
176+
177+
### Naming Conventions
178+
179+
| Element | Convention | Example |
180+
|---------|-----------|---------|
181+
| App name | lowercase, underscores | `custom_manufacturing` |
182+
| DocType name | Title Case, spaces | `Production Order` |
183+
| Field name | lowercase, underscores | `production_date` |
184+
| Controller | snake_case filename | `production_order.py` |
185+
| Module | Title Case | `Manufacturing` |
186+
187+
### Data Model Rules
188+
189+
- NEVER duplicate data that exists in another DocType — use Link fields
190+
- ALWAYS define autoname/naming_series for every DocType
191+
- ALWAYS add created_by and modified_by awareness (built-in)
192+
- NEVER use Data fields for references — use Link fields
193+
- ALWAYS set mandatory fields for data integrity
194+
- ALWAYS define permissions at DocType level
195+
196+
## App Composition Patterns
197+
198+
### Pattern 1: Base + Vertical
199+
200+
```
201+
base_app (shared DocTypes, utilities)
202+
├── vertical_retail (retail-specific DocTypes)
203+
├── vertical_manufacturing (manufacturing-specific DocTypes)
204+
└── vertical_services (services-specific DocTypes)
205+
```
206+
207+
**Use when**: Building industry-specific solutions on shared foundation.
208+
209+
### Pattern 2: Core + Extensions
210+
211+
```
212+
erpnext (standard ERP)
213+
├── custom_fields_app (Custom Fields only, no DocTypes)
214+
├── custom_reports_app (Script Reports and dashboards)
215+
└── custom_workflows_app (Workflows and automation)
216+
```
217+
218+
**Use when**: Extending ERPNext without modifying core. Keeps upgrades clean.
219+
220+
### Pattern 3: Shared Utilities
221+
222+
```
223+
frappe_utils (shared library: PDF generation, email templates, etc.)
224+
├── app_crm (uses frappe_utils)
225+
├── app_hr (uses frappe_utils)
226+
└── app_projects (uses frappe_utils)
227+
```
228+
229+
**Use when**: Multiple apps need the same utility functions.
230+
231+
### Pattern 4: Marketplace App
232+
233+
```
234+
standalone_app (zero dependencies beyond frappe)
235+
├── Works on any Frappe site
236+
├── Self-contained DocTypes and logic
237+
└── Optional ERPNext integration via hooks
238+
```
239+
240+
**Use when**: Building for distribution/sale on Frappe marketplace.
241+
242+
## ERPNext Extension Patterns
243+
244+
### Custom Fields vs Custom DocTypes vs Override
245+
246+
| Approach | Use When | Pros | Cons |
247+
|----------|----------|------|------|
248+
| **Custom Fields** | Adding 1-10 fields to existing DocType | Survives upgrades, no code | Limited logic, UI clutter |
249+
| **Custom DocType** | New business entity not in ERPNext | Full control, clean design | No built-in ERPNext logic |
250+
| **Controller Override** | Modifying existing ERPNext behavior | Full Python access | Fragile on upgrades |
251+
| **Server Script** | Simple validation/automation | No custom app needed | Sandbox limitations |
252+
| **Client Script** | UI customization | No custom app needed | JS only, no server logic |
253+
254+
### Extension Decision Rules
255+
256+
- ALWAYS prefer Custom Fields for < 10 additional fields
257+
- ALWAYS prefer Server Script for simple validations
258+
- NEVER override ERPNext controllers unless absolutely necessary
259+
- ALWAYS use `extend_doctype_class` (v16) over `doc_events` for overrides
260+
- NEVER modify ERPNext source files directly — ALWAYS use hooks or extensions
261+
262+
## Common Architecture Mistakes
263+
264+
| Mistake | Why It Fails | Correct Approach |
265+
|---------|-------------|-----------------|
266+
| Circular app dependencies | Install/update breaks | Restructure dependency tree |
267+
| One mega-app with 50+ DocTypes | Unmaintainable, slow tests | Split by domain into 3-5 apps |
268+
| Duplicating ERPNext DocTypes | Data inconsistency, double maintenance | Extend with Custom Fields + hooks |
269+
| No `required_apps` declaration | Silent failures on fresh install | ALWAYS declare all dependencies |
270+
| Shared database tables between apps | Tight coupling, migration conflicts | Use Link fields and API calls |
271+
| Modifying ERPNext source files | Lost on every upgrade | Use hooks, Custom Fields, extensions |
272+
| No module organization within app | Files scattered, hard to navigate | Group DocTypes into modules |
273+
| Hardcoded site/company names | Breaks on multi-site/multi-company | Use `frappe.defaults` and filters |
274+
275+
## Agent Output Format
276+
277+
ALWAYS produce architecture output in this format:
278+
279+
```markdown
280+
## Architecture Design
281+
282+
### Requirements Summary
283+
| # | Requirement | DocTypes | Mechanism |
284+
|---|------------|----------|-----------|
285+
286+
### App Structure
287+
[Diagram showing apps and dependencies]
288+
289+
### App Inventory
290+
| App | Module(s) | DocTypes | Dependencies |
291+
|-----|-----------|----------|-------------|
292+
293+
### Data Model
294+
| DocType | App | Key Fields | Relationships |
295+
|---------|-----|------------|---------------|
296+
297+
### Cross-App Communication
298+
| Source App | Target App | Mechanism | Trigger |
299+
|-----------|-----------|-----------|---------|
300+
301+
### ERPNext Extensions
302+
| Extension Type | Target DocType | Purpose |
303+
|---------------|---------------|---------|
304+
305+
### Implementation Roadmap
306+
| Phase | App(s) | Deliverables | Dependencies |
307+
|-------|--------|-------------|-------------|
308+
309+
### Risk Assessment
310+
| Risk | Mitigation |
311+
|------|-----------|
312+
313+
### Referenced Skills
314+
- `frappe-syntax-customapp`: App structure
315+
- `frappe-syntax-hooks`: Hook configuration
316+
- `frappe-syntax-doctypes`: DocType definition
317+
- `frappe-impl-customapp`: App development workflow
318+
```
319+
320+
See [references/decision-tree.md](references/decision-tree.md) for complete decision frameworks.
321+
See [references/examples.md](references/examples.md) for architecture design examples.

0 commit comments

Comments
 (0)