Whether you’re improving your existing AI toolkit, or you’re proving the value of AI for your company, if you’ve got PDFs as part of the input data, I expect this will be valuable.

tl;dr

As of July 2025, the best way to analyze a PDF is via Anthropic’s API. Crazy easy, 1 API call, base64 PDF data and your prompt. The accuracy is fantastic, and it’s hilarious to compare the results of trying the same thing with openai. I had a hard time finding conclusions like this outside of forum posts, so hopefully this is useful to you for the next 6 months while it remains true ☺️.

If you need a reason to trust my opinion, or you’re curious, read on…

How I got here

More than a year ago I started a project to introduce our first AI driven feature and after a lot of testing, research into AI APIs, and research into our business problems, I decided on extracting structured data from PDFs. TL;DR from then, I needed to prove the ROI as clearly as possible and as the first person putting my neck out I was extremely focused on making it as small a slice as possible. At the time, you could put a PDF into chatgpt and it would be okay usually, and you could put a PDF into the API and it would be bad.

Example PDF with a chunk of a scanned form that’s been copied and is misaligned on the page. Reading Forms = $$

I ran experiments with every foundation model, extracting PDF content locally (PDFMiner, etc.) and pushing raw text as part of the prompt, I tried providers like AWS Textract, and Unstract (note: I actually thought their service was quite nice), and had a range of results. I was swimming in Google colab docs trying all of this. Ultimately, the strategy that yielded the best results, and fit my cost+time constraints was cumbersome, but effective. In November 2024, I would’ve recommended cutting the PDF by page, and converting each page to a jpeg, and then uploading those as files with the prompt. The multi-modal models at the time did a pretty excellent job with images and text, as well as getting the benefit of identifying images by page number in the responses. This is all to say, I spent a lot of time making that decision, and we did ship a production, profitable, compelling product that opened the door for more AI projects.

I’ve moved companies since then and we come across a somewhat similar usecase (funny enough it’s also driven by how confusing insurance can be) and I needed to refresh myself on that research. In November 2024, Anthropic had a beta feature to ease PDF analysis by basically doing the same PDF->Image process behind the scenes for you, but I didn’t have the bureaucratic temperament or time to get us approval for anthropic. Since then, it seems like that has gone GA and wow. Life. Is. Good.

What took me weeks for a PoC, and months to get it in production (not a fault of the tech), took me a week this time and roughly 1 day to be happy with the accuracy of the AI analysis.

Why It Matters

• PDFs are everywhere: policies, contracts, intake forms.
• PDFs are also bullshit: structured PDF documents, word docs as PDF, PDFs of scanned images of printed forms, it’s all “PDF”.
• Sometimes a hammer is the right tool: We give-up on deterministically converting PDF structure to text reliably and just analyze the image.

Vendor specific without lock in

As much as I’m an Anthropic fanboy, Anthropic did us a really nice favor by making this feature completely transparent. You don’t need to use a special API endpoint, you don’t need to upload the file to their magic assistant API before using it in your prompt, it’s just a single normal API call. If another provider offers a better solution, you won’t be boxed in. The curl PDF example they give is really what you want. We use Elixir, and converting the curl command to a Req request is so easy, no provider client needed or AI framework, it’s just a web request.

Don’t take it from me, here’s an example

It’s easy to test and confirm that Anthropic is the best with PDFs, not only because the quality of life is so much better (see example code), but the quality of the results is there too. Credit to: Anthropic PDF Support | You can download the sample image as a PDF here.

The PDF was ~2k input tokens, claude-sonnet-4-20250514 is $3.75/Mtokens, so we are looking at just under 1 cent(~$0.0075).

base64 -i pdfSample.pdf | tr -d '\n' > pdf_base64.txt

# Create a JSON request file using the pdf_base64.txt content
jq -n --rawfile PDF_BASE64 pdf_base64.txt '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [{
            "type": "document",
            "source": {
                "type": "base64",
                "media_type": "application/pdf",
                "data": $PDF_BASE64
            }
        },
        {
            "type": "text",
            "text": "Give me a 1 sentence answer or less, what is a revenue value from this document?"
        }]
    }]
}' > request.json

# Send the API request using the JSON file
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @request.json

Bonus

Try converting a weird scanned form today and see if Claude can beat your current stack. It’s genuinely as easy as it looks.

To my AI first thinkers, the Anthropic docs even have a button to get the page as markdown. I usually give the URL to claude code and let it scrape however it wants, but if you’re building a local doc center for stuff like this, you can just give the docs to your AI of choice and ask for an implementation in your language and code style.

