frappe-project-triage

Frappe Project Triage

Quickly analyze a Frappe project to determine its type, installed apps, version, and available tooling.

When to use

• First step when opening a new Frappe project
• Before making any code changes to understand the codebase
• When debugging to determine which apps/versions are involved
• To identify the development environment (Bench vs Frappe Manager)

Inputs required

• Project root path (where apps/, sites/, or app code lives)
• Access to run shell commands (for version checks)

Procedure

0) Identify project structure

Check for these patterns:

Pattern	Project Type
apps/ + sites/ directories	Bench installation
docker-compose.yml with frappe	Frappe Manager site
pyproject.toml or setup.py with frappe	Standalone app
doctype/ directory	Inside an app module

1) Detect installed apps

# Inside Bench/FM shell
bench --site <site> list-apps

# Or check apps directory
ls apps/

2) Check Frappe version

# Inside Bench/FM shell
bench version

# Or check from Python
bench --site <site> console
>>> frappe.__version__

3) Identify tooling

File/Directory	Tooling
Procfile	Standard bench
docker-compose.yml	Docker/FM
cypress/	UI testing available
.github/workflows/	CI configured
package.json with @frappe/*	JS build tooling

4) Check development mode

# Check site config
bench --site <site> console
>>> frappe.conf.developer_mode

Verification

• Project type identified (bench/FM/standalone app)
• Installed apps listed
• Frappe version known
• Development mode status confirmed
• Available tooling documented

Failure modes / debugging

• No site found: May be inside an app directory, navigate to bench root
• bench command not found: Not in bench environment, use fm shell or activate venv
• Permission errors: Check if running as correct user

Escalation

If project structure is unclear:

1. Look for hooks.py to identify app root
2. Look for sites/common_site_config.json for bench root
3. Check git remote for app repository identification

Output format

After triage, document:

Project Type: [bench|frappe-manager|standalone-app]
Frappe Version: X.Y.Z
Installed Apps: [list]
Developer Mode: [yes|no]
Tooling: [list]
Site Name: <site>

Use this output to route to the appropriate skill:

• DocType work → frappe-doctype-development
• API work → frappe-api-development
• Testing → frappe-testing
• Enterprise patterns → frappe-enterprise-patterns

Guardrails

• Never modify code before completing triage - understand the project first
• Check for custom apps that may override standard behavior
• Verify site exists before running site-specific commands
• Check developer_mode before making schema changes (required for DocType modifications)
• Note Node.js version - frontend builds require compatible Node (typically 18+ for v15)

Common Mistakes

Mistake	Why It Fails	Fix
Running bench migrate without site	Affects wrong/default site	Always use --site sitename
Assuming ERPNext is installed	Import errors, missing DocTypes	Check list-apps output first
Missing FM shell context	bench commands not found	Use fm shell sitename first
Wrong directory level	Commands fail silently	Navigate to bench root (where apps/ exists)
Ignoring custom app overrides	Unexpected behavior	Check hooks.py for overrides
Not checking Python version	Syntax/compatibility errors	Verify Python >= 3.10 for v15+