Phoenix Context Boundary Validation
Analyze module dependencies to ensure clean context separation and proper architectural boundaries.
Usage
code
/phx:boundaries # Check for violations /phx:boundaries --assess # Score context health (0-100) /phx:boundaries --fix # Suggest fixes for violations
--assess Mode: Context Health Score
Evaluate overall boundary health with a quantified score.
Metrics Calculated
| Metric | Healthy Range | Red Flag | Weight |
|---|---|---|---|
| Modules per context | 3-15 | >20 or <2 | 20% |
| Public API surface | 5-30 funcs | >40 funcs | 15% |
| Fan-out (contexts called) | 1-4 | >6 | 20% |
| Fan-in (called by contexts) | 1-6 | >10 | 15% |
| Circular dependencies | 0 | >0 | 15% |
| Boundary violations | 0 | >0 | 15% |
Commands for Assessment
bash
# Module count per context for dir in lib/my_app/*/; do echo "$(basename $dir): $(find $dir -name '*.ex' | wc -l) modules" done # Public function count per context for f in lib/my_app/*.ex; do echo "$(basename $f): $(grep -c '^ def ' $f 2>/dev/null || echo 0) public funcs" done # Dependency analysis mix xref graph --format stats # Circular dependencies mix xref graph --format cycles
Output Format
markdown
## Context Health Assessment ### Overall Score: 82/100 (Good) | Context | Modules | API | Fan-Out | Fan-In | Score | |---------|---------|-----|---------|--------|-------| | Accounts | 5 | 12 | 2 | 4 | 95 | | Orders | 18 | 45 | 8 | 3 | 62 | | Shared | 2 | 8 | 0 | 12 | 78 | ### Issues Found 1. **Orders** - Too large (18 modules, 45 funcs) - Consider: Extract Fulfillment, Invoicing sub-contexts 2. **Orders** - High fan-out (8 contexts) - Consider: Review if all dependencies necessary ### Recommendations - Split Orders into Orders + Fulfillment - Review Accounts ← Billing dependency
Iron Laws - Never Violate These
- •Controllers call only contexts - No direct Repo access from web layer
- •Schemas are pure data - No side effects, no Repo calls in schema modules
- •Contexts own their schemas - Don't import schemas from other contexts
- •Explicit dependencies only - Cross-context calls must be intentional
Dependency Rules
| Layer | Can Call | Cannot Call |
|---|---|---|
| Controllers | Contexts, Plug, Conn | Repo, Schemas directly |
| LiveViews | Contexts, Components, PubSub | Repo, Schemas directly |
| Contexts | Own schemas, Repo, other contexts | Web layer modules |
| Schemas | Ecto types, validations | Contexts, Repo |
Analysis Commands
Check Compile Dependencies
bash
mix xref graph --label compile-connected
Find What Depends on a Context
bash
mix xref graph --sink MyApp.Accounts --label compile
Find What a Module Calls
bash
mix xref callers MyApp.Accounts.get_user!/1
Check for Circular Dependencies
bash
mix xref graph --format cycles
Red Flags to Detect
Direct Repo Access from Web Layer
bash
grep -r "Repo\." lib/my_app_web/ --include="*.ex"
If found: Move to context module.
Schema with Queries
bash
grep -r "import Ecto.Query" lib/my_app/**/schemas/ --include="*.ex"
If found: Move queries to context.
Cross-Context Schema Import
bash
grep -r "alias MyApp.OtherContext.Schema" lib/my_app/my_context/
If found: Call other context's API instead.
Business Logic in LiveView
bash
grep -r "Repo\.\|Ecto\.Multi" lib/my_app_web/live/ --include="*.ex"
If found: Extract to context function.
Boundary Verification Process
- •Run
mix xref graph --label compile-connectedfor overview - •Check for context cross-contamination
- •Verify no direct Repo calls from web layer
- •Ensure schemas have no side effects
- •Validate explicit cross-context dependencies
References
For detailed patterns, see:
- •
references/context-design.md- Context design principles - •
references/refactoring-boundaries.md- Fixing boundary violations