GeoSoul lets anyone design a garment in 3D in the browser, publish it, and earn on every sale. No stock, no minimum order, nothing upfront. A creator sets their own price and keeps a share of the profit; the platform handles printing and delivery.

That is the brand. The system underneath it is a decoupled monorepo — an Angular SPA, a NestJS API and PostgreSQL in containers — carrying a storefront, a creator economy with wallets and payouts, an admin back office that touches nearly every module, a self-hosted observability stack, and a second product: the 3D designer, sold as an embeddable service to other merchants.

I founded it and I built it. What follows is the engineering, in the order I would want to read it: the shape of the system, then the two hard parts (painting in 3D, and moving 3D models around without killing a phone), then the unglamorous half that decides whether any of it survives contact with real customers.

Angular SPA to a NestJS API over a single REST surface, TypeORM to PostgreSQL. Frontend and backend are independently built and deployed containers and share no code — the only contract between them is the API, reverse-proxied under one prefix.

The backend is a feature-module pattern: each domain is a module, a controller, a service, an entity and its DTOs. Controllers stay thin — HTTP and validation only. Business logic lives in the service, persistence in a repository, and the root module wires them together with the global pipes and guards.

The frontend has no NgRx and no Redux. State is RxJS and singleton services — one injectable per domain, subject-backed where it is genuinely stateful, like auth and cart. For an application this size a store would have been ceremony. The one place that actually needed a store — the 3D designer — got its own, and only its own.

Routing is fully lazy: every route loads its component on demand. Translations load synchronously at startup through an initialiser, so they exist before first render and no screen ever flashes its own translation keys at a visitor.

Controllers stay thin. If a controller knows why, it is in the wrong place.

The marquee feature. You load a garment and you paint on it — directly on the 3D surface, with layers, brushes, text and images — and what comes out is a texture the print pipeline can use.

Engine and state are deliberately two services. One owns the Three.js scene, the 2D canvas and everything that touches a pixel; the other owns layers, tools, brush settings, blend modes and selection. Rendering never reads component state, and the store never touches a canvas. That separation is what makes the layer system testable and the renderer replaceable.

A stroke does not draw into its layer. It draws into a scratch canvas while tracking a growing bounding box of everything it has touched, and only that rectangle is composited back. Compositing is coalesced to once per frame — dragging a layer queues the pointer position and flushes it on the next frame rather than recompositing on every pointer event, which at a high-DPI pointer rate is several times per frame.

Blend modes map onto the canvas composite operations, so a layer stack behaves the way a designer expects without a second rendering path. Background removal on uploaded images runs client-side, so an image never has to leave the browser to become a layer.

Painting across a seam — the problem that has no obvious answer.

A 3D garment is a flat texture wrapped onto a surface, and that surface is cut into islands. Two points can be neighbours on the garment and sit at opposite ends of the texture. Drag a brush across that boundary and the naive implementation joins them with a straight line in texture space — a stripe smeared clean across the garment from a stroke you made in one place.

Detection compares how far the pointer moved in UV space against how far it moved in world space. If it barely moved in 3D but jumped in UV, it crossed an island boundary in place: unambiguously a seam. Otherwise the ratio of the two is weighed against the model's own density.

That density is not a constant, because every model is unwrapped differently. On load the engine samples up to four hundred triangles per mesh, computes the square root of UV area over world area for each, and takes the median. Median rather than mean: a handful of degenerate triangles would drag an average, and the threshold would then fail on exactly the models with the messiest unwraps.

The threshold is model-relative. A magic number would have worked on the t-shirt and failed on the cap.

Thirteen garments, Draco-compressed GLB with WebP textures. Compressed they are small. Decoded they are not, and the gap between those two numbers is the whole problem.

The interesting constraint here was one I could not remove. The garments are heavy and I did not model them — cutting triangle counts, rebuilding UVs, baking detail into normal maps is 3D asset work, and it is not my craft. The obvious lever, making the files smaller, was never in my hands, and a month spent pretending otherwise would have produced worse models and a later launch.

Everything after the file arrives was in my hands. So I went around the problem instead of at it. The weight of a single model is fixed; the number of them decoded at once is not, and that one is entirely a software question.

