Claude Skill

phoenix-contexts

Phoenix context design — creating/splitting contexts, Scope (1.8+), Ecto.Multi,

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download oliver-kriska-claude-elixir-phoenix-targets_amp_skills_phoenix-contexts-9767a82.zip · 11 KB

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/skills/phoenix-contexts
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
Git git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Phoenix Contexts Reference

Ash projects: Ash.Domain replaces Phoenix contexts for data access — use the ash-framework skill. Context boundary and PubSub patterns still apply.

Reference for designing and implementing Phoenix contexts (bounded contexts).

Iron Laws — Never Violate These

  1. CONTEXTS OWN THEIR DATA — Never query another context's schema directly via Repo
  2. SCOPES ARE MANDATORY (Phoenix 1.8+) — Every context function MUST accept scope as first parameter
  3. THIN CONTROLLERS/LIVEVIEWS — Controllers translate HTTP, business logic stays in contexts
  4. NO SIDE EFFECTS IN SCHEMAS — Use Ecto.Multi for transactions with side effects

Context Structure

lib/my_app/
├── accounts/           # Context directory
│   ├── user.ex         # Schema
│   ├── scope.ex        # Scope struct (Phoenix 1.8+)
├── accounts.ex         # Context module (public API)

Phoenix 1.8+ Scopes (CRITICAL)

Context functions take the scope as their first parameter, so queries are filtered to the caller:

def list_posts(%Scope{} = scope) do
  from(p in Post, where: p.user_id == ^scope.user.id)
  |> Repo.all()
end

def create_post(%Scope{} = scope, attrs) do
  %Post{user_id: scope.user.id}
  |> Post.changeset(attrs)
  |> Repo.insert()
  |> broadcast(scope, :created)
end

Quick Decisions

When to SPLIT contexts?

  • Module exceeds ~400 lines
  • Functions don't share domain language
  • Could theoretically be a separate microservice
  • Team member could own it independently

When to KEEP together?

  • Resources share vocabulary and domain concepts
  • Functions frequently operate on same data together
  • Splitting would create excessive cross-context calls

Cross-Context References

# ✅ Reference by ID, convert at boundary
def create_order(%Scope{} = scope, user_id, product_ids) do
  with {:ok, user} <- Accounts.fetch_user(scope, user_id) do
    do_create_order(scope, user.id, product_ids)
  end
end

# ❌ Reaching into other context's internals
alias MyApp.Accounts.User  # Don't do this
Repo.all(from o in Order, join: u in User, ...)  # Don't query other schemas

Anti-patterns

Wrong Right
Service objects (UserCreationService) Context functions (Accounts.create_user/2)
Repository pattern wrapping Repo Repo IS the repository
Direct Repo calls in controllers Delegate to context
Schema callbacks with side effects Use Ecto.Multi

Version Notes

  • Phoenix 1.8+: Uses built-in %Scope{} struct for authorization context
  • Phoenix 1.7: Requires manual authorization context (see references/scopes-auth.md "Pre-Scopes Patterns")

References

For detailed patterns, see:

  • references/context-patterns.md - Full context module, PubSub, Multi, cross-boundary
  • references/scopes-auth.md - Scope struct, multi-tenant, authorization, plugs
  • references/routing-patterns.md - Verified routes, pipelines, API auth
  • references/plug-patterns.md - Function/module plugs, placement, guards
  • references/json-api-patterns.md - JSON controllers, FallbackController, API auth
Files (claude-elixir-phoenix)
  • references
    • context-patterns.md 5.8 KB
      Loading…
    • json-api-patterns.md 4.4 KB
      Loading…
    • plug-patterns.md 3.7 KB
      Loading…
    • routing-patterns.md 2.6 KB
      Loading…
    • scopes-auth.md 7.7 KB
      Loading…
  • SKILL.md 3.3 KB
    ---
    name: phoenix-contexts
    description: Phoenix context design — creating/splitting contexts, Scope (1.8+), Ecto.Multi,
      PubSub, routers, plugs, controllers. Use when editing contexts, routers, or designing
      boundaries.
    ---
    
    # Phoenix Contexts Reference
    
    > **Ash projects**: `Ash.Domain` replaces Phoenix contexts for data access — use the `ash-framework` skill. Context boundary and PubSub patterns still apply.
    
    Reference for designing and implementing Phoenix contexts (bounded contexts).
    
    ## Iron Laws — Never Violate These
    
    1. **CONTEXTS OWN THEIR DATA** — Never query another context's schema directly via Repo
    2. **SCOPES ARE MANDATORY (Phoenix 1.8+)** — Every context function MUST accept scope as first parameter
    3. **THIN CONTROLLERS/LIVEVIEWS** — Controllers translate HTTP, business logic stays in contexts
    4. **NO SIDE EFFECTS IN SCHEMAS** — Use `Ecto.Multi` for transactions with side effects
    
    ## Context Structure
    
    ```
    lib/my_app/
    ├── accounts/           # Context directory
    │   ├── user.ex         # Schema
    │   ├── scope.ex        # Scope struct (Phoenix 1.8+)
    ├── accounts.ex         # Context module (public API)
    ```
    
    ## Phoenix 1.8+ Scopes (CRITICAL)
    
    Context functions take the scope as their first parameter, so queries are filtered to the caller:
    
    ```elixir
    def list_posts(%Scope{} = scope) do
      from(p in Post, where: p.user_id == ^scope.user.id)
      |> Repo.all()
    end
    
    def create_post(%Scope{} = scope, attrs) do
      %Post{user_id: scope.user.id}
      |> Post.changeset(attrs)
      |> Repo.insert()
      |> broadcast(scope, :created)
    end
    ```
    
    ## Quick Decisions
    
    ### When to SPLIT contexts?
    
    - Module exceeds ~400 lines
    - Functions don't share domain language
    - Could theoretically be a separate microservice
    - Team member could own it independently
    
    ### When to KEEP together?
    
    - Resources share vocabulary and domain concepts
    - Functions frequently operate on same data together
    - Splitting would create excessive cross-context calls
    
    ### Cross-Context References
    
    ```elixir
    # ✅ Reference by ID, convert at boundary
    def create_order(%Scope{} = scope, user_id, product_ids) do
      with {:ok, user} <- Accounts.fetch_user(scope, user_id) do
        do_create_order(scope, user.id, product_ids)
      end
    end
    
    # ❌ Reaching into other context's internals
    alias MyApp.Accounts.User  # Don't do this
    Repo.all(from o in Order, join: u in User, ...)  # Don't query other schemas
    ```
    
    ## Anti-patterns
    
    | Wrong | Right |
    |-------|-------|
    | Service objects (`UserCreationService`) | Context functions (`Accounts.create_user/2`) |
    | Repository pattern wrapping Repo | Repo IS the repository |
    | Direct Repo calls in controllers | Delegate to context |
    | Schema callbacks with side effects | Use Ecto.Multi |
    
    ## Version Notes
    
    - **Phoenix 1.8+**: Uses built-in `%Scope{}` struct for authorization context
    - **Phoenix 1.7**: Requires manual authorization context (see `references/scopes-auth.md` "Pre-Scopes Patterns")
    
    ## References
    
    For detailed patterns, see:
    
    - `references/context-patterns.md` - Full context module, PubSub, Multi, cross-boundary
    - `references/scopes-auth.md` - Scope struct, multi-tenant, authorization, plugs
    - `references/routing-patterns.md` - Verified routes, pipelines, API auth
    - `references/plug-patterns.md` - Function/module plugs, placement, guards
    - `references/json-api-patterns.md` - JSON controllers, FallbackController, API auth
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.