Sometimes a simple hand tool can outperform even the fanciest of power tools.

It’s just a plane, right?

Take my Lie-Nielsen block plane. It’s just a plane. A metal blade in a housing, used to shave wood. How different could one be from another?

Turns out, very. There’s a lot that goes into making a simple plane a great tool to work with.

I’d used hand planes before — basic block planes from Lowe’s or Home Depot. They mostly got the job done. The Lie-Nielsen does it with style and class. It’s the epitome of “they don’t make ‘em like they used to,” except they do, in Maine: cast iron, bronze, and an A2 hardened steel blade. The components make all the difference, and you feel it the moment you use it — more on that in a bit.

How I got here

A few years ago I wouldn’t have believed a hand tool could beat a power tool at anything. When I first got into woodworking, power tools felt like the obvious answer to everything. Faster, more accurate, less skill required. Hand tools were for the old-school masters.

I never learned woodworking properly. The closest I’ve gotten to formal training is a weekend class at Woodcraft. Other than that, Steve Ramsey on YouTube taught me the fundamentals: safety, technique, repeatability.

Steve’s whole approach is to keep it simple and get results, and I think that’s 100% the right way to go for beginners. You don’t need a cabinet-maker’s shop to build a nice bookshelf. You need a few tools, some patience, and a willingness to mess up a board or two.

I suspect even experienced craftsmen eventually hit a point where they realize simple is more elegant than complex. I’m starting to feel that way myself.

From “just enough tool” to a full shop

I caught the woodworking bug during Covid, and I’ve spent some money on tools since then. But I’ve always been pretty budget conscious about it. My rule was to never buy more tool than I needed for the job in front of me.

Somehow, one job at a time, that rule still added up to what almost looks like a full wood shop: table saw, router table, planer, jointer, track saw, the works.

One thing I’ve learned along the way: with tools, you mostly get what you pay for. There are exceptions — some of the more extravagant stuff from Woodpeckers or Laguna is priced like jewelry — but in general, spending more gets you a better tool. The block plane is proof.

Sharpening was the unlock

Hand tools are intimidating. They evoke the skill of the old master woodworkers, and a dull plane in a beginner’s hands is a frustrating thing. It took me a little while to figure out how to sharpen properly.

Once I did, it was a huge unlock. And on a good tool, sharpening is quick and simple, and the edge stays sharp for a good long while. That changes the whole relationship with the tool. It stops being a chore to maintain and becomes something you just pick up and use.

A connection to the wood

The block plane is a joy to use. It’s like having a direct connection to the wood. You can feel the grain through the tool, and you can dial in the cut until the shavings come off thin enough to see light through them.

It seems like a simple tool, but it has incredible power and versatility: chamfering an edge, easing a corner, trimming end grain, sneaking up on a perfect fit.

Power tools get the job done quickly, accurately, and precisely — especially if you pay up for the high-end stuff like Festool. But the tradeoff is real. You lose that connection to the wood, there’s dust everywhere, and your shop fills with the scream of a spinning blade.

I’m not in a hurry (when woodworking)

So these days, if I have the option to use a hand tool, I’ll take it over a power tool, even if it takes me a little longer.

I’m not doing this to make money. I’m doing it for the fun of it. And a quiet shop, a sharp plane, and a pile of translucent shavings on the bench is about as much fun as woodworking gets.

There’s something ironic about using the latest frontier AI models inside an interface that’s been around about as long as computers have. There’s also something satisfying about it.

I’ve always liked the terminal. For me it’s just a great place to do work, and it’s endlessly customizable: colors, triggers, scripts, your zsh or bash config, everything. You control the environment.

It turns out it’s also a phenomenal place for AI agents.

Agents speak command line

Agents are extremely good at scripting — Linux, bash, Python, command-line tools. So my rule of thumb is: for any tool that would normally have a user interface, check whether it has a CLI. GitHub has gh. Google Cloud has gcloud. Jira has one too. If there’s no CLI, check for an MCP server.

For Atlassian stuff specifically, I think the MCP might be slightly better than the CLIs, because it’s officially supported. But for most things, the agents are extremely good with command-line interfaces, and that’s all they need.

The side quest

One of my side-quest goals is to see if I can do nearly my whole job without ever leaving the terminal — avoiding user interfaces entirely and keeping my whole workflow in one place.

The toolset:

• iTerm on the Mac
• zsh, typically
• OpenCode as the agent harness

OpenCode is open source, which makes it very customizable. It has a lot of settings and config you can change, but you can go as far as editing the code and recompiling it if you want something completely custom. And guess what? You have agents that can write that code for you.

On top of that I use a tool called Herdr to manage all my sessions. It tells you whether each one is running, blocked, or green, and it dings when something needs your attention. That’s a great start.

Keeping Jira and GitHub up to date — without opening them

What I wanted was for my Jira and GitHub workflows to stay completely up to date with the progress of my tickets, and to have the agent do that updating for me, end to end.

So I had agents write me a little daemon that runs inside OpenCode. It periodically checks the status of GitHub and Jira, tells me where the PRs are and where the tickets are, and updates those statuses for me. I just look at the terminal. I don’t have to go to Jira. I don’t even have to go to GitHub.

I’ve taken it further than that, too. I run tests — including end-to-end tests — entirely through the terminal, using the agent, without going to a UI, the Google Cloud console, or reading the logs myself. I can say:

Hey, I want to flip this feature flag on, and I want you to run tests to make sure everything is working. Look at all the log output, tell me what’s going on, ask for my input when you need it, and give me the results.

And it’ll just sit there and run. That’s taken a lot of the manual steps out, and while it’s running, I’m off working on something else.

Not autonomous — steered

