Full Stack Challenge: StackCompass
A compass tells you which way you're facing, not where you are. StackCompass takes a build goal and your actual constraints, then returns three structurally different options, the axis that decides between them, and an ADR you can commit.
The word generator handed me COMPASS, and with it an app idea called
EchoBlock: a hyperlocal platform where neighbours pin voice notes to park
benches and passers-by get nudged to listen. It is a lovely concept. I kept
the word and went somewhere else entirely.
A compass is honest about what it cannot do. It will not locate you. It will
not choose your destination. It tells you which way you are currently pointed,
and that is all. I wanted to build something with the same restraint.
Vision and What It Does
StackCompass takes a build goal and the constraints around it, then returns
three structurally different options, a trade-off table scored against the
axes that actually differ, the single axis that dominates the decision, and an
ADR you can commit to your repository.
It is for engineers who are not short of options. They are short of a stated
reason to prefer one. Design reviews stall on "why not the other thing?" and
nobody has written down the axis the choice actually turned on. Later the
reasoning is gone and the team relitigates it.
The tool does not claim to know the right answer for your system. It makes the
axis visible and hands the decision back.
Full Stack Breakdown
The series names five stages: pitch, prototype, MVP, UX, launch. Compressed
into a single sprint they stop being phases and start being a checklist you
run against yourself, repeatedly, in whatever order the work demands.
Pitch. One line, fixed on day one: a compass for decisions, not for
movement. Every scoping question got measured against whether it served that
line. Most did not.
Prototype. Before writing any application code I ran the reasoning prompt
straight through the AWS CLI against Bedrock. If the model could not produce
three genuinely different options, the product had no centre and I needed to
know that early rather than late.
MVP. One flow end to end: intake, three options, trade-off table, ADR
export. Search, tagging and team sharing went to the roadmap immediately. I
said so in my idea comment before writing a line of code, which made it harder
to quietly expand later.
UX. The prototype changed the interface. Constraints moved to the front of
the form rather than behind an "advanced" toggle, for reasons below.
Launch. Static export on Amplify Hosting, with guest access so the app can
be tried without an account.
How You Built It
Validating the model before the product
The first thing I ran was a raw Converse call:
aws bedrock-runtime converse \ --region us-east-1 \ --model-id us.amazon.nova-2-lite-v1:0 \ --messages '[{"role":"user","content":[{"text":"..."}]}]'Nova 2 Lite returned three options that differed structurally rather than in
degree: a managed platform path, a self-hosted queue, and a move to another
cloud. The trade-offs did not all point the same way, which is the property
that makes a comparison table worth reading.
One observation changed the design. When the existing stack was included in
the input, the model rated the third option's operational burden as high
because the team was already on Vercel. That is a relative judgement, and it
vanishes when you remove the constraints. The same question with and without
constraints does not produce better or worse answers. It produces answers of a
different kind. That is why the constraint fields sit at the top of the form
and the button sits next to the line "Constraints are the input, not an
afterthought."
Nova also wraps its JSON in markdown fences regardless of how firmly the
system prompt forbids it. I could have forced the shape with Converse toolUse.
I stripped the fences on the way out instead. That is exactly the kind of
trade-off the app is built to surface, made under exactly the kind of deadline
pressure it takes as input.
The environment variable that cost the most
My shell had
NODE_ENV=production exported. A single npm install pruned the
dev dependencies, and ampx , tsc and esbuild disappeared from
node_modules/.bin . Amplify Gen2 keeps its CLI in devDependencies, so this is
not "type checking stops working". It is "you can no longer deploy".The fix was obvious once found:
NODE_ENV=development npm install --include=dev .Then I carried that prefix onto the next command, and
next build began
failing with this:Error: <Html> should not be imported outside of pages/_document.Error occurred prerendering page "/404".App Router only. No
pages directory anywhere in the project. No import of
next/document in any file I had written. The failing route alternated
between /404 and /500 between runs.I worked through four hypotheses in order: a missing
app/not-found.tsx , the
output: "export" setting, a bug in Next.js 16.3.1, and a corrupt install. I
added the file, removed the setting, downgraded the framework to 15.5.23, and
wiped node_modules along with the lockfile. None of it helped, because none
of it was the cause.The cause was
NODE_ENV=development still sitting in front of next build .
Next prints a warning about non-standard NODE_ENV values, well above the error
and in the register of general advice, which is to say in the register of
things you skim.The fix that stuck was to stop relying on memory:
"build": "NODE_ENV=production next build","sandbox": "NODE_ENV=development ampx sandbox"Worth saying plainly: the Next.js downgrade was unnecessary. I changed a
framework version to chase a symptom that had nothing to do with it, and that
change is still in the repository.
A build that succeeded and a deploy that failed
Amplify Hosting then failed with:
CustomerError: Can't find required-server-files.json in build output directoryReading upward through the log, both phases had succeeded.
ampx pipeline-deploy completed. ✓ Exporting (2/2) was right there.required-server-files.json is emitted by Next.js in SSR mode. With
output: "export" it is never generated at all. Amplify had auto-detected
Next.js at app creation and provisioned the app as WEB_COMPUTE , and the
platform setting outranks baseDirectory: out in amplify.yml .aws amplify update-app --app-id <id> --platform WEBaws amplify update-branch --app-id <id> --branch-name main \ --framework "Next.js - SSG"Both of these errors named a file that did not exist in my project. In both
cases the cause was environment or configuration, not code. That pattern is
now the first thing I check.
Blaming the model for a transport problem
The deployed app then reported: "The model returned a shape this app could not
read." I had written that message myself.
AppSync returns the
AWSJSON scalar as a string. My type guard required an
object, so a perfectly good payload failed the check and my own error text
pointed the blame at Bedrock. Parsing before validating fixed it. Writing an
error message that names a likely culprit turns out to be a way of handing
your future self a wrong answer.AWS Services / Architecture
Layer | Service |
|---|---|
Hosting, CI/CD | AWS Amplify Hosting, static export |
API | AWS AppSync, custom query |
Compute | AWS Lambda |
Reasoning | Amazon Bedrock, Amazon Nova 2 Lite |
Auth | Amazon Cognito identity pool |
Persistence | Amplify Data on Amazon DynamoDB |
The browser calls a custom AppSync query,
compass , which resolves to a
Lambda. The Lambda calls Bedrock through the Converse API, strips the markdown
fences, and returns parsed JSON. AppSync hands it back to the client, which
renders the option cards and trade-off table and generates the ADR as a
client-side Blob download. Nothing is written to S3 for that.Generation is open to guests, deliberately: the app can be tried without
signing up, and nothing about taking a bearing needs to know who you are. An
owner-scoped
Decision model sits in the schema behind Cognito for saved
history, which is the next thing to surface rather than something the current
build exposes. The Lambda's Bedrock permission is granted in backend.ts
against both the foundation model ARN and the cross-region inference profile.What You Learned
Constraints are not an input to the reasoning. Under a model, they are the
reasoning. Ask for background job options with no context and you get a
listicle. Say "three people, two weeks, already on Vercel" and every rating
becomes relative to that. The product design followed from the prototype
rather than the other way round.
Environment variables carried between commands are a category of bug I had not
taken seriously. Both of the failures above that stopped the build share that
single root, and the second cost far more than the first because the error
pointed somewhere else entirely.
When an error names a file your project does not contain, stop reading the
code. A framework fallback has been exposed, and the thing that exposed it is
almost always something you changed about the environment.
Dark mode was the curveball bonus, and it cost almost nothing because the
palette came from the generator I had otherwise ignored. Deep Midnight over
Parchment. EchoBlock got the last word after all.
Shipping one finished interaction beat shipping three half-finished ones. That
decision was made on day one, in a public comment, before I knew whether it
was right.
The needle only ever tells you which way you are facing.
Link to App or Repo
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article