Image of the Anthropic docs header, including a “copy” button with dropdown for format of copy for LLM convenience

In my Cursor post, I demonstrated how I utilized a verification script to assist Claude Code in verifying its work. However, until recently, UI changes still required me to manually run the server and take screenshots, which I would then share with Cursor along with feedback. Note that this was still a significant improvement, as it could now perform the design UI iteration with screenshots.

I’ve been MCP¹ curious, but I had not, until now, seen a valuable practical application. Enter Puppeteer. With a Puppeteer MCP, Claude Code can drive the browser. The agent can navigate, interact, and take screenshots without requiring my intervention. What’s significant here is that there’s now one fewer step where I am the bottleneck. Claude can self-review and provide a visual critique, which will then improve before I have to evaluate it manually.

Top: My previous workflow, Claude can self-iterate via automated tests. Bottom: Current workflow, Claude can self-iterate via tests, and UI QA via Puppeteer. Saving me a step in the process

Part of my inspiration for this was an article about Programming with Agents, because it illustrated the importance of enabling feedback and even how a simple bash tool is enough to unlock a massive boost in LLM capability. Now to the meat.

Let’s build a custom Phoenix 404

I love the playful 404 pages, like GitHub’s 404. I’ve always wanted to add one to my apps, but the combo of limited artistic ability, time, and it never feeling like a priority prevented me from making one.

Exploring MCP finally gave me the right opportunity. You can try this out in less than an hour. Setting up Puppeteer via NPX was a mix of super simple and, as a result, extremely confusing when it wasn’t working. It’s just one configuration², and it should run. This project is essentially design-driven; it’s a public route with no interactivity, providing a perfect example to focus on tooling.

Left: Mock made by ChatGPT | Center: First attempt from Claude | Right: Finished product

Start with a target UX

I brainstormed ideas with ChatGPT and generated an image I liked. You can see it above; ideally, Claude Code can do this for me one day as well. (This took a couple of turns to refine my idea and tweak the design language and art) I gave it info on our business, the tone I was looking for, the thematic style, how I wanted users to feel (calm), and what they might already be feeling (stressed, frustrated, exasperated, desperate).

Implement with Claude & Puppeteer

I started a Claude Code session with my design file in my repo and directions that were not clear enough, eventually landing on quite structured instructions and a link to the Phoenix custom error docs. Claude nailed the normal coding challenges, getting a custom error page working in its first prompt and making a nice automated test. This is a huge improvement from the past because it can so effectively read the doc link I provided. It even taught me how they work (skipping the “layout” work that pages use and containing the body and layout in the HTML).

I eventually got good results and an effective self-review by asking for these steps to be followed:

use puppeteer to visit a specific route /nonsense, take a screenshot, compare that screenshot to the design file, make notes of each difference between the images, address the top 3 differences, repeat until the browser looks reasonably close to the design and would provide a nice user experience.

This took a couple of turns as I realized what I was looking for and gave some specific feedback for responsive design, which did a great job with different resolutions.

I got a 404 I was happy with, and I didn’t code.

The agent ran the loop: code -> browser -> screenshot -> compare -> repeat. I only nudged it when needed. Phoenix made it easy to wire up, especially by including the docs URL in my instructions. The main point I want to convey is that we’re no longer simply generating code with the agent. Instead, the agent now actively participates in development activities. Generating code is just one of its functions, rather than a peripheral tool I use for development. Each piece like this, where I can get out of the loop, brings us closer to the agent-based future.

Bonus: I read a similar article on Agentic Coding, but with a huge emphasis on the speed of your iteration tools. If you’re already getting success from things like I mentioned above, this article will take it a step further. This assumes that your AI tooling needs to be able to evaluate its work and revise it; the next goal is then to make that feedback as fast as possible.

If you’ve been working on your AI workflow, I’d love to hear about it and share ideas. I’m still not entirely convinced that MCPs hold significant value for me right now, but I’m starting to see their potential.

Footnotes:

¹ MCP is a standard defined by Anthropic to enable “plug and play” tool sets for things like Computer use, or the Sentry API, etc. Ideally, you can share code that’s like an SDK for an Agent to use.

²

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

Praise the editor: Sam Roberts

It’s a natural follow-up to our scaffolding with Claude Code, and a powerful tool for targeted improvements. Check out AI Architecture and Scaffolding with Claude Code in the AI development Mindset: Coach series. We continue from our scaffolding the project with help from Claude Code.

UI Edits with Screenshots