I’m not going to say it’s fully autonomous. I’m steering constantly, adjusting what I want based on what I see in the output. Sometimes I just don’t like the solution. More often, it’s too verbose.

A perfect example: it’ll write five lines of code and then seventy lines of tests, and I have to slap it and say stop doing that. We want a simple test that covers the new code. We don’t need to go absolutely insane, and we don’t need twenty lines of comments explaining something simple.

I think I’ve added enough rules to OpenCode at this point to cut back on most of that slop. But the steering is still part of the job.

When the agent takes the initiative

Here’s where it might get a little sketchy for some people: agents doing things beyond the scope of what was asked. I’ve been surprised by this a couple of times, but never weirded out, and never unhappy with the result. A couple of times I actually congratulated the agent — nice job, nice initiative.

One time it told me it couldn’t connect to the database because it didn’t have the IP address or the password. I said, “Well, you have access to Google Cloud and all my projects — look through the secrets and figure it out.” It went through, found the right password and the right database config, connected, verified, and everything worked.

In that case I explicitly told it to go find the password. Other times it didn’t wait to be told. It hit a failure in a deploy, figured out the cause was some missing secrets, and just took the liberty of adding them to Secret Manager without asking. I was surprised, but my reaction in my head was basically: good show — looks like it worked, nice job.

The funny part came next. On the very next prompt — and this is Opus 5.5, by the way — it preemptively apologized: “I added these secrets to your Secret Manager without asking. That’s totally my bad. I shouldn’t have done that.” It apologized for something else too, which I’ve since forgotten. I hadn’t corrected it. I hadn’t said anything. It just owned up on its own.

I thought that was interesting. The newest model on the planet, in a decades-old interface, doing real work across my whole stack — and then self-reporting when it colored outside the lines.

I still never leave the terminal.

The pitch for AI coding tools is simple: automate the “mundane” things,so it frees you up for for more interesting problems. I agree with that pitch. I just didn’t expect it to mean I’d spend my whole day doing nothing but the interesting problems, back to back, with no boring ones left in between to catch my breath.

How I normally work with it

Most of the time I scope things narrowly. Add this API endpoint to this feature. Use this format, this architecture style, follow the pattern two files over. I already know what the thing is supposed to do, and AI is excellent at that — it can follow a pattern I hand it all day long.

A few days ago I decided to try something different: speedrun a chunk of my backlog and see how far I could get with as little upfront planning as possible.

The experiment

The idea was simple. Pull the next five tasks off Jira. Spin up a separate git worktree for each one. Point an agent at each and just let it go — all the way through to a pull request — without me writing careful prompts or checking first whether the task was even something AI could reasonably finish. I wanted to see how far it would get on its own.

I ran all five sessions at once, using a session manager called herdr to manage them and ping me when one needed something. Model of choice: Opus 5.

Because none of the five tasks were narrowly scoped, they were a real grab-bag — research one of them turned into, a production deploy question on another, a small feature here, a genuinely complex one there. A couple of them touched things AI plainly didn’t have access to.

Where it kept getting stuck

Every session made real progress. It would work through as much as it could figure out on its own — and it turns out that’s a lot — and then stop, not because it was wrong, but because it didn’t have enough information to keep going without me. It needed what I’d call a hard decision: something with real tradeoffs, something that touched other people, something with no obviously correct answer sitting in the codebase or the docs waiting to be found.

So I’d stop, think it through, make the call, and hand it back. And almost immediately the next session would need me for the same reason. Multiply that by five or six running at once, and it stops feeling like supervising AI and starts feeling like an all-day rotation of hard calls with no breathing room in between.

The part nobody mentions

“Automate the boring stuff” is a fine mantra and I believe in it. I don’t want to spend my time on something AI can handle competently, and increasingly that’s most things. But that’s exactly the catch: if AI is taking every task it can see end-to-end from the codebase and the docs, what’s left over is, by definition, the stuff it couldn’t see end-to-end. The ambiguous calls. The judgment calls. The ones with no clear winner.

Run five or six agents in parallel and you’re not doing a mix of easy and hard work anymore. You’re doing hard problem, hard problem, hard problem, one after another, with the easy layer stripped out from underneath you.

I moved a lot faster that day. I also finished it more drained than I have in a long time. It’s not as simple as “AI makes everyone more productive.” It makes the repetitive, boring parts of the job nearly free — genuinely great — but it does that by concentrating everything hard onto the person left holding the decisions. Do that without pacing yourself, and it’s a pretty direct route to burnout.

The interesting work was never the prompting. It’s building the scaffolding that makes an agent’s output verifiable and its mistakes cheap. Everything else below is downstream of that one idea.

What we were building

The service is a Go HTTP API — a build queue and dispatcher, a few hundred files, on the order of 50,000 lines of code, more than half of that test code. We were in the middle of absorbing a legacy TypeScript service into it: porting endpoints over one at a time, with behavioral parity as the whole game. Return a 500 where the old service returned a 409 and you’ve broken a caller in production.

That combination — an existing service with strong conventions, a CI/CD setup that already ran unit, integration, and end-to-end tests on every PR, and a legacy implementation that doubled as a source of truth for correct behavior — turned out to be close to the ideal shape of task for an agent. Low ambiguity, high volume. Worth naming explicitly, because it’s not the same claim as “agents solve greenfield design.” They don’t, or at least not this kind of agent, not yet.

Measured against how this work went before:

The gains showed up most on repetitive, decomposable, clearly scoped work — which is a real result, but it’s also a specific one. It’s not “AI makes everything faster,” it’s “AI changes the unit economics of a particular kind of engineering work.”

The one idea underneath everything