Those are the production models, loaded by the same pipeline the product uses, and the readout is measured in your browser rather than typed into this page. Switch garments and two numbers diverge: what is resident now, and what would be resident if this viewer cached decoded scenes instead of disposing them.

That second number is the bug. The first version of the model service memoised parsed results — the obvious optimisation, and exactly the wrong one. Every garment a visitor touched stayed decoded, and a mid-range phone died four garments into browsing.

The fix was to memoise the buffer and not the scene: cache the compressed bytes, decode on demand, and dispose the previous model before the next one is built. Peak memory becomes one decoded model, however long somebody plays.

The file never got smaller. It just stopped mattering how big it was.

The generalisable part is not the caching strategy. It is that an optimisation does not have to happen where the problem is. The problem was in the asset pipeline, where I had no reach; the fix went in the service layer, where I had all of it.

Serving is access-controlled rather than a public path — models go through a service that decides who may fetch which asset. In the embeddable viewer they are additionally cached per browser, so a returning shopper fetches a garment once rather than once per page view, and the usage ledger counts a model served roughly once per browser instead of once per visit.

Bloom over a transparent canvas can return a fully opaque alpha. On the page that reads as a black rectangle sitting exactly where the glow should be — worse than no bloom at all, and it never shows up in the isolated demo, only once composited onto the real page. Every workaround costs either a second render target or the transparency the hero depends on, so the pass was dropped and the same read came out of point size and falloff instead, for nothing.

Verify an effect on the page it ships to, not in isolation.

Moving the particle cloud from additive to normal blending broke it in a way that took a while to name: the same alpha has to go up for the scattered state and down for the bound one. Scattered points need weight or the cloud disappears; bound points need transparency or the cloud occludes the garment it is in the middle of forming. Alpha is not a constant, it is a function of assembly — and the crossfade between those two tunings is the effect.

The choreography began scroll-driven across three viewport heights. A homepage hero is not three viewport heights, so the driver had to go, and pointer-led with an idle wander replaced it. Two rules came out of that and both generalise: read relative pointer deltas and never absolute position, because absolute mapping snaps to wherever the cursor entered frame and never reads as answering the gesture; and spend one gesture per axis, because scrub and spin both want horizontal drag, so the autonomous motion has to be the one that never stops.

The garment viewer above obeys both of those rules. It is the same lesson, applied to a different piece.

House catalogue and creator designs live in the same list. A shopper should not have to know who made a thing in order to find it, so discovery is one grid and the seller is an attribute of the item rather than a separate section of the site.

The house identity is deliberately not a row in the brands table. Items with no brand render under a single admin-editable configuration row instead. Modelling the platform as just another brand would have meant every money path, every payout, every ownership check and every analytics query had to special-case one magic row forever.

Paid placement splices a featured slot into the default sort on the first page, always labelled as such. The policy lives in exactly one file in the brand module and the public read paths call it; they never re-implement it. A placement rule duplicated across two query builders is a rule that will eventually disagree with itself.

Two access paths, kept apart on purpose: owner-only backs every money surface; team membership backs the catalogue.

A creator registers a brand, publishes designs, accrues to a wallet, and requests a withdrawal. Around that sit a team roster on the brand, a commission channel where a buyer and a creator negotiate a custom piece with messages and attachments, and a referral programme.

The referral module owns no balance. It owns the invite links, the who-invited-whom edge, and its own ledger; the money itself lands in wallets like every other kind of earning. It is imported by auth and by orders and never the other way round, so the dependency arrow only ever points one direction and the module can be reasoned about without reading the two that use it.

Ownership and membership are different questions and are answered by different code. The owner-only lookup backs every money surface; a separate access check backs the catalogue. Collapsing them into one convenience helper would have quietly let a team member reach a payout screen.

Two tokens, not one, because they answer different questions.

The refresh cookie is scoped to the two routes that can spend it, so the browser never attaches it to the couple of hundred other calls the SPA makes. Its same-site policy is what makes the refresh endpoint safe from cross-site submission without needing a separate anti-forgery token.

