Adan

The problem

Adan (Twi for “houses”) is for people planning a home in Ghana: self-builders, homeowners, anyone who wants to see a room before paying for it. CAD tools assume you are an architect. Adan assumes you aren’t.

The bar I set: someone with no design experience furnishes a small house and sends a friend the link in under fifteen minutes, with no tutorial.

The shape of it

You draw walls from above. Adan finds the rooms, joins the corners, and lets you place doors, windows and furniture. Switch to 3D and the same design rises into a dollhouse you can edit, walk through in first person, or photograph with a path tracer running on your own graphics card. Changes sync live between collaborators, with an offline copy kept in the browser.

Decisions that mattered

Strict boundaries, enforced by a machine. The code is split into domain, application, infrastructure and interface layers, with dependencies pointing inward only. That isn’t a convention people are trusted to follow: a dependency checker in CI fails the build if the domain imports infrastructure, or if one area reaches into another without going through its public interface.

Let collaboration be messy, then tidy up. Live editing merges concurrent changes outside the domain’s control, so two people can briefly produce a shape the rules don’t allow. A deterministic normaliser repairs the structure after every remote merge, so the merge library never needs to understand houses.

Checks inform; they never block. Building checks point out problems in plain words, and Adan never calls a design “safe”, “approved” or “compliant”. It isn’t a structural engineer, and pretending otherwise would be a lie with consequences. Each suggested fix is tried on a copy before it is offered, and the checks run in a Web Worker so drawing never stutters.

One language end to end. TypeScript everywhere means the same rules engine runs in the browser and on the server.

Tests are a contract. Test files that existed at a release are never edited afterwards; new behaviour gets new tests. By the time the plan-to-3D transition shipped, the suite had 2,382 tests.

A size budget for every release. Each release may grow the main bundle by only about 4 KB. New features load lazily, and CI fails a release that goes over.

The hard parts

• Roofs. A roof belongs to the rooms on a level that have nothing above them. Hip roofs come from a straight-skeleton construction; awkward shapes fall back to a hip, and anything too complex falls back to flat with a note saying why. Roofs are identified by their rooms, not their walls, so they stay put while you move a wall, and undo brings back a roof an edit had hidden.
• The moment it becomes 3D. Switching views morphs the plan into the house: walls rise from the centre, the camera tilts, furniture settles into place. The animation runs on the clock, not on frame counts, because on a software renderer frames can take forty times longer and a frame-counted animation would crawl.
• A silent failure. After a release, textures quietly stopped loading for some users. The texture decoder ran in a worker created from a blob, which inherited the page’s security policy and failed without an error. The fix was a same-origin worker with its own policy and a timeout, so a failure can never be silent again.
• Photographs from code. Photo mode path-traces the scene on the user’s own GPU, so there is no server render farm. A test render of one realistic room came first, before any product work, to find the traps early.

What shipped

A complete home designer that runs in the browser:

• Plans: walls that join cleanly, rooms found automatically, and doors and windows in several types.
• Building up: up to four levels joined by stairs, columns and beams, and roofs in four styles.
• Furnishing: 124 furniture pieces and 20 surface finishes from open-licensed libraries, plus paints and your own saved colours.
• Checks: plain-language building checks with fixes you can try before you accept them.
• Seeing it: a 3D view under realistic daylight, a first-person walk-through, and path-traced photos kept in an album for each project.
• Sharing: a read-only link for anyone, live editing with collaborators, and an offline copy in the browser.

It’s live at adan.crudxpert.com. Open it, draw a room, and walk into it.