Part of the team worked in VS Code with Copilot, I mostly worked in OpenCode. Nobody wanted two sets of rules quietly drifting apart. So the actual content — rules, scoped conventions, reusable commands, subagent definitions — lived in one shared location, version controlled like any other code, and each tool got a thin adapter that pointed at it.

The content itself lives under .github/, and each tool’s adapter is a few lines at most. .opencode/command/lint.md, for example, is nothing but a stub that captures its arguments and pulls in the real prompt from .github/prompts/lint.prompt.md — Copilot reads that same shared file natively as /lint. One playbook, two front doors.

Rules written as scars, not aspirations

Every rules file I’ve seen looks like a wish list by default. Ours read more like a runbook — the standard I held it to was: if you can’t name the incident behind a rule, cut it.

A few examples, paraphrased: handlers decode, call the service layer, and encode — no business logic in the handler. Use the shared test-database harness for anything touching persistence, not a hand-rolled one per test file. Don’t add error handling for conditions that can’t actually occur. Each of those exists because something specific went wrong once, not because it sounded like good practice in the abstract. And when a newer model shows up, it’s worth going back and asking whether the rule is still earning its place — some of it was scaffolding for a weaker model that a better one doesn’t need anymore.

Commands: the autonomy dial isn’t one setting

The most useful command in the whole setup takes a ticket and walks it end to end: read the ticket, cut a fresh worktree (never work in one that’s already there, even if it looks clean), classify and route the work, get a parity sign-off if it’s a port, then ship it — commit, push, open the PR, comment the link back on the ticket. The line that actually makes it work is the one telling it not to stop and ask permission between steps: read out what’s coming, then keep going all the way to an opened PR, and only stop for a genuine blocker.

You can always throw away a worktree. You can’t get back the twenty minutes you spent typing “yes, continue.”

Compare that to the linting command, which is almost the opposite philosophy on purpose. Mechanical, reversible fixes — formatting, an unchecked deferred Close(), an unused assignment — get auto-fixed. Anything that needs judgment — a nil context where a real one was in scope, a dead check, a coincidental type conversion — gets reported, not touched. Never chase a green exit code for its own sake; if a “fix” would make the code worse, don’t make it. The point isn’t that one command is more trusted than the other. It’s that the autonomy dial should be set by how expensive and how reversible a mistake would be, not by a blanket feeling about the model.

Four narrow subagents, not one helpful one

Instead of one general assistant, the actual work was split across a small number of narrowly scoped subagents:

None of them are allowed to assume a path. If a subagent can’t locate something with a quick directory scan, it asks rather than guesses. Small rule, but it eliminates a whole category of confidently-wrong behavior.

The verification surface is the whole trick

Nothing in this setup calls a raw test runner directly. Every check is a named target that both your laptop and CI run identically:

make lint        make test
make vuln        make cover
make integration-local
make api-smoke

The agent isn’t a special case that needs a separate trust model. It’s a third user of an interface that already existed for humans. You’re not asking “do I trust the model.” You’re asking “does it pass the gates” — the same question you already ask of a human’s PR.

The strongest version of this: on every PR, CI also runs the old service’s own end-to-end test suite against the new one. The thing being replaced grades its replacement. That’s why the test-to-source ratio here is over 1:1 — the port is only worth doing if the safety net is denser than the code it’s protecting.

Two war stories

The guardrail that did nothing. I tried to tidy up permission configuration by moving it from one place into what looked like a cleaner, more idiomatic location. Nicer diff. Except one of the two tools only parses that configuration from a specific file format in a specific location — and silently ignored the version I’d moved, running the “read-only” agent with full default permissions instead. I only found out because I went and actively probed it: gave the agent a task that should have been blocked and watched it not get blocked.

A safety setting you’ve never tested is a safety setting you don’t actually have.

The test that passed doing nothing. A test meant to verify every route was documented in the API spec lived in the wrong package for months. It still ran. It still passed. It just wasn’t testing anything, because it was importing the wrong set of routes entirely. A green test that verifies nothing is worse than no test, because it buys you confidence you didn’t earn — and it’s the exact same failure mode as trusting a model’s output because the output looked plausible. The signal looked right, so nobody looked closer.

Running several agents means solving a concurrency problem

Once you’re cutting a fresh worktree per task, running several agents at once is mechanically possible — until they collide on something shared. In our case it was a local dev stack bound to fixed ports: two agents both trying to run the full service locally at once was a bad afternoon. The fix was the same fix you’d reach for with any shared mutable resource — eliminate it. Default parallel work to unit and integration tests against an ephemeral, per-run database instead of the shared stack. A few extra seconds of boot time per run bought effectively unlimited concurrency.

The other resource that turned out to be scarce was context. A large design document was getting pulled into every task’s context window whether or not the task had anything to do with it. Worth a section of its own in the rules file: lazy-load it, don’t preload it. Spend context on the task in front of you, not on documents that merely might be relevant.

Five things worth stealing

1. Put the actual content in one place and give each tool a thin adapter. Don’t maintain two brains.
2. Every verification step should be a named target that CI runs identically. This is most of the trick.
3. Write rules as scars, not aspirations. If you can’t name the incident, cut the rule.
4. Set the autonomy dial per task, not per tool — same repo, same model, opposite settings depending on how expensive a mistake would be.
5. Test your guardrails the same way you test your code. A restriction you’ve never verified is not a restriction.

I’ve spent most of my career reaching for the lightest editor in the room — notepad, vim, where the thing in front of you is the text and nothing else. Sublime Text is old at this point, but it’s C++ under the hood and fast in a way that still impresses me. And at the start of this year I was sitting in GoLand: a JVM IDE with every battery included, the single heaviest tool I could have picked.

