--- slug: "elixir-architect" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/maxim-ist/elixir-architect@main/README.md" repo: "https://github.com/maxim-ist/elixir-architect" source_file: "README.md" branch: "main" --- # 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) ```bash # 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 ```bash # 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: ```bash # In Claude Code /skills list ``` You should see `elixir-architect` in the list. ## Usage ### Basic Invocation ```bash # 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 ```elixir # ✅ 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 ```elixir # ✅ ALWAYS check version for concurrent updates task |> change(status: new_status) |> optimistic_lock(:version) |> Repo.update() ``` ### Transaction Boundaries ```elixir # ✅ 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](https://github.com/maxim-ist/elixir-architect/tree/HEAD/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`) 3. Make your changes with tests 4. Commit with clear messages (`git commit -m 'Add: improved ADR template'`) 5. Push to your fork (`git push origin feature/amazing-improvement`) 6. Open a Pull Request ### Areas for Improvement - Additional domain adaptations (Healthcare, Logistics, etc.) - More code examples in the skill - Integration with other Claude Code plugins - Community-contributed architecture patterns - Multi-language support (currently Elixir-focused) ## Roadmap ### v1.1 (Planned) - [ ] GraphQL API documentation templates - [ ] LiveView component patterns - [ ] Broadway event streaming examples - [ ] Distributed system patterns (clustering, horde) ### v1.2 (Planned) - [ ] Kubernetes deployment templates - [ ] Observability and monitoring setup - [ ] Load testing scripts and examples - [ ] Migration from Rails/Django guides ### v2.0 (Future) - [ ] Multi-language support (Go, TypeScript) - [ ] Event sourcing pattern library - [ ] CQRS implementation templates - [ ] Microservices architecture option ## Related Skills This skill works well with: - **test-driven-development** - For TDD workflow - **code-review** - For reviewing generated code - **git-workflow** - For managing commits and branches ## Testimonials > "The elixir-architect skill saved us weeks of architecture work. The generated documentation was so comprehensive that our team could start implementing immediately." - *SaaS Startup CTO* > "The Director/Implementor workflow with the guardrails made AI-assisted development actually work at scale. No more architectural drift." - *Platform Engineering Lead* > "Finally, architecture documentation that's actually maintained and useful! The ADRs with alternatives are gold." - *Senior Elixir Engineer* ## FAQ ### Q: Can I use this for umbrella apps? **A:** Yes, just specify "umbrella app" when asked about structure style. The skill will adapt, though Dave Thomas path-based dependencies are recommended by default. ### Q: Does this work for non-financial systems? **A:** Absolutely! While financial systems get special handling (money, audit trails), the skill adapts to any domain: e-commerce, SaaS, messaging, IoT, etc. ### Q: Do I need Director/Implementor AI workflow? **A:** No, it's optional. If you answer "no" to that question, the skill still creates complete architecture docs without the AI collaboration guardrails. ### Q: Can I customize the generated documentation? **A:** Yes! All documentation is Markdown, fully editable. Treat the generated files as a starting point and adapt to your needs. ### Q: What if my project uses different tech stack? **A:** The skill is optimized for Elixir + Ash + Oban + Phoenix but can adapt. Specify your preferences when asked, and the skill will adjust recommendations. ### Q: How often should ADRs be reviewed? **A:** The skill sets review schedules (typically 6 months), but review ADRs whenever: - Performance becomes a bottleneck - Scale significantly changes - New technologies emerge - Team composition changes ## License MIT License - See [LICENSE](https://github.com/maxim-ist/elixir-architect/tree/HEAD/LICENSE) file for details. ## Support - **Issues**: [GitHub Issues](https://github.com/maxim-ist/elixir-architect/issues) - **Discussions**: [GitHub Discussions](https://github.com/maxim-ist/elixir-architect/discussions) - **Email**: [Your contact email] ## Acknowledgments This skill incorporates wisdom and patterns from: - **Dave Thomas** - Multi-app structure and path-based dependencies - **Saša Jurić** - OTP patterns and "database as source of truth" - **José Valim** - Elixir philosophy and GenStage patterns - **Zach Daniel** - Ash Framework patterns and best practices - **Superpowers Framework** - Implementation planning format ## Version **Current Version**: 1.0.0 **Release Date**: 2024-01-11 **Compatibility**: Claude Code 1.0+ --- **Built with ❤️ by the Elixir community** _Creating production-ready architectures, one documentation package at a time._