Refresh tokens are single-use and rotating. A replay inside a short grace window is treated as what it almost always is — an honest race between two tabs. Outside that window it is treated as theft, and the entire token family is killed.

One piece of deliberate paranoia: when the access-token lifetime moved, the configuration key was renamed rather than reused, and the module logs a warning at boot if it finds the old one. A stale day-long value sitting in a deployed environment file would otherwise have silently overridden the new twenty-minute default, and nothing anywhere would have looked wrong.

Renaming the key is the migration. A config value that can silently win is a bug you cannot see.

Admin two-factor is TOTP and enforced by default — but enforced at the admin boundary, not the authentication boundary. An unenrolled admin can still sign in and use the site as an ordinary user; what they cannot do is anything administrative, and every admin route refuses them until they enrol.

Blocking them at login instead is a bootstrap deadlock: enrolment needs a session, and no session means no enrolment. A lockout with no way out of it is not a security feature. This is the decision most likely to be helpfully 'fixed' by someone who has not thought it through, which is why it is written down next to the code.

Enrolment is a three-state machine, and the middle state is the entire point. The secret must be stored before the user has proved they can generate a code from it, because the QR they are looking at has to be the one we later check against. If the enabled flag flipped at that same moment, anyone whose authenticator silently failed to save the entry — or who closed the tab mid-scan — would be permanently locked out of their own account by a secret they do not possess. The flag only flips on a verified code.

Three bypasses were closed on the way, and each one alone would have made the whole feature decorative:

A second factor is only as strong as the paths that do not ask for it.

Input is validated by a global pipe that strips properties nobody declared and rejects payloads that carry them outright, so a field that is not in a DTO cannot reach a service. Output leaves through a role-aware serializer that honours exclusion decorators everywhere and re-exposes group-gated fields only to admins — which means trimming personal data is the default on every endpoint rather than something each one has to remember to opt into.

Passwords are bcrypt with a real complexity policy rather than a length minimum. Lockout is dual-scope, per account and per address, with exponential backoff that decays after a quiet day so yesterday's typos do not punish today's login. The counter is incremented inside a transaction that holds a row lock, because credential stuffing is concurrent and a read-modify-write without one lets parallel guesses clobber each other's count.

Rate limits are counted per real client address by a dedicated guard rather than trusting a proxy header blindly, and the edge adds its own on top. Security headers come from the standard middleware set including strict transport security. The cross-origin allow-list is explicit and never falls back to development defaults in production.

Secrets live in the environment and nowhere else; only example files are in version control. Boot fails hard rather than starting insecure if the signing secret is too short or the database password is missing, and a secret scanner runs in CI over the full history rather than just the diff.

Boot should fail loudly rather than start quietly wrong.

The hardening lives in that one function rather than in a pipe, a decorator or five separate upload configurations, because every path already funnelled through it. A call site cannot forget to apply it, and a new upload route inherits it for free.

The order is not arbitrary. Scanning runs on the original bytes because re-encoding destroys the only copy that still contains what the user actually sent. Sniffing decides what a file is from its content, never from the type the client claimed — that is a hint, not a fact.

What re-encoding buys that a magic-byte check does not: metadata, because a phone photo carries the coordinates it was taken at, and before this a buyer attaching a photo to a support ticket was handing the seller their home address. Polyglots, because a file can be a valid image and a valid script at the same time — the magic bytes at the front say image and the payload rides in a trailing chunk, and it does not survive being decoded to pixels and written back out. And decompression bombs, which are refused from the header before a single pixel is decoded.

The starting position was worse than the roadmap thought. The validation function took a file path and read from disk — and every upload route in this application holds the bytes in memory, so there was never a path to read. It had zero call sites. It had never run once.

Three traps followed, and each would have left the feature decorative while looking finished from the outside. A direct-to-storage upload path whose bytes never reach the API at all, and therefore bypass every check above it — dead surface that was still reachable, now off unless deliberately enabled, and turning it on means first solving validation for a file the API never sees. A default import of a CommonJS imaging library that type-checks, builds clean, and is undefined at runtime, so the app would have crashed on the very first upload. And a virus scanner whose replies are NUL-terminated, where trimming whitespace does not strip NUL, so every parse fell through to an error branch that logged and then allowed the file — including a live test sample.