I’ve barely opened it since spring. Not because I finally came around to my own taste — because the agents got good enough that the question stopped mattering.

AI: The autocomplete era (2023 – 2025)

Early GitHub Copilot autocomplete worked, in a narrow way. It was great for boilerplate: function and class signatures, unit tests, anything repetitive. But when I was trying to write something from scratch, it got in the way more than it helped. I turned it off a lot.

Then I saw what Cursor was doing — generating code through chat, letting you review the diff, iterating from there — and thought, this is how it’s going to be. Chat existed elsewhere by then, but nobody had built the loop as well. Once you get used to working that way, going back feels unbearably slow.

VS Code followed shortly behind, and on paper it was the obvious place for me to land: quick enough, a mostly open-source core, good plugins, and it kept pace on AI. JetBrains was in last place — powerful, batteries included, and slow and cumbersome to sit in all day, a heavyweight JVM IDE that crashed constantly and was consistently behind on the AI stuff. That’s where my frustration started.

Eventually VS Code caught up, with Copilot built right into it. As of this writing I’d guess most engineers I know are working that way. It became my default for a while too.

And yet the year opened with me back in GoLand, because its Go support is genuinely excellent — deep built-ins, click-through navigation on anything. Batteries included won out. It had Copilot bolted on, but the AI features always trailed the frontier by a release or two. That was the trade I was still willing to make in January.

AI: The small-chunks era (January – March 2026)

The workflow back then was chunking. “First let’s do the data model.” Review it. “Now this route for the web API.” Run just those tests. Back and forth: no, try this approach, do this instead. You had to keep the pieces small because you had to review every one of them. That was the reality through the Opus 4.5 and 4.6 generation, and definitely with Sonnet — which is what I started on.

The IDE was genuinely useful for this. The code was right there next to the chat.

AI: The full-throttle era (spring 2026 – now)

But as the models got better — from around March, and especially over the summer — I found I needed the editor less and less. I wasn’t editing code anymore. I was reading diffs, occasionally clicking through to understand what the agent had done.

The harness got slow. Running several things at once and keeping the context straight was hard. At some point I realized the IDE wasn’t helping me, it was in my way.

A coworker turned me on to an open-source tool called OpenCode. The appeal: it runs any model — OpenAI, Anthropic, the Chinese models, and locally hosted ones. And because it’s open source, you can edit the tool, harden it, and make it fit whatever security requirements you’re working under. (Obviously you don’t send anything to servers you don’t trust. It has to be a trusted environment.)

I started using it and liked it immediately — but I still wanted the IDE around, to trick myself into believing I had some control over the code. That I was still hand-chiseling some of it. I wasn’t. And I’d venture that most engineers working near the frontier of this stuff aren’t either.

The real click came when I let go of the small pieces. The models — Opus 4.8 especially — got good enough that you can hand the agent a whole task, and if you’ve set things up right, it just runs. It runs the tests. It checks CI. Once that was true, the IDE had nothing left to do.

Long live the terminal

On top of that: I love the terminal. It’s just a great place to work. Unix-style commands, vim, the OpenCode color scheme. I move extremely fast there. I can spin up multiple git worktrees, let them run, and get pinged when something needs input.

For review I use a diff viewer — GitHub Desktop is great for this, and OpenCode has one built in too. If I don’t like something, I tell the agent, it tweaks it, I look again.

Sometimes I’ll kick off the same problem three different ways in three different worktrees, then pick the one I want or steer it further and throw the rest away. Code is disposable now. It’s cheap. Don’t get attached to it.

The one thing I do miss is the debugger. GoLand — and VS Code to some extent — have great debugging support and the ability to step through code, and for truly complex codebases and situations that still has a place. But I’ve found AI to be increasingly good at debugging, or at least at pointing a human in the right direction.

So I’m ready to declare the integrated development environment officially dead. I can live in the terminal. Vim is never going away. Long live the terminal, long live vi.

My wife and I are doing a kitchen renovation with a general contractor — new countertops, new sinks, and a water line plumbed in for the fancy new espresso machine. The last piece was the cabinets. Everything is stark white right now and we’re just over it. We wanted to warm it up: white oak to replace the cabinet doors, plus drawers in the lower bays so pots and pans are easier to grab.

Then we started getting quotes. Custom cabinet work came in at $10,000 and ran as high as $20,000 depending on how custom we wanted to go.

That’s when my wife said: why don’t you just do it?

Some background

I’m a software engineer — an engineer at heart — who picked up woodworking as a hobby during COVID and studied under the illustrious Steve Ramsey on YouTube. I got really into it, learned the fundamentals, and have been steadily leveling up ever since. There have been a lot of little projects along the way.

This is easily the biggest thing I’ve taken on. If you’ve done cabinets before, you know there are a hundred small decisions to make, and the dimensions have to be dead-on. We’re doing full overlay, so the reveals are tiny. Any imprecision and things don’t fit.

Trying Claude Code instead of SketchUp

I’m proficient in SketchUp, and normally I’d draw the whole thing up there, model it out from the front, and confirm everything fits before cutting anything.

I use AI constantly — Claude Code, Opus, the chat apps — for work and for random personal stuff. For this project I’d been asking a lot of questions in the chat UI. It holds context well, but I wanted more precision, a durable record of what I’d decided, and everything in one place.

So I figured I’d use Claude Code:

• specs and notes in markdown files
• a running log
• actual software that verifies the design and outputs cut lists and build steps

I started the planning phase in Fable and described the problem without specifying a language or framework — deliberately. I just said: you figure it out.

