Sharpee's Architecture Solidifies

Rewind

A little over three years ago I started playing around with elements of a new IF Platform built in C#. The vision included a graph data store, text service, and not much else. Then when ChatGPT arrived, I was able to make some progress, especially learning new patterns, but those early models were very bad. Each time a new model was introduced, I'd start over and see where it would lead, but the capability of the model, the context window, and the amount of time given was nowhere near enough to handle a complex system.

When Anthropic released its first model under Claude, I switched over to their paid plan. The context window was still a serious limitation and the interface was limited. You could upload your files to a project, but eventually you'd reach the limit and have to figure out ways to cheat that limitation. Eventually I paused, realizing the model and context windows were close, but not good enough.

I also struggled to get Claude to write C# well and so I asked it why this seemed to be a problem. Shockingly, it admitted that C# was a second-tier language in its database and that the optimal languages were Typescript and Python. SO after doing some R&D and switching to Typescript, it became clear that Typescript was a better platform in any case. And if I want, I can do a secondary project to convert a working Typescript version back to C#.

Then Claude Opus 4 arrived as well as higher subscriptions. I started with Opus 4, but almost instantly upgraded to the MAX $100/month subscription. I also downloaded Claude Desktop which allows you to use MCP (Model Context Protocol) which is an obscure method of talking to "other things". The built-in MCP is file_system, which allows Claude Desktop to see a directory on your local file system. I'd tried using before the MAX upgrade, but it was cranky. There's a known bug where Claude will respond to a prompt, then wipe out your prompt and its response before you can read it. Upgrading to MAX has mostly eliminated this issue and restarting the app seems to clear it up.

With Opus 4 and MCP and MAX to Success

This combination is the game changer for generating code with GenAI. There are still a lot of general engineering disciplines you have to adhere to, but you can get extraordinary results when you learn these guardrails.

The guardrails include:

• Write design documents with development standards.
• Write ADRs (Architecture Decision Records)
• Repeatedly request "professional" assessments. (You are a professional IF Platform Designer and Developer but also know my vision)
• State your vision and criteria clearly to Claude. For Sharpee, this was:
  • queryable world model
  • event source story and system messages
    • story messages will allow a post-turn text service to construct output
    • system messages show everything that happened within the turn (parser, validation)
  • loosely-coupled architecture stack
  • fluent user DSL for authors
  • no virtual machine
  • typescript (with some dev standards like don't use enums)
  • no unit tests until a layer/module is "design stable"
• Repeatedly request check lists of bursts of work to keep the model on track. I can stress this enough. These models will run amok if you don't contain them. Even with these guardrails, Claude will sometimes get confused about "where we are" and start undoing or reworking solved problems. Luckily it's very good when you scold it and it will revert changes correctly.

Today

There is still a lot of work to do. I have no indulged in the Forge DSL authoring layer yet, but I occasionally will ask Claude to validate what something might look like and that we're not breaking our vision. The Text Service is still a theory, though I am confident the event source will be more than sufficient to emit text in standard IF form. The challenge of combing text will be an interesting effort.

The diagram is slightly out of date, but it's close enough to share. I don't see any major changes at this point. The internal pattern of Validate->Execute and external pattern of Parse->Validate-Execute seem to offer an elegant design.

Traits and Behaviors

One thing that came through in the design process was stepping away from "objects" and moving to something different. From this Traits and Behaviors were born. Traits are things in the traditional sense. So RoomTrait is what you add to an Entity to make it a Room. The RoomTrait contains the data. RoomBehavior contains the logic. Claude and I have thoroughly examined how this extends to story development and its quite beautiful.

Summary

I would say Sharpee is about 75% complete with no major architecture changes in its future. The remaining work is integration, testing, and developing the Text Service and a few sample games.