elixir-architect

Elixir Architect

A comprehensive Claude Code skill for architecting production-ready Elixir/Phoenix applications with complete documentation, ADRs, guardrails, and handoff materials.

Overview

Elixir Architect is a Claude Code skill that acts as an expert system architect, creating comprehensive project documentation packages that enable Director and Implementor AI agents to successfully build complex Elixir/OTP systems following industry best practices.

This skill creates:

• ✅ Complete directory structure for multi-app projects
• ✅ Architecture documentation (8 comprehensive files)
• ✅ Architecture Decision Records (ADRs)
• ✅ AI collaboration guardrails (Director/Implementor roles)
• ✅ Handoff documentation with workflows
• ✅ Domain-specific adaptations (Financial, E-Commerce, SaaS)

Key Features

Expert Consultation

Automatically launches Task agents to research:

• Domain-specific architecture patterns
• Ash Framework best practices
• Dave Thomas's path-based dependency approach
• OTP supervision tree patterns
• Superpowers framework for implementation planning

Comprehensive Documentation

Generates 20+ documentation files including:

• Foundation: README.md, CLAUDE.md with AI context
• Architecture: 8 detailed architecture documents (~6,000 lines)
• Guardrails: NEVER_DO, ALWAYS_DO, role definitions, review checklist
• Decisions: ADRs with alternatives and trade-offs
• Handoff: Complete workflow for Director/Implementor collaboration

Domain-Specific Adaptations

Special handling for:

• Financial Systems: Double-entry bookkeeping, money handling, audit trails
• E-Commerce: Order workflows, inventory, payment integration
• SaaS Platforms: Multi-tenancy, subscriptions, usage tracking

Proven Architectural Patterns

• Database as source of truth (no GenServers for entities)
• Functional core, imperative shell pattern
• Dave Thomas multi-app structure (path-based dependencies)
• Ash Framework for declarative domain modeling
• Oban for background job processing
• Optimistic locking for concurrency

Installation

Method 1: Claude Code Plugin (Recommended)

# In Claude Code, run:
/plugin install github.com/maxim-ist/elixir-architect

The skill will be automatically available as elixir-architect.

Method 2: Manual Installation

# Clone the repository
git clone https://github.com/maxim-ist/elixir-architect.git

# Copy skill to Claude Code skills directory
mkdir -p ~/.claude/skills
cp -r elixir-architect/skills/elixir-architect ~/.claude/skills/

Verification

To verify the skill is installed:

# In Claude Code
/skills list

You should see elixir-architect in the list.

Usage

Basic Invocation

# In Claude Code
/skills elixir-architect

Or simply describe your need:

I need to architect a task management system using Elixir, Ash, and Oban with
complete documentation for Director and Implementor AI collaboration

Claude will automatically invoke the skill if appropriate.

The Skill Will Ask You

The skill gathers requirements through these questions:

1. Project Domain: What system are you building? (e.g., task management, e-commerce, SaaS)
2. Tech Stack: Confirm Elixir + Ash + Oban + Phoenix + LiveView?
3. Project Location: Where to create files? (provide absolute path)
4. Structure Style: Dave Thomas path-based or umbrella app?
5. Special Requirements: Multi-tenancy? Event sourcing? External integrations?
6. Scale Targets: Expected load and performance requirements
7. AI Collaboration: Using Director/Implementor workflow?

Example Session

User: Create architecture docs for a task management system at /Users/me/projects/taskflow

Claude: [Invokes elixir-architect skill]

Skill: I'll help architect your task management system. Let me gather some details:

1. Confirm tech stack: Elixir 1.17+, Ash 3.0+, Oban 2.17+, Phoenix 1.7+?
2. Structure: Dave Thomas path-based dependencies?
3. Special requirements:
   - Multi-tenancy (teams/organizations)?
   - Real-time features (LiveView task boards)?
   - Expected user volume and task creation rate?
4. Will you use Director/Implementor AI workflow?

[After answering questions, skill launches expert Task agents]

Skill: Researching task management patterns and state machines...
      Analyzing Ash Framework resource patterns...
      Studying Dave Thomas multi-app structure...

[Creates complete documentation package]

Skill: ✅ Project architecture complete!

Created 23 files at /Users/me/projects/taskflow:
- Foundation docs (README, CLAUDE.md)
- 5 guardrail documents
- 8 architecture documents
- 4 Architecture Decision Records
- Handoff documentation

Ready for Director AI to create first feature design!

What Gets Created

The skill generates this structure at your specified location:

project_root/
├── README.md                      # Project overview
├── CLAUDE.md                      # Complete AI agent context
├── docs/
│   ├── HANDOFF.md                # Director/Implementor workflow
│   ├── architecture/             # 8 comprehensive architecture docs
│   │   ├── 00_SYSTEM_OVERVIEW.md
│   │   ├── 01_DOMAIN_MODEL.md
│   │   ├── 02_DATA_LAYER.md
│   │   ├── 03_FUNCTIONAL_CORE.md
│   │   ├── 04_BOUNDARIES.md
│   │   ├── 05_LIFECYCLE.md
│   │   ├── 06_WORKERS.md
│   │   └── 07_INTEGRATION_PATTERNS.md
│   ├── design/                   # Empty - Director fills during features
│   ├── plans/                    # Empty - Director creates Superpowers plans
│   ├── api/                      # Empty - Director documents APIs
│   ├── decisions/                # Architecture Decision Records
│   │   ├── ADR-001-framework-choice.md
│   │   ├── ADR-002-id-strategy.md
│   │   ├── ADR-003-process-architecture.md
│   │   └── [domain-specific ADRs]
│   └── guardrails/              # AI collaboration rules
│       ├── NEVER_DO.md          # Critical prohibitions
│       ├── ALWAYS_DO.md         # Mandatory practices
│       ├── DIRECTOR_ROLE.md     # Architect AI role definition
│       ├── IMPLEMENTOR_ROLE.md  # Coder AI role definition
│       └── CODE_REVIEW_CHECKLIST.md