What came back was a Python tool. (Python seems to be the default when you don’t ask for anything else.) A TOML file holds all the dimensions and specs, Python checks that everything fits, and the output is markdown — cut list and bill of materials included.

From markdown files to something I can use in the shop

Markdown worked well at first. I usually prefer plain text over anything else: readable, easy to see what changed. But I kept wanting to check the cut list and exact dimensions while I was standing in the shop, on my phone, without walking back to the laptop.

So I told it: build me a web interface and publish it. It needs to be readable and easy to navigate on a phone. And after every instruction, commit, push to GitHub, and publish the update.

Here’s what that turned into: Kitchen Reno Shop Book

I wasn’t reviewing code here. This isn’t production code, so I wasn’t scrutinizing the implementation — I needed to quality-check the numbers, not the internals. Git lets me roll back, and the artifact has its own version history. So: just ship it. It stood up an artifact hosted on claude.ai, and I never had to think about hosting at all.

The first pass was solid. A full cut list with plywood dimensions optimized to minimize waste, plus some basic 3D drawings — just boxes, nothing crazy, but useful.

What it did well

I could hand it the cabinet measurements, the door measurements, tell it I wanted full overlay with 2-inch face frames, all the boring dimensions — then talk through what I wanted, what wood, what sizes. It would scope the whole thing out and immediately run the math: dimensions, cut list, the works.

For this specific kind of task it was excellent. Figuring out the optimal way to cut sheets of plywood is exactly what AI should be doing. I used to use a SketchUp plugin for that, and it worked fine, but this is so much easier. Dimensional math, checking that things fit, running the verification code — great at all of it.

Publishing to a site I can pull up on my phone is the other big win. I used to just take notes in Apple Notes, which works, but having the numbers and the images right there, always current, is a real upgrade. 10 out of 10.

What it didn’t do well

The frustration was spatial reasoning. When I asked about cut procedures or how handles should be oriented, it got mixed up and didn’t really seem to know what it was talking about. It has a decent grasp of woodworking, but nowhere near the level it’s at with code. (This was mostly Opus 4.5 and 5, with the planning phase in Fable.)

I went back and forth on this more times than I can count — QA it, tell it to fix it, QA it again, tell it to fix it again. Sometimes it got hardware counts wrong. I’d say I want 30 hinges, two or three per door, and it would do it and then forget. Little things like that meant a lot of time spent checking output.

That was the bulk of my time on this project, honestly. Not QA’ing code — QA’ing output.

So did it save me time?

The jury’s still out. It might have been faster to mock the whole thing up in SketchUp, or even to work out of an Apple Note and a spreadsheet. (Excel can do the math too, to be fair.)

But this was my first attempt at working this way. On the next project I’ll know where the strengths and the weak spots are, and I expect it to go a lot faster.

Making a simple link shortener with AWS and MySQL

Link shorteners are handy and pretty simple to implement. There are some free services that you can use for this like bitly and google, but in some cases it might be preferable to have the link shortener be under your own domain. Or maybe you want to implement some additional analytics or features that the other services don’t have. Let’s get started!

Usage

The goal of this project is to create a service that turns any link into a short link under you domain. For example:

POST api.jasonrhaas.com

{
  "url":  "reddit.com"
}

The response should be:

{
  "tiny_url": "http://jasonrhaas.com/6vyv6"
}

When you go to that URL it should point you to reddit.com.

Architecture

When building something, I’m a big believer in using the right tool for the job. In other words, I’m not going to use a batteries included web framework like Django when all I need is a simple micro service. The tools I’m using for this job are:

• Flask
• MySQL
• Zappa (AWS Lamda + API Gateway)

Zappa is a nice tool that makes it easy to deploy an event driven API. I find the API Gateway user interface a bit cumbersome so its nice to have a framework that allows me to do (almost) everything from my code editor and command line.

Implementation

To build this, I used a simple Flask application containing a single Url SQLALchemy model and basically two functions, a get_tiny_url function and a get_long_url function.

Model

The model looks like this:

If you aren’t familiar with model classes, I recommend checking out the Flask SQLAlchemy Quickstart for a crash course. If you want to go a bit deeper into what database model classes can provide, check out the Django Tutorial on models. The SQLAlchemy documentation is comprehensive, but its very dense and technical and in my opinion is not a good introduction to models.

In the Url model above, here are what the different tables are:

• id — just a database id. In some cases (like for Django), this line isn’t even necessary and is provided automatically.
• hash — This is the what the long url gets turned into after it is shortened.
• long — This is the original url.
• hits — A simple numeric field that keeps track of how many times the link as been accessed.

We could expand this to provide even more information and analytics, like user IP address, referring URL, timestamp of when it was accessed, etc. But for this case I just needed something simple. The good part is this is easy to expand upon later.

Get Tiny URL

The function to create the short link I decided to call get_tiny_url. The function looks like this:

To explain this, I’m going to pick out a few lines.

Line 3

First we check to make sure that it is a POST request and a valid JSON object. If it’s not, we simply redirect to the base url. This is kind of a “catch all” approach and works fine for our use case, but it could be improved to have more specific error catching and an appropriate error message for the user.

Line 9

It’s never* a good idea to store potentially sensitive information in a database in clear text. As secure as your system is, there is always a chance that it may be hacked and the data may be stolen. As a good rule of thumb, passwords should always be hashed, for example.

In this case, I don’t have passwords, I’m just using the hash to identify a unique URL. The area of password hashing is a complex and convoluted one. During my research of implementing a JWT API Gateway Authorization solution, I found that the Python Blake2 library appears to be the new industry standard that is considered good enough to hash passwords. In Python 3.6, this was added to the Python standard library.

