🚨🚨🚨 WARNING!! 🚨🚨🚨

• This is a vibe-learning experiment and I would absolutely NOT follow what's in here blindly; a lot of this is straight-up AI slop.
• Over time I hope to clean this up as I learn the fundamentals of the Elixir ecosystem.

Elixir Systems Mastery

A comprehensive Elixir/OTP learning project structured as an umbrella application, covering production-grade systems design from fundamentals to deployment.

🎯 Project Structure

This repository contains two parallel learning tracks:

1. Labs Apps (labs_*)

Isolated, focused mini-apps demonstrating a single concept per phase:

• M0: labs_gatekeeper - Tooling, CI/CD setup
• M1: labs_csv_stats - Pure functions, Stream processing
• M2: labs_mailbox_kv - Processes and mailboxes
• M3: labs_counter_ttl - GenServer + supervision
• M4: labs_session_workers - Registry + DynamicSupervisor
• M5: labs_orders_db - Ecto schemas, Multi, constraints
• M6: labs_orders_web - Phoenix, LiveView, Channels
• M7: labs_ingest - Broadway ingestion / labs_jobs - Oban
• M8: labs_cache - ETS read-through cache
• M9: labs_cluster - libcluster + sharding
• M10: labs_telemetry - OpenTelemetry + Prometheus
• M11: labs_authz_audit - Authorization + audit logging
• M12: labs_release_runner - Mix releases + health checks
• M14: labs_incident_cli - Incident drills CLI

2. Pulse Apps (pulse_*)

An evolving production application built incrementally:

• pulse_core - Pure domain logic
• pulse_cart - GenServer-based shopping cart
• pulse_fleet - Per-user cart workers
• pulse_data - Database layer (Ecto)
• pulse_web - Web interface (Phoenix/LiveView)
• pulse_ingest - Data ingestion (Broadway)
• pulse_jobs - Background jobs (Oban)
• pulse_cache - Caching layer (ETS)
• pulse_cluster - Clustering & sharding
• pulse_obs - Observability & telemetry

🚀 Quick Start

# Install dependencies
make setup

# Run tests
make test

# Start database
make db-up

# Format code
make fmt

📓 Getting Started with Livebook

Interactive learning notebooks are available in livebooks/.

# Install dependencies (includes Kino for Livebook)
mix deps.get

# Start Livebook server
make livebook

# Open your browser to http://localhost:8080
# Navigate to setup.livemd to begin

What's in Livebook?

• Interactive exercises - Run code directly in your browser
• 7 Phase 1 checkpoints - Pattern matching, recursion, Enum/Stream, error handling, property testing, and more
• Progress tracking - Monitor your completion across all 15 phases
• Visualizations - See benchmarks and performance comparisons
• Self-assessments - Check your understanding at each step

See livebooks/README.md for more details.

🤖 AI-Powered Learning with Jido

✅ Fully Functional: The Jido integration uses the real Jido v1.0 framework with LLM-powered AI responses for enhanced learning. See apps/labs_jido_agent/README.md for details.

This repository integrates the Jido AI Agent Framework for enhanced learning:

# Get AI help with Elixir concepts
make jido-ask QUESTION="What is tail recursion?"

# Grade your code with AI review
make jido-grade

# Interactive detailed feedback
make jido-grade-interactive

# Scaffold new projects with best practices
make jido-scaffold TYPE=genserver NAME=Counter PHASE=3

AI Agents Available:

• Code Review Agent - Analyzes code quality, finds issues, suggests improvements
• Study Buddy Agent - Answers questions about Elixir concepts (explain/socratic/example modes)
• Progress Coach Agent - Analyzes learning progress, provides personalized recommendations
• Jido Assistant - Livebook Smart Cell for interactive help while coding

Example Usage:

# Ask a question
mix jido.ask "How do I use pattern matching?"

# Grade your Phase 1 code
mix jido.grade --phase 1 --interactive

# Scaffold a new GenServer project
mix jido.scaffold --type genserver --name UserCache --phase 3 --features ttl,telemetry

See apps/labs_jido_agent/README.md and livebooks/phase-15-ai/ for complete documentation.

📚 Documentation

• Roadmap - Learning phases and milestones
• Reading Notes - Per-phase study notes
• ADRs - Architecture decision records
• Checklists - Design & review checklists
• Runbook - Operations procedures
• SLOs - Service level objectives
• Demos - Example scripts and outputs

🛠️ Tools & Operations

# Load testing
make load        # k6 load tests
make smoke       # k6 smoke tests

# Benchmarking
make bench       # Run Elixir benchmarks

# Cluster operations
make cluster-up  # Start local cluster
make cluster-down

📊 Observability

• Grafana dashboards: observability/grafana/
• OpenTelemetry collector: observability/otel-collector.yaml

🏗️ Development

Each app in apps/ can be developed independently:

cd apps/labs_csv_stats
mix test
mix run

📖 Learning Path

1. Review docs/roadmap.md for the overall learning progression
2. Read phase-specific notes in docs/reading/
3. Implement labs apps to practice isolated concepts
4. Build corresponding features in pulse apps
5. Use checklists for design reviews
6. Write ADRs for architectural decisions

🧪 Testing

# All tests
mix test

# Specific app
cd apps/pulse_web && mix test

# With coverage
mix test --cover

📦 Release

# Build release
MIX_ENV=prod mix release

# Run release
_build/prod/rel/elixir_systems_mastery/bin/elixir_systems_mastery start