Cursor’s multi-modal capabilities are extremely undervalued. Screenshots help your coworkers understand what you’re aiming for, and Cursor is no exception! Here’s my typical workflow:

1. Take a screenshot of the current app
2. Take a screenshot of the design
3. Prompt with specific changes:

   “Make the app look more like the design. Flatten the form header, move the input to the left, and use the brand color for the background.”

I iterate with more screenshots and feedback:

Refactoring and Test Updates

Cursor’s also great for test updates and refactoring. I often ask:

“Make @this_test.exs work like @my_gold_standard_test.exs. Share test setup. Reduce file length, keep coverage.”

Just like UI edits, focused prompts and examples help. When context matters (e.g., not using Mox in Elixir tests), Cursor Rules let you inject project-specific instructions. If you want a deep dive, this article (You are using Cursor AI incorrectly…) and this case study were really impactful to me.

The Review Process

As with Claude Code, I review each diff like a PR. Feedback goes directly into the prompt. I stage the changes I like. I commit once a full thought is resolved. Cursor’s addition is the ability to reference Rules, and Notebooks where you can store extra context and even directly reference functions by starting to type @function_name and it will auto suggest as you type.

Knowing When to Stop

Eventually, you’ll hit the wall: if the change is small, tedious, or personal-style-based, stop asking AI and do it yourself. There are diminishing returns as code changes get smaller. More specific changes need more description and start changing fewer and fewer lines, you will cross a point where you need to type more than the the changes that you know how to code.

Stop when your explanations are getting longer and changes are getting smaller.

Heuristics for Success

1. Use Visual Context
   • Screenshots are worth a thousand words
   • Show before and after states
   • Reference existing patterns
2. Keep Prompts Focused
   • One change at a time (I cheat with numbered lists)
   • Be specific about what to change
   • Reference existing code
3. Know Your Limits
   • Stop when prompts get too long
   • Switch to manual changes for small tweaks
   • Use AI for what it’s good at (css)

The Bottom Line

Cursor shines when you need to turn good-enough code into nearly-production-ready polish—without writing every line yourself. It’s uniquely powerful for UI work with images. and test refinement for UI, where visual context and pattern matching are key. If you liked this series, send word! I’m excited to share more if it’s valuable to folks out there (or future me as well).

Praise the editor: Sam Roberts

This is a follow-up to better explain my approach to using AI coding tools in AI development Mindset: Coach. This is how I start projects that are big enough to warrant atleast a 15 minute planning session before starting. I have scripts that I use to handle the rote work described here, but it’s really important to talk through (and experience) it first hand to help you build up your own tools. I found this article by Manuel Kießling, Senior Developer Skills in the AI Age: Leveraging Experience for Better Results really similar to how I see a lot of this work and wanted to show what it looks like for my work.

The Prompt Template

Every session starts with the same context structure:

1. Business Context: What does our business do?
2. App Purpose: What does our app do?
3. New Problem: What are we trying to solve and for who?
4. Desired Outcome: What does success look like?

Prompt by explaining the business context first. Then define outputs and guardrails.

The PLAN.md Structure

I have Claude turn this context into a PLAN.md file that includes:

1. A restatement of the context, problem statement, and outcome
2. A milestone breakdown, where each milestone includes:
   • A testable unit of work
   • An automated test to prove it’s done

If I already have architectural ideas, I include them. If not, I’ll ask for three architecture options—always including one wild-card idea to stretch creativity—before moving to the milestone plan. I use Claude Code Custom Slash Commands for this, where I have a template plan file including the business context and a real sample project that we did and it was the fully completed PLAN doc that I ended with. You can checkout an example of mine in this gist.

The Development Loop

Once the plan looks good, I give it the go-ahead.

Start on milestone 1. Use TDD. Update the PLAN.md with progress. And always run the verify.sh script after changes to be sure everything is working.

It’s important to note that the biggest boost we are unlocking allows Claude Code to make changes, fix them, and continue on it’s own until the whole plan is complete, running completely autonomously with no additional input from me for ~5-8 minutes. The plan needs to be clear and the feedback script - verify.sh, just all of our deterministic testing/linting/even dev server, is so fast and easy that CC can self-iterate accurately and with clear next steps.. This is the Critical Victory that I’ve seen from CC that Cursor can’t match yet.

When the first diff is ready, I treat it like a PR. I review each file and leave feedback in the prompt as a numbered list. I expect working, test-passing code after 1–2 rounds and hitting that or not is a reflection on my ability to prompt.