A scanner is not working until you have watched it refuse something it is supposed to refuse.

The schema is never auto-synchronised — that setting is off, always. Changes are apply-once SQL migrations, and the applied ones are recorded in a ledger.

Migrations apply in the order a manifest lists, not alphabetically. Alphabetical is not a dependency order, which is precisely why building from an empty database used to fail on the first file. Filenames are never changed to encode order either: the ledger keys on the filename, so renaming an applied migration makes it look brand new, and the runner would re-apply every backfill inside it against live production data. The order goes in the manifest instead, and if a new migration is missing from it the runner refuses to run rather than guessing.

Schema and data are different things. A deploy used to write rows through three doors nobody had counted: the database entrypoint script inserting placeholder content merely by starting a container, migrations carrying inserts of their own, and the API upserting reference rows on every boot. None of it was destructive, but it meant a deploy could never be reasoned about as a pure schema change — and each of those statements was one careless edit away from overwriting something an administrator had set.

'No data statements in migrations' is the wrong rule, though, because it breaks them. There are three kinds and only one is seeding. A backfill populates the column the migration just added, and the schema change is simply wrong without it. A repair deletes duplicates so that the unique index below it can be created at all — strip it and the migration fails. Seeding inserts content, and that is the one that moves out.

So the enforced rule is narrower and survivable: a migration may touch rows it structurally changed, and may not seed content. Backfill and repair declare themselves with a marker comment, and the runner refuses to apply a migration carrying data statements without one, printing the offending lines.

The word boundaries in that check are load-bearing. A naive match on UPDATE hits the updated_at column present in nearly every CREATE TABLE in the repository — the guard would have rejected everything, including files with no data statements at all.

Seeds are split into what a fresh install is broken without and what is only sample content, and the seed script is not called by deploy and never will be. Primary keys are UUIDs, every raw query uses placeholders, and the database listens on loopback only.

The suite is integration-first. Nineteen spec files stand a real application against a real PostgreSQL rather than mocked repositories, because almost everything that can go wrong in this system is a query, a transaction or a guard — and none of those exist in a mock.

What they cover reads like a list of the things that would actually hurt. Money under concurrency. PII exposure — a test whose whole job is to assert the serializer does not hand a field to the wrong role. Authentication lockout. Then wallet consolidation, order-to-earnings, referral payouts, plan limits, member discounts, brand billing, catalogue placement, multi-brand ownership, the audit trail, compliance, and the SaaS portal's principal model.

money-concurrency and pii-exposure are the two suites I would keep if I could keep only two.

The pipeline is split across three workflows on purpose. The main one typechecks, runs the suite against a database it stands up itself, builds the frontend for production and runs Lighthouse. A dependency audit runs on its own weekly schedule and blocks on critical findings. A secrets sweep runs over full history, also on its own schedule. Bundling them into one file would mean a vulnerability published on a Tuesday waits for somebody to push.

The production frontend build in CI is passed no secrets at all, deliberately — if the build needs one to succeed, that is a finding, not an inconvenience.

Development, staging and production are separate container stacks from the same repository. A deploy builds both images and brings the stack up behind a reverse proxy handling TLS termination and edge rate limiting.

Uptime monitoring is deliberately external, and this is not a preference. On-box monitoring watches the machine from inside it — so when the machine is what died, whether that is a kernel panic, a network drop, a full disk or a wedged container daemon, the thing that was supposed to page you is down with it. Only a monitor running somewhere else on the internet can tell you the whole box is unreachable.

Errors report to a self-hosted collector and the host reports its own health separately, so an application error and a sick machine do not arrive as the same signal. Outbound email has its own deliverability work behind it, because a marketplace that cannot reliably deliver a password reset does not have a password reset.

Four separate questions, four separate systems, and not one of them shares a compose project with the application.

The isolation is the actual design decision. Each stack is its own compose project with its own network and volumes; it reads container logs the way the docker CLI does, through a read-only socket, and it never touches an application container. The worst a broken observability stack can do is stop collecting.

A monitoring system that can take production down with it is not monitoring. It is a second production.

