Jacob Quatier

Squinch - Architecture Diagrams Your AI Agent Can Draw

Sun, 04 Oct 2026 19:00:00 +0000

Every project I’ve worked on has had The Diagram. You know the one. Somebody spent an afternoon lining up boxes in a drawing tool, it got pasted into a wiki, and six months later it’s wrong in three places and nobody remembers where the original file is. I’ve been that somebody more than once.

There are a ton of tools out there for this already: drag-and-drop editors, text-based diagram languages, full-blown architecture modeling tools. I’ve used a lot of them, and they’re all good at what they do. But I always found myself looking for something else. I wanted the diagram to live in git next to the code. I wanted it to look like something I’d actually put in a design review. And lately I wanted my AI coding agent, which already knows the architecture, to just draw it for me. I never found one tool that did all of that, so I built it. Enter Squinch.

Built for AI agents first

Most diagrams-as-code tools were designed for humans to write, and AI got bolted on later. Squinch went the other way around. It ships as a skill for your AI coding agent (Claude Code, Codex, Cursor, whatever you use), and the language was designed so an LLM can write it fluently. When something’s wrong, squinch check doesn’t just say “syntax error.” It tells you where the problem is, what’s wrong, and usually how to fix it (did you mean ...?), and it can do all that in JSON. So the agent writes the model, checks it, fixes what the checker flags, and renders it. In practice I describe the system in a paragraph and get back a diagram I don’t have to redraw.

One model, every altitude

This is the part I’m most excited about. You write the model once, and every system automatically gets its own zoomable view. The landscape shows each system as a card, and clicking one opens up its internals while its neighbors stay on screen as muted context. You can also tag things (say #pci) and get a view that’s just the PCI stuff for an auditor. All the views come from the same source, so they can NOT disagree with each other.

Here’s a small example:

system orders "Orders API" {
  api    = aws/api-gateway "API Gateway"
  save   = aws/lambda      "Save Order"
  db     = aws/dynamodb    "Orders Table" datastore
  notify = sys/webhook     "Notify Webhook" external

  api -> save
  save -> db "put item"
  save -> notify "order created" { animate: comet }
}

That’s it! No boxes to drag, you get real AWS icons, and that little dot riding the webhook line is just animate: comet.

It actually looks good

I wanted these to look like something you’d be proud to put in front of people, not grey boxes with labels on them. Squinch ships with about 1,350 real vendor icons (AWS, Azure, Google Cloud, Kubernetes, plus a big set of product logos). Dark mode is designed rather than just inverted. You can export SVG, PNG, or one interactive HTML file with click-to-zoom and a presentation mode that works without a server.

It lives in git

Rendering is deterministic, so the same input always produces the same output. The .squinch file sits next to the code it describes, and a GitHub Action fails the build when a committed diagram has gone stale. My favorite part is that squinch diff tells reviewers what changed in the architecture (“edge added: checkout → fraud”) instead of showing a thousand lines of SVG path data.

Why “Squinch”?

A squinch is the little corner arch that lets a round dome sit on a square room. It’s the piece of architecture that makes mismatched structures fit together, which felt about right. =)

Summary

So yeah, if you’ve ever been stuck maintaining The Diagram, give it a try. It’s still pre-alpha, so expect some rough edges. Getting started is one command (npx squinch skill), and then you just ask your AI agent for a diagram. Check out squinch.cc, or try it in the playground without installing anything. Enjoy!

The Meter

Tue, 02 Dec 2014 04:12:00 +0000

The whole idea of this project was to create a giant meter to show website response time almost like a speedometer would. The result is something that’s both fun to watch and provides a meaningful ‘heartbeat’ of current status. After several revisions and different designs along the way, I ended up with what you see here.

Construction & Design

The meter is carved using my CNC machine from 1/4” bi-color HDPE (12 inches square). This is a great material to cut signs or other carvings with because anything carved out is the alternate material color, so there’s no painting/masking/re-painting needed. The needle is cut from 1/8” orange acrylic which worked great for the speedometer theme. For mounting the micro servo, I designed a hole matching the shape of the outer plastic casing which the servo I chose had (see parts list for a link). I designed the whole thing using Inkscape and Easel, mainly because they are free and fairly easy to use. Check out my bill of materials if you are interested in using the same HDPE and acrylic.

View my design & bill of materials

Electronics

I decided to power the meter using the Arduino Uno microcontroller since it handles servo control really well. The Raspberry Pi would be another option, but I’ll detail the Arduino setup for now. My implementation also uses a few LED displays to display detailed metrics, but the servo is the main piece you need. Here’s a quick parts list:

Arduino UNO
micro servo motor
2x Adafruit Quad Alphanumeric Display - Blue 0.54” (optional)
Adafruit Bicolor LED Square Pixel Matrix (optional)
misc jumper wires
screws, scrap wood for test cuts, etc.

Code

Construction was by far the longest part of this project. The code ended up being pretty simple since it’s just rotating a servo using a PWM output and writing values to LED displays over i2c. The nice thing is that the implementation can be changed to support any kind of metric or API that is desired. For example, instead of web response time you could make a meter for monitoring CPU utilization on a server or even your own desktop. I’ve posted all of the code required to get this working, along with more detail about the implementation on GitHub under servometer. Enjoy.

Spring MVC Mapped Interceptors

Tue, 16 Jul 2013 05:38:00 +0000

Interceptors in Spring MVC are a great way to add logic that needs to execute for every request to your servlet. The nice thing is that you can have logic that executes BEFORE and/or AFTER the request is handled by your controller, which is done by overriding the preHandle and postHandle methods in the HandlerInterceptor interface that Spring provides.

The one problem in the past with using interceptors was that there wasn’t a good way to exclude them from running for certain requests. For example, you might have a specific service that doesn’t need to run that additional logic in your custom interceptor so it’s just adding unnecessary execution time.

Enter Spring 3.2 and we now have a great way of selectively including or excluding interceptors from running based off a mapping system. It’s called Mapped Interceptors, and it uses Ant path matching to see if a request path matches the included or excluded paths. Check out the Spring documentation for more detail. Here’s an example:

XML configuration:

<mvc:interceptors>
  <mvc:interceptor>
      <mvc:mapping path="/**"/>
      <exclude-mapping path="/foo/**"/>
      <bean class="com.jacobquatier.MyCustomInterceptor" />
  </mvc:interceptor>
</mvc:interceptors>

Java configuration:

@Configuration
@EnableWebMvc
public class MyWebConfig extends WebMvcConfigurerAdapter
{
  @Override
  public void addInterceptors(InterceptorRegistry registry)
  {
    registry.addInterceptor(new MyCustomInterceptor())
            .addPathPatterns("/**")
            .excludePathPatterns("/foo/**");
  }
}

Anyway, because the path matcher uses Ant paths, it’s pretty easy to include/exclude anything you want.

One thing you might want to watch out for is that Spring automatically detects any beans of type MappedInterceptor and registers them in your servlet. So, if you have multiple servlets with some shared configuration/beans, any MappedInterceptor bean that’s sitting in the context will get picked up and be put in the list of interceptors that get run. This behavior can be overridden by subclassing the handler mapping and changing the detectMappedInterceptors method. See AbstractHandlerMapping for more information.

Freemarker and Exception Logging

Thu, 09 May 2013 03:54:00 +0000

Freemarker is a pretty nice templating language for Java-based servlets, especially if you are looking for an alternative to JSP pages. One problem with it, or “feature” I should say, is that it puts a pretty large stack trace in your logs whenever it encounters an error rendering a template. In my travels, I’ve seen a single missing null-check fill up server logs rather quickly for pages that are hit often (especially if there is looping going on in the template). I decided it wasn’t really helping me at all to have these in the logs, so I wanted to turn them off, at least on the live site.

Turns out all I needed to do was extend the FreemarkerConfigurer class that Spring MVC uses to instantiate the Freemarker view resolver. This is important because you need to set up the logger library before any of the Freemarker classes load up. Thankfully, there’s an afterPropertiesSet() method that you can override for this purpose. Here’s an example:

public class MyAwesomeFreemarkerConfigurer extends FreeMarkerConfigurer
{
  private boolean loggingEnabled = true;

  @Override
  public void afterPropertiesSet() throws IOException, TemplateException
  {
    // disable freemarker logging if the bean is configured as such
    if(!loggingEnabled)
    {
      resetFreemarkerLogging();
    }
    super.afterPropertiesSet();
  }

  public void resetFreemarkerLogging()
  {
    try {
      freemarker.log.Logger.selectLoggerLibrary(Logger.LIBRARY_NONE);
    } catch (ClassNotFoundException e) {
      System.out.println("Failed to disable Freemarker logging =(");
    }
  }

  public void setLoggingEnabled(boolean loggingEnabled)
  {
    this.loggingEnabled = loggingEnabled;
  }
}

That class will disable all Freemarker logging (Logger.LIBRARY_NONE). You’ll notice I added a property which allows me to enable/disable logging via bean configuration. This means I can turn logging off in the live site, but leave it on for test and development. You could also use this approach to set the logger library to whatever logging framework you use. By default, Freemarker will use the first logging library it finds, per the documentation.

Anyway, depending on your situation you might not want logging turned off completely. But, in my case it was far too noisy to provide any value. The smallest template error made the logs a nightmare since the pages get hit so often. Template errors are easy to overlook (especially if they only happen when dynamic data is in a certain state), and I need my server logs readable at all times. Also, if a problem arises with a template, I can test it in an environment that has Freemarker logging turned on and I’ll see the stack trace. Hopefully by keeping logging enabled in test and dev, I get the best of both worlds. We’ll see! =)

Hibernate Envers - Audit Logging Made Easy

Sun, 21 Apr 2013 05:26:00 +0000

One of the requirements for my most recent project was to provide a detailed audit trail for any changes made to my database entities through the administration panel. I needed to keep track of what was changed (at a field level) and who made the change. There are a ton of ways to do this, including triggers, plain old system logging, and homebrew audit tables. But, I decided to look around for something cooler than that. Enter Hibernate Envers. What’s nice about it is configuration is basically a one-liner (for the most part), and it plays nice with my existing all-annotations JPA2 Spring MVC project. All you need to do is mark your entities with the @Audited annotation, and it takes care of the rest for you. Here’s an example:

Maven dependency (pom.xml):

<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-envers</artifactId>
  <version>4.1.9.Final</version>
</dependency>

Entity:

@Audited
@Entity
@Table(name = "PERSON")
public class PersonEntity implements Serializable
{

  @Id
  @GeneratedValue( strategy = GenerationType.AUTO )
  @Column( name = "ID" )
  private Integer id;

  @Column( name= "FIRST_NAME")
  private String firstName;

  @Column( name= "LAST_NAME")
  private String lastName;

}

And, that’s it! So what does this do? Let’s look at the tables that Hibernate will generate:

create table PERSON_AUD (
    ID number(10,0) not null,
    REV number(10,0) not null,
    REVTYPE number(3,0),
    FIRST_NAME varchar2(255 char),
    LAST_NAME varchar2(255 char),
    primary key (ID, REV)
)

create table REVINFO (
    REV number(10,0) not null,
    REVTSTMP number(19,0),
    primary key (REV)
)

alter table PERSON_AUD
    add constraint FK_PERSON_AUD -- I renamed the system generated name... ;)
    foreign key (REV)
    references REVINFO

Basically, with the default configuration, you end up with another table with the same name as your existing table but with “_AUD” appended on the end. You can also change the generated name of the tables if you want. It has the same fields as your entity table but adds a REV number to keep track of the revision, and a REVTYPE to indicate an addition, modification, or delete. Read more about this in the documentation. Each time any field is changed on one of your entities an entry will be written to this table saving the state, which allows you to easily see what changed between 2 revisions. Envers also includes utilities to query over these tables to find all the revisions for a certain entity.

Generating Schema DDL

By the way, if you are looking for an easy way to generate the DDL for your entities AND your envers tables, here’s some code. I had trouble finding a Maven plugin that supported BOTH Hibernate 4 and Envers, so this is what I did:

Configuration config = new Configuration();

// don't forget to get the right dialect for Oracle, MySQL, etc
config.setProperty("hibernate.dialect","org.hibernate.dialect.Oracle10gDialect");
config.addAnnotatedClass(PersonEntity.class);

SchemaExport export = new EnversSchemaGenerator(config).export().setOutputFile("person-schema.sql");
export.execute(true, false, false, false);

Summary

So yeah, Hibernate Envers is an awesome time-saver if you need an audit trail. Keep in mind that these tables can grow quickly in size if you have a lot of changes to your entities happening regularly. But otherwise, I’m really glad I found this since it was just what I needed. Enjoy!

Facebook LIKE buttons without the count

Mon, 01 Apr 2013 07:22:00 +0000

I’m not a huge fan of putting Facebook LIKE buttons on everything, but there’s some cases where it makes sense. It’s also advantageous to use the code that Facebook provides for buttons rather than building your own, because it handles all the different states a user could be in (logged in, logged out, already liked, etc.). It allows users to like your content on Facebook without leaving your website, so that’s kind of nice as well.

What is NOT nice is that if you use their button, they force you to show the number of likes. There isn’t a flag you can pass in (like Twitter has) to not show the count next to the button. Here’s a quick hack to hide the count by setting the width of the IFrame accordingly.

/* CSS Hack for hiding the LIKE count */
div.fb-like span {
  display:block;
  width:48px !important;  
}

div.fb-like iframe {
  width:48px !important;
}

div.fb-like iframe.fb_iframe_widget_lift {
  width:450px !important;
}

It’s important to note that the 3rd rule is to set the width correctly when the comment model window appears (Facebook allows you to comment on what you just liked). Without this, only the first 48 pixels of that modal would be visible.

This will probably break at some point if Facebook decides to change their API like they often do, but this seems to work right now.