> 1. File A duplicates File B—centralize that logic.
2. Rename ActionItem to NextSteps, and update tests and callers.
3. Use an adapter pattern around the HTTP client—see File D for reference.
4. Refactor UI code to match patterns from File E.

Managing Changes

I stage diffs as I go—if something’s mostly right, I keep it but haven’t committed yet. That way, I can trace each “chain of thought” to 1 commit, and incremental improvements of that commit are managed through staged diffs. Typically, I get 1–2 commits from this stage. Sometimes I don’t like the changes it makes, which is why I rely on staging to avoid losing anything useful. I drop the incoming changes, and provide the same review with the added context that it was wrong and I removed the changes. You can use anything to solve this, I just find the diff view of staged changes versus unstaged to be the easiest to compare.

When to Use Claude Code

Claude Code is much slower and more expensive than the Cursor Agent. Even the simplest task will take minutes, not seconds. I often complete a project that’s reasonably big ~2-3 PRs and spend $5 to $10. Personally, if this speeds me up 10%, it’s easily worth the cost, and I’ll multi-task while claude works (🙊). Only accept this overhead while you’re making broad or complex changes. Stop when the structure and relationship between files is where you want it, even if you have specific code changes you still want to implement.

Time Expectations

For a typical feature, I budget:

• 15m of context + planning
• 30–60m of architecture + initial build
• 30m of refinement (next post)
• 15m of self-review + polish

The reward isn’t just speed—it’s focus. I get to spend more time making thoughtful decisions and typing boilerplate less. Claude Code takes minutes, not seconds, so I use that to explore a separate change in parallel, read docs, or continue designing the next change. The fundamental change is that I am able to keep my perspective on the level of architecture and code organization more, and implementation less. Next up, I’ll walk through what I do after Claude Code, where I really like the Cursor Agent.

Praise the editor: Sam Roberts

Over the past year, I have transitioned from self-exploration of AI to building an AI adoption plan for a team of 30 engineers and now back to solo daily use of AI. My opinion on what AI offers and how I interact with it has changed dramatically. A change in perspective about collaborating with AI enables the most significant productivity gains.

Treat AI Like a New Engineer

My most significant improvement in my dev workflow with AI has come from a mindset shift: My AI is a superhuman engineer with zero awareness. A fast, tireless contractor who knows everything except my business, users, and codebase. They just showed up, and I need to manage them.

If you wouldn’t expect a brand-new dev to succeed without context, you shouldn’t expect it from your AI.

You don’t have to use AI, just like you don’t have to use a new engineer on every project. But if you do, your job is to provide an environment where it can thrive—and to recognize when a task isn’t a fit. AI shines with a clear, broad context, a strong feedback loop, and a well-defined goal.

📝 Aside: Be real about what AI is

AI is not magic. That said, it’s not a person, and you need to handle some limitations. It’s extremely fast, absurdly knowledgeable, has no business awareness, memory limited to the length of your session, and only “sees” your code base in slivers at a time. That’s not a knock—it’s just the job description. Accept its strengths and weaknesses, and it can do fantastic work. In general, let your guiding principle be “treat AI like a new engineer,” and be aware of tactics to work within its limitations.

Tactical Advice for Working with AI

1. Provide Clear Context
   • What does your business do, and why does this problem matter?
   • Define clear goals and outcomes
   • Set explicit boundaries and constraints
2. Review Like a PR
   • Give specific, actionable feedback
   • Iterate on changes systematically
   • You’re a coach, not a mentor, tell it what to do
3. Know When Not to Use AI
   • Simple tasks that you already know and can complete as fast as you can type
   • Minor changes very specific to your code base
   • When the change depends on specific data (bug with a specific user in your logs)

# bad
> "make this controller able to accept a PUT request"