Documentation Highlights

NEVER_DO.md

10 critical prohibitions with code examples:

• Never use floats for money (use integer cents or Decimal)
• Never update balances without version check (optimistic locking)
• Never create GenServers for domain entities (database as source of truth)
• Never allow partial transaction commits (use Ecto.Multi)
• And 6 more with detailed rationale

ALWAYS_DO.md

22 mandatory practices across:

• Data integrity (transactions, events, audit trails)
• Testing (TDD, edge cases, property tests)
• Code quality (typespecs, documentation, formatting)
• Architecture (separation of concerns, async workers)

Architecture Documents

Each of the 8 architecture files includes:

• Complete explanations with context
• Concrete code examples (valid Elixir)
• ASCII diagrams where helpful
• Performance considerations
• Testing patterns
• Common mistakes and corrections

ADRs (Architecture Decision Records)

Each ADR documents:

• The decision made
• Context and rationale
• Alternatives considered with pros/cons
• Why alternatives were rejected
• Implementation guidelines with DO/DON'T examples
• Validation criteria
• Review schedule

Use Cases

Task Management Systems

Perfect for:

• Project management platforms
• Issue tracking systems
• Kanban/Scrum boards
• Team collaboration tools
• Workflow management

Special handling:

• State machine enforcement
• Priority calculations
• Dependency management
• Real-time updates (LiveView)
• Notification workflows

Financial Systems

Perfect for:

• Double-entry ledgers
• Payment platforms
• Commission calculation systems
• Multi-currency accounts
• Audit trail requirements

Special handling:

• Money handling (never floats!)
• Balance integrity validation
• Two-phase transactions
• Optimistic locking patterns

E-Commerce Platforms

Perfect for:

• Order management systems
• Inventory tracking
• Payment processing
• Shipping integration
• Customer accounts

Special handling:

• Order state machines
• Inventory reservation
• Payment gateway integration
• Refund workflows

SaaS Applications

Perfect for:

• Multi-tenant platforms
• Subscription billing
• Usage metering
• Feature management
• API platforms

Special handling:

• Tenant isolation strategies
• Row-level security
• Usage tracking patterns
• Plan limit enforcement

Director/Implementor Workflow

One of the unique features of this skill is creating documentation that enables a two-AI workflow:

Director AI (Architect)

• Creates feature designs
• Makes architectural decisions
• Writes implementation plans (Superpowers format)
• Reviews code against design
• Maintains architectural consistency

Implementor AI (Coder)

• Executes implementation plans
• Writes tests first (TDD)
• Implements features
• Reports progress and blockers
• Maintains code quality

Workflow Cycle

1. Director: Creates design + plan → commits
2. Implementor: Executes plan (TDD) → commits
3. Director: Reviews implementation → approves or requests changes
4. Repeat: Until feature complete

The generated HANDOFF.md provides complete workflow documentation with message templates and communication protocols.

Architectural Principles

The skill enforces these proven principles:

1. Database as Source of Truth

• No GenServers for domain entities (Task, Project, User, etc.)
• State persists in PostgreSQL, not process memory
• Optimistic locking for concurrent updates
• Simple recovery: just query the database

2. Functional Core, Imperative Shell

• Pure business logic in impl/ layer (no side effects)
• Side effects (DB, HTTP) in boundaries layer
• Easy to test, easy to reason about
• Clear separation of concerns

3. Async for External Calls

• Never block request path with external API calls
• Enqueue Oban jobs for notifications, webhooks, integrations
• Circuit breakers for failing services
• Idempotency keys for retry safety

4. Let It Crash (OTP Philosophy)

• Supervision trees for fault tolerance
• GenServers for infrastructure (not entities)
• Processes isolated, failures contained
• Self-healing systems

5. Test-Driven Development

• Write tests first (red → green → refactor)
• Unit tests for pure functions (impl/ layer)
• Integration tests for boundaries
• Property tests for invariants

Performance Targets

The skill includes realistic performance targets in documentation:

• Task Queries: <50ms (p95), <100ms (p99)
• Task Updates: <200ms (p95), <500ms (p99)
• Throughput: 1,000+ operations/second sustained
• Test Coverage: >90% for core logic, >80% for boundaries

Best Practices Codified

State Machine Validation

# ✅ ALWAYS validate transitions
def can_transition?(from_status, to_status) do
  valid_transitions = %{
    todo: [:in_progress, :blocked],
    in_progress: [:blocked, :review, :done],
    review: [:in_progress, :done]
  }

  to_status in Map.get(valid_transitions, from_status, [])
end

Optimistic Locking

# ✅ ALWAYS check version for concurrent updates
task
|> change(status: new_status)
|> optimistic_lock(:version)
|> Repo.update()

Transaction Boundaries

# ✅ ALWAYS use Multi
Multi.new()
|> Multi.insert(:record, changeset)
|> Multi.run(:side_effect, fn _, %{record: r} -> side_effect(r) end)
|> Repo.transaction()

Examples

See the examples directory for:

• Complete supervisor tree example
• GenServer infrastructure template
• Ash Resource with optimistic locking and state machines
• Oban worker with retries and notifications
• Property test for state transition validation

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-improvement)