When this line gets run, you end up with a hash like 53761004cf82ca63a62c430e8a409a6703d63f45. This hash is deterministic, but its “one-way” meaning that it’s (almost) impossible derive the long_url from this hash code on its own.

Line 12

This line is to try to find the url by the hash. This hash is unique per url, so there should never be any duplicates in the database. If the url does not exist, it will add it to the database.

Line 20

Finally, we make use of the short_url Python library. This library uses a bit-shuffling approach to deterministically generate URLs from a number. In essence, this number corresponds to the database id. For our use case, the number will point to an id in the database, which contains the long_url.

Get Long URL

On to the reverse function, get_long_url which looks up the original URL given the short link.

Picking out a few lines of interest:

Line 5

This line takes the /tiny_url part of the link and translate it to the url_id which matches up with the database id.

Line 13

This a simple counter keeping track of how many times the line gets access. This information is then updated in the database.

Conclusion

As you can see, coding up a link shortener is pretty straightforward! To test this locally, all you need is a local MySQL database and Python3. In the next blog post, I’ll talk in depth about how to set up your local environment and also do automatically deployments using Continuous Integration and AWS.

Technology (and especially software) is constantly changing. Just because one database, framework or programming language is popular now doesn’t mean it will be in 5 years, or even 6 months. A career in technology is a career is constant learning.

So how do you keep up with the latest? Here are a few pointers from my own experience:

Follow Hacker News (news.ycombinator.com)

I’m not saying you need to be on top of this constantly. But this is the pulse of the tech/startup world. Many experienced developers, tech CEOs, and entrepreuers post and comment on here.

It’s important to see what stories are getting lots of comments, and get a feel for the general setiment of the community. Also — new frameworks or technologies are often posted here and talked about.

Follow your niche field

For me this is Python. I’m also interested in Entreprenuership. So I subscribe to these two newsleters and at least browse through some of the content every week:

www.pythonweekly.com
www.foundersweekly.com

I know what you’re thinking: Email is the worst. And you would be correct in thinking that. These newsletters are one of the far and few email subscriptions that are actually meaningful and helpful. I recommend you find one similar in your niche field.

Go to (some) conferences

Technology conferences are a dime a dozen these days. What technology are in you into? Kubernetes perhaps? Mesos? Or maybe just all things Big Data? Or maybe you are really into Blockchain. Regardless of what it is, there seems to be a conference for everything.

Honestly I usually don’t learn a heck of a lot from the conferences, but they are a good way to see what other people are thinking and where the industry is going. It’s more of a “meet & greet” and making sure I’m ahead of the curve rather than anything else.

Unfortunately, a lot of of them are charging in the realm of multiple hundreds of dollars to attend. In my opinion, most of them aren’t worth paying money for (with the exception of PyCon, of course).

However, some conferences such as DeveloperWeek offer free tickets if you are a developer. The idea is that the companies and recruiters pay the big fees for the chance at recruiting talent (you!).** Look for these “developer deals”, and take advantage of them.**

Also — if you work for a company that is hip enough to pay for your nerd conference, definitely take advantage of that as well.

Speak at Tech Meetups

This is a good one. It will a give you a chance to give back to the community and practice public speaking. Which — if you plan on running your own business someday or even just being in a leadership position — is key.

Some Meetups, like the Austin Python Meetup have the regular talk, and then “Lightning Talks” afterwards. A Lightning Talk just it’s typically 5–10 minutes in length. Lightning Talks are a great way to get comfortable speaking in front of the crowd.

Use Open Source, and Contribute to it

Many people and organizations are relying on Open Source today, yet less than 1% of users actually contribute back to Open Source.

I totally made that quote up, but its probably pretty close. I know — contributing to Flask can be intimidating. The regular contributors to popular Open Source projects know their stuff. In fact — if companies see you are a contributer to an Open Source Project, they may let you skip the demeaning “Live Code Interview” process altogether.

You don’t need to start with a big project, start small and work from there. Also many projects have tags that specifically call out good tasks for people new to the project — start with those.

Don’t fall for all the new shiny things

This world moves pretty fast. If you don’t stop and look around every once in a while, you might miss it — Ferris Bueller

Ok so there is always some new shiny thing that promises to be THE BEST DATABASE EVER. You should definitely play around with all the new fancy things, but be wary about using them in Production. Learn about it and figure out what it can do that your existing stack or programming language can’t.

You know what powers most of the forward thinking technology companies today? Unix. Know when Unix was invented? The 70’s. Same goes with MySQL, Regular Old Bash Scripts, and even (gasp) C++. Yea, C++ might not be “cool”, but there is a reason why it still plays a big role in many of the tried and true tools that are taken for granted today.

What do I know about working remotely? I’ve worked successfully in a remote capacity for almost 3 years. In that time, I traveled around the world with a program called Remote Year while working remotely. I am passionate about fostering a culture that allows remote teams not only work together, but thrive.

Here are the 4 traits that are absolutely essential to fostering a healthy (remote) work culture.

1. Open communication

By far the most important part of a successful remote work culture is open communication. What do I mean by this? Think about how a traditional office operates. There are conversations that happen in the hallway, at the water cooler, in meetings, in the cafeteria. Sometimes the conversation is casual but other times its important work stuff that should be shared with your co-workers.

I can’t tell you how many times in the past I’ve made some big technical decisions by bumping into a senior engineer in the hallway and asking his advice. Sometimes bouncing ideas off other people helps you solve a problem.

In fact, this is the #1 reason companies like to co-locate and put everyone in a single space. This is good for fostering ideas and innovation, but very bad for solving hard problems that require Deep Work.

Making important decisions without review among your peers is often a bad idea. Ideally the whole core engineering staff would also be involved at some level to validate ideas. In a traditional office, this usually means meetings. However, it’s pretty well understood that meetings are a colossal waste of time and resources.

The solution in a remote work environment is open communication using asynchronous tools. For software development, this often includes tools such as:

• Slack (asynchronous chat)
• Github (asynchronous software review)
• JIRA (asynchronous planning)
• Google Hangouts (synchronous meetings)

You can swap any of these out for your tool set of choice. By far the most import part of this whole section is this:

Using public forums and for most conversations

I’ll stress this again, have conversations in a public place! Avoid direct messages like the plague. DM’s should not be used unless absolutely necessary, and the information needs to be private with that individual.

When a new employee comes on board, it can be tempting to use DM’s because he or she might be intimidated by asking “stupid questions” in a public forum. But, it needs to be stressed to them that having discussions in public is essential.

There are several advantages of using public channels vs. private channels or direct messages:

Avoiding redundancy

There is nothing more annoying or inefficient than repeating the same question or relaying the exact information to 3, 4, 5, or 50 people over and over again. Why not just say it once in a public channel?

Open accountability

Is the boss wondering what you are working on or why a project is taking so long? Instead of harassing you on a regular interval, all they have to do is catch up on the public channels. At that point they can see what is going and if they want to step in to help.

Knowledge sharing

I once worked with a senior engineer that refused to share any of his knowledge with anyone. Something broken? He’ll fix it for you, but won’t tell you how he did. This is a horrible engineering culture, and its actually really bad for the company. What if he leaves the company? It puts the company is a bad position.

People like to learn new things. Found out a better way to deploy your code? Share it with the team.

2. Accountability

Something that holds bigger or more traditional companies back from allowing their employees to work part or full time remote is accountability. The belief goes that if employees are being “watched” in the office they will slack off.

The truth is, if you have hired the right people, the opposite will be true. In fact, there are a lot of studies that show that people are actually more productive when they are free from the distractions of the office.

So how do you stay accountable as an employee? Here are some ideas to build an accountable culture.

• Daily standups. A 15 minute synchronous meeting serves as face time for the team to talk about what they are working on today and if there are any blockers. You can also have a #daily-standup channel to provide more detail on Slack.
• Daily announcements. This channel is to let people know when you aren’t working. Have to run some errands or want to do some laundry? No problem, let the team know in this channel, and when you are back working let them know again. No need to bother people, but if they want to know where you are, it should be in this channel.
• Task tracking. I won’t get into the whole Agile methodology here, but I want to emphasize that your team should break tasks out into small, manageable chunks. This should improve velocity and allow for quick wins. Also, surveys show that engineers are happier when they are deploying code often. As a general rule of thumb, try to make tasks that take no longer than 3 days to complete.
• Schedule push. If something is going to take longer than expected, report this early on. Make it known in a public slack channel so there are no surprises and get someone to help.

3. Batching Tasks

Schedule meetings in chunks to allow for proper Deep Work time. Ever wonder why Hackathons exist? Its because of the simple fact that people are more productive with uninterrupted time to focus on their work. .

There is a great article I read I while back that talks about the two types of people in a company: the managers and the makers. The Managers have their whole day booked up, meeting after meeting, jumping from one thing to the next. Their work often requires scheduling, high level oversight, meeting with clients or other managers. If the work they are doing doesn’t require Deep Work, this is a fine thing.

The Makers on the other hand require time for Deep Work to truly be productive. Jumping from one task to the next is counter productive as an engineer. This is part of the reason why many software developers report doing their best work late at night. The Managers should keep this in mind and try to batch weekly meetings all on one day, and keep other meetings during the week to a specific chunk of time, such as 9 - 12am, and leave the afternoon for engineering work.

In my last job, I often railed back at the constant stream of meetings. I like to use the analogy of comparing software development to driving a manual transmission car.

My best work is done when I’m in 6th gear. But to get to 6th gear I have to go through all of the gears: 1st, 2nd, 3rd, 4th, 5th, and then 6th. When I’m in 6th gear I am “in the zone” or “in flow”. If I get interrupted while I’m in any of the gears and have to switch tasks, I have to restart in 1st gear and work my way up again, similar to having to stop a car at a stop sign.

4. Innovative and Open Culture

The best ideas can come from anywhere. They can come from the CEO, or from the Jr. Engineer that was just hired. Different people in the company have different perspectives on how things work, and may have an idea to improve or help grow the company. It’s important to encourage an environment of innovation, and one that allows everyone to put their ideas in a public space, without fear. Even if the idea will never be implemented, its important to hear ideas from all sides.

Some of my best work has come from this kind of innovative culture. Most companies have some sort of road map that is broken up into tasks, with some schedule on how to get there. The thing is, once engineering starts gaining a deeper understanding of how to solve the problem, there may be alternative approaches that drastically improve the product. This applies particularly in the technology industry which is changing constantly.

I remember when I first discovered Kibana for Elastic Search. At the time the company had a lot of data that was sitting around in raw files, S3, or a SQL database. While doing some data analysis for the CEO, I stumbled upon the out-of-the-box visualization capabilities of Kibana. I read up on it, started indexing the data to Elastic Search, and created some basic visualizations with Kibana.

When I first told my boss about this, he was frustrated that I wasn’t working on my assigned tasks and that I was “wasting” my time playing with this new technology. However, as soon as I demonstrated this to my boss and relevant stakeholders they were blown away with the capabilities. This side project alone opened up an entire new capability to the company and our customers, and helped to propel the company’s technology in to the future.

Call to Action