# good - and ideally mostly automatically added
> "Our Customer Service business has an opportunity to accept incoming updates from MegaCorp. 
If we can accept their requests we can save users hours. Their documentation is at mega-corp.net/docs (Tell me if you can't read them)
they will be sending us the Money object via a PUT request, and @nice-example.code is a file that does something similar, implement it like that.
Be sure to use TDD practices and run the @verify script after everychange before you tell me it's done.
"

If that example seems long, you’re right. This makes a difference, and it’s why I script the bulk of that context. AND there comes a point where you will absolutely have diminishing returns because thorough input is so valuable; the result needs to be high value to be worth it.

The Bottom Line

AI shines with a clear, broad context, a strong feedback loop, and a well-defined goal. I talked about this as it related to Elixir in my last post Elixir’s Advantage in the Era of AI. I’ve seen some great results so far, and the mindset is what leads to creating the best prompts and the proper context. I will explore using Claude Code for scaffolding and Cursor for polish soon. Stay tuned!

I’m also experimenting with using Substack to provide a newsletter. Let me know if you have any thoughts, and subscribe to get these pushed directly to your HUD contact lenses.

Aaron on the Sylverstudios Substack

Praise the editors: Sam Roberts & Dan Janowski

I’ve been deep in AI dev tooling for about 10 months, and I’m now fully bought in on the future of AI-assisted development. Tools like Cursor and Claude Code 🚀 are no longer just autocomplete—they can self-iterate. They’ll run tests, interpret failures, revise code without my intervention, and do it until everything works.

And the more structured feedback you feed these tools—errors, types, docs, tests—the better they perform. We want to make each iteration as fast and accurate as possible. That’s where Elixir quietly shines.

Despite being a small slice of training data, Elixir is uniquely well-positioned to thrive in this new model. It has three traits that stack up beautifully for AI pair programming: First-Class Documentation, Functional + Compiled Design, and a Deeply Integrated Testing Model (thanks, BEAM).

1. First-Class Documentation: Context Built into the Code

Elixir treats documentation as a first-class citizen. Every function and module has structured, built-in documentation next to the code. It’s not just scattered comments—it’s compiled, queryable, and often includes real usage examples through doctests. That can be run and updated by our AI!

This is a goldmine for LLMs. Instead of guessing how a function works, AI tools can read structured descriptions, see example inputs/outputs, and even run the embedded tests. This means fewer hallucinations, better API usage, and more accurate code. Elixir isn’t alone in great doc support, but it compounds the benefits with these other features.

2. Functional & Compiled: Predictable, Debuggable, and AI-Friendly

Grouping these may be cheating, but any functional, compiled language has an edge for AI. Functional code is more straightforward for people to reason about because you should only need the context of the function you are in. No side effects on variables outside the scope, no class variables to chase down, and the AI’s context window thanks you. Elixir is not alone here, either, but the combination with #1 narrows the field significantly

Elixir is compiled, which means AI tools (and developers) get immediate, structured feedback before your code runs, pointing out exactly what’s wrong. As a minor bonus, Elixir’s Gradual Set-Theoretic Types are closing the gap to static compiled and strongly typed languages. Instead of failing silently at runtime, compilation errors tell you exactly where the problem is—which is as helpful for an AI refactoring code as it is for a human. This keeps the iteration loop for the AI tight and efficient because it will be more likely to make the correct change after an error than to receive a message like null is not an object.

3. Elixir, Best Tests in the West 👈🤠👉

One of Elixir’s biggest strengths is how deeply its testing framework integrates with real application behavior. This has a caveat, if you are using a frontend framework for an SPA, you lose some of this benefit. Because Elixir is Erlang running on the BEAM (Bogdan/Björn’s Erlang Abstract Machine), we can run your entire application as a collection of processes and interact with it from “outside.” The side bonus of being able to run most tests concurrently is a spooky fast feedback loop. I’m using Phoenix Liveview and avoiding an SPA for now, which means I can also get UI tests that run the whole application, and trigger UI events on button clicks or navigation links. I’ve never been a fan of full integration tests—too much setup and maintenance, and they still miss things. But now, the cost has gone down with AI writing and maintaining tests while the value has gone up because the same AI can benefit from the feedback that used to require manual aid.

That means AI tools can:

• Interact with the full app—API, UI, and DB—in native tests.
• Get structured failures and iterate without manual debugging.
• Build and maintain integration and UI tests.

AI has changed how I see Elixir

My experience using LLMs with Elixir—especially Cursor and Claude Code—has been incredible. I will give lots of context on the situation, ask to start by making a TODO.md implementation plan that includes the tests in TDD style, and let the agent build features, run the suite, and iterate until it’s done. Elixir isn’t the only language with these capabilities, but the combination of clear docs, fast compiler feedback, and integrated testing makes it uniquely effective. It has been a delight to work with it and build enough context for it to navigate my code like a seasoned young engineer.

That’s not a future I’m waiting for—it’s already here.

I’m betting on the future of AI-driven development. JS and Python devs may have a head start, but I don’t think they ride the best horse. Elixir has the right DNA—and our way forward is to create, share, and lead with great code. That’s something this community excels at. Writing this blog (and sharing more code) is part of that effort.

We have a moment. Let’s make sure Elixir rises with the AI tide.

To share the credit, if you’re working in a statically typed language as well as function? (cough: Elm 😍) Then your compiler is a gold mine for an AI assistant to work with, line numbers, exact type references, even calling out specific function signatures and variables that have the issue :chef-kiss:.

TY to RJ Dellecese for editing.

This post is self documentation as I work through my thoughts on testing an Event Sourced System using commanded. Transitioning from a history of traditional CRUD to Event Sourcing is wild and involves a big change in thinking…I think.

Testing

Why do I need this? Because I started writing tests like normal, only to start seeing tons of connection and PID related errors. After much discovery and the Elixir Slack #commanded channel’s input, I’ve started to grok it. I kind of like how structured it is 🙊

General Config

# config/test.exs
# Sandbox Repo
config :app_name, AppName.Repo,
  pool: Ecto.Adapters.SQL.Sandbox,
  …

# In memory Event Store
config :app_name, AppName.EventStore,
  serializer: Commanded.Serialization.JsonSerializer,
  adapter: Commanded.EventStore.Adapters.InMemory

# Oban in manual mode - jobs only execute with direct invocation
# I've really liked the `Oban.Testing.with_testing_mode(:inline, fn -> … end)` for individual tests
config :app_name, Oban, testing: :manual

Pure Unit Tests - Aggregates & Business Logic

use ExUnit.Case, async: true

These are all pure functions and should encompass commands, events, and aggregates. Construct commands, construct state, execute the command, assert on the result.

• No Side Effects
• Do Not Assert on the State of the Aggregate
• Only input and output, leave the aggregate state opaque
• This should encompass as much business logic as possible
• Functional Phoenix Components could fit here too

Unit Tests - EventHandlers

use AppName.DataCase, async: true

These are functions with side effects, in Phoenix DDD we would call these context functions. We are testing 1 function that usually performs a DB operation, not the flow of data through the system.

Essential Business Element

Test independent parts of the system that have side effects. Test Oban.Testing.perform_job/2, but not how it links to parts of the system. Test EventHandlers, often it’s Event in, assert :ok, and assert_enqueued/1. We often have a handler setup that only queues the Oban Job for durable execution. This keeps things very isolated at the cost of an additional step in the flow.

Essential Technical Element

These tests can take advantage of Ecto.Adapters.SQL.Sandbox because each test can checkout a single connection pool to the DB for that process alone. You can test the internal functions of a Genserver, but testing from an external caller that is going to spin up a new process is asking for trouble. The result is frequent ownership errors or PIDs shutting down before the call returns, making tests very noisy.

• Single Process Side Effects (DB)
  • Oban Job performs
  • Oban Job Enqueued
  • Handler responds to the correct events
  • Projectors getting called directly
  • API calls to 3rd parties
• Test Contexts Independently
• This can even include controller functions and Phoenix Liveviews as long as it doesn’t include Command dispatch

Integration Tests - Command Dispatch

use AppName.ConnCase

# conn_case.ex
  …
  setup tags do
    reset_commanded(tags)
    Cove.DataCase.setup_sandbox(tags)
    {:ok, conn: Phoenix.ConnTest.build_conn()}
  end

  # Drops active events and handlers and restarts the app - and in memory event store
  def reset_commanded(tags) do
    if not tags[:async] do
      {:ok, _} = Application.ensure_all_started(:app_name)
      on_exit(fn -> Application.stop(:app_name) end)
    end
  end

Because Event Sourcing with commanded is an eventually consistent and multi-process affair, we quickly jump to any other type of test being a full, synchronous integration test. These tests require shared DB access because event handlers need to be able to run in the same DB transaction (eg. Reading data that was written by a separate process). Additionally, these require your commanded app to be running and at the end of the test we need to shut it down or else suffer noisy error logs as handlers are still running after the test process has exited. ⚠️ These tests are significantly slower. For that reason, we should use these for strictly testing the connections between our processes.

• Multi-process, soup-to-nuts, integration testing
• LiveView UI -> Command Dispatch -> Projection Update -> LiveView Update
• Ideal Test
  • LiveView Test, render_click on a submit button
  • Await a pubsub message from the projection
  • Assert the view changed

This is a reflection on my love letter to Elm, to make myself better understand why I’m ready to move forward. I’ve been watching LiveView for a long time and it’s passed my threshold as an Elm holdout by becoming mature enough to depend on, easy to develop with, and a leader in showcasing the benefits of modern SSR. As my goals grow and change, I need my toolkit to as well. I’m looking forward at more experimentation and exploration with LiveView as the medium. My hypothesis is that LiveView’s simplified API, 2-way communication, and end-to-end UI testing makes it the best tool for modern use cases and I’m stoked to see just how much there is to gain.

I’m excited to push LiveView to explore its potential. The shift to SSR and a unified language for frontend and backend unlocks some incredible benefits. By removing the separate frontend language and active development of the API layer, the cognitive load to create a product is dramatically reduced. This removes hundreds of lines of code I’ve come to accept in the past and simplifies the mental model of data flow. These advantages are a result of comfortable SSR templating (heex) and tight websocket integration, which make the client experience nearly indistinguishable from a traditional SPA. Seamless, real-time updates with server push allow SSR to compete directly with modern JS-driven SPAs. In Elixir, process-driven concurrency makes leveraging these benefits even easier. LiveView assigns an in-memory process to each connected client, allowing seamless communication by sending messages directly to these processes using Elixir’s built-in primitives—no special DSL or complex logic required. These all reduce cognitive load and reduce code, which means fewer and faster decisions. Finally, this means faster implementation and better iteration speed.

To be fair to Elm, I’m going to miss it and its unparalleled strengths. The truly unique degree of confidence provided by its error-proof runtime and compile-time checks made it a delight. Elm excels in building complex UIs in API driven environments. But for my next chapter, I’m focused on exploring new territory and delivering innovative products, where LiveView aligns perfectly with fast iterations over the stability I loved from Elm.

Every tool has its place, and LiveView is the right choice for where I’m headed. Elm is an excellent choice for many scenarios, but my joy comes from providing services that users love, and discovery requires iteration. I’m confident with LiveView I can reduce iteration time, yielding more cycles, faster feedback, and ultimately more progress in less time. I’m excited to see how far LiveView and I can go on this journey.

Have thoughts to share? Want to learn more details? I’d love to hear from you! Send me an email

You know em’, you love em’, my editors: RJ Dellecese and Sam Roberts

Note about Shamshirz

This post reflects my experience working extensively with Elm at a B2B insurance startup from 2017 to acquisition in 2024, as the 2nd Engineer.

I’m looking at a new year of big changes and I want to share my appreciation and advocacy through reflection. Elm is my Gold Standard, best in class UI development kit. I had experience with SSR templating languages, vanilla JS sites, and React just prior to picking up Elm. Elm was my first introduction to a pleasant type systems (👎 unlike Java). The type system is friendly, clarifies thinking, and provides the best feedback loop I’ve experienced in engineering. I learned that Elm can be rocket fuel and I hope to articulate when I saw it accelerate us as well as when I saw the signs that it may not be the best fit. Elm isn’t without its limitations, but allow me to convince you why it’s worth it, dear reader.

Why Elm Shines

The type system is simple and delightful. The compiler is fast, capable, and descriptive enough to be a coding assistant without the need of an LLM. Problem solving is mostly modeling types to reflect your needs and the code writes itself. The initial hurdle is adapting to the syntax and the flow of data through the Model, Update, and View functions. The language is small! Once you’re past the basics, you’ll find it easy—and fun—to dive into discussions and improve your work. In contrast, the JS ecosystem often demands familiarity with language oddities, dependency sprawl (leftpad), and each author’s unique style. Elm avoids this entirely. A standard formatter ensures consistent, readable code across all projects. The compiler’s precision was so effective that we rarely felt the need to write tests.

Running Elm in production genuinely changed how I saw front end development. The compiler’s feedback was the end of the loop, rather than manual UI testing after a change. The compiler will assert whether you’ve covered every possible case and handled every operation that could fail. The implications are enormous and easily overlooked. No debugging in the browser locally, in Staging, in Production, or trying to reproduce a problem a user saw in their browser. It’s very hard to truly appreciate the lack of something found in many little moments, but the overall impact was profound. I didn’t view UI work as tedious or error prone. The only negative that I experienced was that Elm became “boring”;it didn’t need me. I had complete confidence that Elm could guide new engineers to success and adding my experience wouldn’t bring any added benefit. I subscribe to Dan McKinley’s ideal that “boring technology” is a good thing that allows you to put energy elsewhere. We know when Elm shines and we know it’s failure modes quite well. Elm’s static nature and tiny language size make it surprisingly “boring” without the need for dozens of years of use like Postgres. The important decision to make is whether you are willing to accept the trade-off that Elm requires in order to benefit.

Trade-offs to consider

Elm is wonderful because of its limitations. One amazing property of Elm is that it guarantees zero runtime errors. To provide that guarantee you aren’t allowed allowed to integrate JS directly into the Elm runtime. Everything external to the runtime has to go through a Port. This is doable, but the code that ports require is not pretty and is not fun to work with. We implemented them very infrequently in part because we didn’t need as much from outside of Elm as we expected, but undoubtedly also because of the difficulties of working with them. We got by with simple ports for GraphQL subscriptions and page scrolling, but as others benefit from things like WebSockets and you miss out, you will notice the inaccessibility of advancements made outside of Elm.

We ran into issues occasionally, but compared to experiences with other frameworks it was a much smaller drag on our productivity. We had a compiler slowdown that impacted development, but Evan Czaplicki, the creator of Elm, gave us some input to resolve it. We got massive benefits from the elm-graphql library (generates an Elm SDK for our GraphQL API), but it was a big implementation cost and still isn’t intuitive enough for engineers to grok quickly.

For Elm or any UI framework, the accidental complexity, popularized by Fred Brooks, that comes with a separate build system for UI should to be considered. I continue to learn this lesson regularly. This is maintenance and time to your build pipeline. This was not obvious to me when we started with a SPA build step, but since the rise of Elixir LiveView I can’t stop seeing the added burden of a separate UI framework.

10/10

If the limitations are acceptable for the project I’m working on, then Elm is my preferred way to develop UI. When I prototype, it’s most often with Elm. I spend my time thinking through the types and what I really want to accomplish rather than chasing around errors. It folds well into my dev environment too. I use (and adore) the cursor editor, and with Elm’s compiler, I can immediately feed it back to the LLM and I generally get away with having a conversation with the composer tool and no coding needed 🤯.

Elm is a walled garden, for better or for worse. I love that it hasn’t needed any changes, bug fixes, or updates to keep working perfectly. It feels frozen in amber, in a perfect working state. You can achieve business and personal success with Elm. It got us to an acquisition and the reliability and dev satisfaction far out-weighed the limitations. If you’re an engineer seeking a delightful UI experience, I can’t recommend Elm enough. Especially if you are new to functional programming or static typing, this is a beautiful way to learn.

Have thoughts to share? Want to learn more details? I’d love to hear from you! Send me an email

my editors: RJ Dellecese and Sam Roberts

When I explore an idea, I want to test it out all the way through deployment. There is no better way to challenge my assumptions about libraries (comparing HTTP clients) or ideas (SQLite is the future of storage) than working through publishing. I dread this step because it’s either 💰, headaches or hard work. I can’t speak highly enough of ngrok when I only need to share with friends or treat myself as a real user rather than localhost. I want to go a step further. Fly’s blog has been posting some fantastic material lately and their “inbound” marketing caught me.

My default had been Heroku, RIP 🪦 free tier, but I never loved the workflow. Specific Elixir alternatives like Gigalixir are out there but didn’t catch my attention. On the other end of the spectrum, AWS fills me with mixed feelings of terror and boredom. I hadn’t found a compelling example until Fly.

Making an account and creating the starter app were easy, guided experiences. That’s how it should be, and better than usual, I actually felt equipped to step away from the guide and try on my own. The fly CLI is fantastically simple, with great feedback especially while deploying.

“Speed Run” Fly Docs

brew install flyctl
fly auth signup
fly auth login
fly launch --image flyio/hellofly:latest

I budgeted a lot more headaches than I experienced and that convinced me. I had the mental bandwidth left to pursue my other explorations immediately. I experimented with floki, req, Liveview, and SQLite. Instead of fighting with deployment, I explored those tools in a real app and the extra energy came from Fly providing the platform. If you’re interested in seeing any of those, or just a Fly deployment in the wild, the repo lives here.

Fly is my new default playground for exploration and full deployment isn’t a Maybe anymore. I’m stoked to add deployment satisfaction to my normal exploration flow. It used to be such a bother I would skip the joy that comes with seeing real traffic. In hindsight, “no duh” that a tedious deployment process would cause me to lose motivation. #AppCareIsSelfCare

P.S.

The experience brought up another feeling. Cognitive dissonance around full-stack applications. I enjoy Elixir, Fly is awesome, I adore Elm, elm-graphql is a godsend, and I see the value in Liveview. That said, I struggle to rationalize full-time servers and DB instances in the face of how accessible serverless functions + static sites have become. For my needs, 24/7 service is a waste. I’m exploring these ideas now…

P.P.S.

• I’m not affiliated with Fly.io, I just really them.
• Shout out to my editors 🙇‍♂️ - RJ Dellecese and Sam Roberts