Product analytics is self-hosted Umami — cookieless, no consent banner to justify. It is shipped and deliberately switched OFF: the site is still behind an early-access gate and marked noindex, so the only traffic today is mine, and tracking it would be measuring myself.

It is also kept carefully apart from the analytics a seller sees. A brand's dashboard shows that brand's own sales and earnings, computed from the application database and scoped to its owner. Umami shows anonymous visitor behaviour, and only to me. Two surfaces both reasonably called “analytics”, answering different questions for different people — and collapsing them is how a seller ends up looking at somebody else's numbers.

The API also reports its own health, including a storage indicator that actually reaches the object store rather than returning a cached opinion about it. A health check that cannot fail is a status light with the bulb taken out.

A nightly database dump, plus configuration and uploads, pushed off the box to object storage. A manual backup also runs before every deploy, which is what makes the worst case theoretical rather than nightly.

Configuration and uploads are content-fingerprinted on every run, so an unchanged snapshot is not written or uploaded at all. The retained configuration snapshots are therefore that many real versions of the environment file, rather than that many identical copies of last week's.

Retention differs between them on purpose. The database rolls on date buckets. Configuration is kept by count, because configuration changes are event-driven rather than nightly: five edits can land in one afternoon and then nothing for months, and a date-bucketed scheme would keep only the last of that day and discard the four intermediate versions you would actually want to roll back to.

A restore that has never been performed is a hypothesis, not a backup. The first one was proved by restoring into a throwaway database and counting rows in it — never into production, and never as a drill that stops at 'the file exists'.

A backup you have not restored is not a backup.

The designer and a showcase viewer are also sold as an embeddable product. A merchant drops an iframe onto their own product page and their customers configure a garment in 3D without ever leaving the shop.

That is one half. The other is a portal the customer signs into: their own staff users, their API keys, their registered origins, their SKUs, their textures, their entitlements and their usage. Tenancy is explicit rather than implied by a column — a tenant, tenant users, per-tenant keys, per-tenant origins, per-tenant theme — and it has its own rate limiting, separate from the marketplace's.

The piece worth stealing is the principal model. Three different things can hold a credential here: a customer's server, a customer's staff member, and an anonymous embed session inside somebody else's page. They are three distinct principal types, named as such, so a guard never has to infer which one it is holding from the shape of a token. Every one of them has an integration test.

The security model is the design. Three credentials, each living on a different side of a trust boundary, and getting that right is most of the work:

A publishable key exists because some platforms leave no choice. On hosted storefronts the merchant has no server-side execution available to them — there is nowhere to hide a secret, and theme files are readable by staff. So the credential is public, and constrained instead: it cannot reach anything that writes, and it only works from a registered origin.

The token travels in the URL fragment and never the query string, because a fragment is never sent to a server: it cannot land in an access log, a proxy cache or a referrer header. The shell reads it once on load and strips it from history immediately.

Framing is permitted coarsely at the HTTP layer and checked per tenant in JavaScript, because the server cannot do the per-tenant check itself — at the moment it serves the document, the token is in the fragment and it does not yet know which tenant is asking.

A limitation you have to discover is a bug. One that is written down is a boundary.

The admin surface is horizontal — it touches nearly every module: orders, users, brands, design review, wallets, payouts, support, commissions, even the translation table. It is guarded at class level rather than per handler, so every route on the controller is covered by one decorator pair and a new one cannot arrive unguarded by omission.

Analytics owns no entity of its own. It is read-only aggregation over what the other modules already store — revenue, top sellers, funnels, payouts — because a reporting module with its own tables is a second source of truth, and a second source of truth is a drift waiting to happen.

The designer funnel is instrumented anonymously: milestone events land in their own small module that owns the ingest route, and the report that reads them lives with the rest of analytics. Ingest and reporting are different concerns with different access rules.

There is no server-side rendering, and the site still has to be shareable. A dedicated module serves the sitemap and renders social preview tags for crawlers specifically — a narrow answer to a narrow problem, rather than adopting SSR across the entire application to solve it.

Reporting reads. It does not own.

Forty-two feature modules do not each earn a chapter, but leaving them unmentioned would misrepresent the system. The ones that carry real weight and did not get one: