Phoenix Framework Coding Standards

Purpose

Progressive disclosure of Phoenix Framework standards for agents writing Phoenix applications.

Authoritative Source: docs/explanation/software-engineering/platform-web/tools/elixir-phoenix/README.md

Usage: Auto-loaded for agents when writing Phoenix Framework code. Provides quick reference to Phoenix contexts, channels, REST APIs, and web patterns.

Foundation: Requires Elixir skill (swe-programming-elixir). Phoenix Framework is built on Elixir/OTP foundations.

Prerequisite Knowledge

CRITICAL: This skill provides OSE Platform Phoenix Framework standards, not Phoenix tutorials.

You MUST complete both Elixir AND Phoenix learning paths:

1. Elixir Foundation (prerequisite for Phoenix):

• Elixir Learning Path - Initial setup, language overview (0-95% coverage)
• Elixir By Example - 75+ annotated code examples
• Elixir In the Field - Production patterns
• Elixir Release Highlights - Elixir 1.12-1.18 features

2. Phoenix Framework Learning Path:

• Phoenix Initial Setup - Environment setup
• Phoenix Overview - Contexts, controllers, views
• Phoenix By Example - 75+ examples
• Phoenix In-the-Field - 30 production guides

Documentation Separation:

• AyoKoding Phoenix - "How to use Phoenix Framework" (educational, universal patterns)
• docs/explanation/elixir-phoenix - "How to use Phoenix in OSE Platform" (repository conventions)

What this skill covers: OSE Platform Phoenix Framework configuration, context patterns, channel usage, REST API design, data access patterns.

What this skill does NOT cover: Phoenix Framework basics, OTP fundamentals (those are in ayokoding-web).

Quick Standards Reference

Context Patterns

• Use contexts to group related functionality
• Keep contexts focused and bounded
• Contexts expose public API, hide implementation
• Use schemas within contexts for data structures

Controllers and Views

• Keep controllers thin, delegate to contexts
• Use action fallback for error handling
• Render JSON with Jason for APIs
• Use Phoenix.HTML helpers for templates

Routing

• Use resources for RESTful routes
• Scope routes by authentication requirements
• Use plugs for request pipeline customization
• Apply rate limiting at router level

Channels and PubSub

• Use channels for real-time bidirectional communication
• Leverage Phoenix.PubSub for process communication
• Implement presence tracking for user activity
• Handle channel errors gracefully

Data Access with Ecto

• Use Ecto schemas for data modeling
• Apply changesets for data validation
• Write composable Ecto queries
• Use Repo for database operations
• Apply database transactions for consistency

REST API Design

• Use JSON:API or GraphQL conventions
• Implement proper HTTP status codes
• Apply authentication with Guardian or Pow
• Version APIs with URL prefixes or headers
• Document APIs with ExDoc

Comprehensive Documentation

For detailed guidance, refer to the 15 Phoenix Framework standards files:

Core Patterns:

• Idioms - Phoenix-specific patterns
• Best Practices - Framework standards
• Anti-Patterns - Common mistakes

Architecture & Configuration:

• Configuration
• Contexts
• Channels

Data & Web:

• Data Access
• REST APIs

Quality & Operations:

• Security
• Testing
• Performance
• Observability
• Deployment

Maintenance:

• Version Migration

Related Skills

• swe-programming-elixir - Elixir language fundamentals (prerequisite)
• docs-applying-content-quality - Content quality standards
• repo-practicing-trunk-based-development - Git workflow

References

• Phoenix Framework README
• Elixir README
• Functional Programming