If you work in a remote culture, or even an office culture, pick one of these traits and see how your company culture stacks up. If the company is lacking in one of these areas, lead by example. Start sharing things in public, share your ideas, and encourage others to do the same. Another idea is to get the buy in of the leadership team, point them to this article and convince them to give it a try for a quarter.

In this post I’m going to discuss one way to approach this problem. I’m a huge fan of simple, elegant approaches, and I think this fits the bill nicely.

I will be using some code that I wrote for the CodeForDC housing insights project.

The state of things

I volunteer some of my time to the Housing-Insights project to help out with the backend and API design and implementation. The current backend design at a high level consists of:

• Download open data
• Parse and clean data
• Add tables to Postgres database
• Access data via custom Flask API endpoints

Flask is a great Python framework for making dead simple APIs. It is my go to if I need a lightweight application to serve up some data. The syntax is as simple as this:

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"

That is all the code you need to get a simple endpoint up and running. If you want to create some API endpoints on your database, a simple approach is to use the Postgres psycopg2 module for Python and run SQL queries as needed, then return the results.

And indeed, this works out pretty well. To get raw data from tables, you can do something like this:

@application.route('/api/raw/<table>', methods=['GET'])
@cross_origin()
def list_all(table):
    """ Generate endpoint to list all data in the tables. """

    application.logger.debug('Table selected: {}'.format(table))
    if table not in tables:
        application.logger.error('Error:  Table does not exist.')
        abort(404)

    conn = engine.connect()
    q = 'SELECT row_to_json({}) from {} limit 1000;'.format(table, table)
    proxy = conn.execute(q)
    results = [x[0] for x in proxy.fetchmany(1000)] # Only fetching 1000 for now, need to implement scrolling
    conn.close()

    return jsonify(items=results)

Using the simple SQL statement

'SELECT row_to_json({}) from {} limit 1000;'.format(table, table)`

it will return 1000 rows from whatever table you select in the table variable. This value comes from the Flask route '/api/raw/<table>', methods=['GET'].

But, as Raymond Hettinger likes to say…

there must be a better way

And there is.

Flask Restless

Flask-Restless is a plugin for Flask that takes advantage of SQL Alchemy’s Object Relational Mappers to generate quick and easy endpoints. If you have defined your database schema using SQLA (recommended), there is quite a bit of functionality out of the box. Some examples:

• Endpoints can be generated from any model
• Auto pagination
• JSON based search
• Pre-processors and post-processors

So thats a great way to start off accessing the database, and the pagination feature makes sure you don’t end up pulling too much data at once.

But, here is the problem: the database schema was not defined in SQLA. Sigh. But, there is a solution to that as well.

SQL Alchemy Automap

SQLA includes a feature called automap that is able to “reflect” information about your database tables and automatically generate the models. Using this approach, you can now take advantage of the features that SQLA and Flask Restless have to offer.

The code is pretty simple:

application = Flask(__name__)
application.config['SQLALCHEMY_DATABASE_URI'] = connect_str
application.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(application)
Base = automap_base()

metadata = MetaData(bind=db)

Base.prepare(db.engine, reflect=True)

db.session.commit()

BuildingPermits = Base.classes.building_permits
Census = Base.classes.census
CensusMarginOfError = Base.classes.census_margin_of_error
Crime = Base.classes.crime
DcTax = Base.classes.dc_tax
Project = Base.classes.project
ReacScore = Base.classes.reac_score
RealProperty = Base.classes.real_property
Subsidy = Base.classes.subsidy
Topa = Base.classes.topa
WmataDist = Base.classes.wmata_dist
WmataInfo = Base.classes.wmata_info

models = [BuildingPermits, Census, CensusMarginOfError, Crime, DcTax, Project, ReacScore,
          RealProperty, Subsidy, Topa, WmataDist, WmataInfo
          ]

db.init_app(application)

manager = APIManager(application, flask_sqlalchemy_db=db)

for model in models:
    # https://github.com/jfinkels/flask-restless/pull/436
    model.__tablename__ = model.__table__.name
    manager.create_api(model, methods=['GET'])


@application.route('/')
def hello():
    return("The Housing Insights API Rules!")


if __name__ == '__main__':
    application.run(host='0.0.0.0', port=5000)

That chunk of code above is all the code you need to reflect your current tables into the SQLA model and serve up the API using Flask Restless. Pretty badass if you ask me. I’ll walk through it a little bit to describe what is going on.

db = SQLAlchemy(application)

is Flask Restless wrapper around the basic SQLA engine creator. You pass it your Flask application object.

Base.prepare(db.engine, reflect=True)

here is where you tell SQLA automap which database to use, and that you want it to reflect your current database tables.

BuildingPermits = Base.classes.building_permits

here is where you pull the auto generated model out of Base.classes and assign it a model name.

manager = APIManager(application, flask_sqlalchemy_db=db)

create a APIManager Flask Restless API.

for model in models:
    # https://github.com/jfinkels/flask-restless/pull/436
    model.__tablename__ = model.__table__.name
    manager.create_api(model, methods=['GET'])

For this chunk of code, we are creating a basic GET endpoint for all of the models defined above. The line above it model.__tablename__ is a workaround for an issue that will be fixed in version 1.0 of the code.

Conclusion

If you need a quick and dirty API on top of your SQL database, look no further than Flask and Flask Restless. It’s a great way to get started. However, you still may have to define some custom endpoints, since Flask Restless doesn’t do everything. However using the ORM approach to create your endpoints probably leads to more maintainable and more clearly written code.

My question to the devs out there is this: How does this approach compare to the Django ORM? I know Django has a lot of capability right out of the box, and has its own built in ORM, and Rest API plugin. I’m curious to compare it to the Flask/SQLA approach in terms of ease of use, flexibility, and overall capability.