AWS Builder Center

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.

Platform Engineering Head | Startup CTO | Founder
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 directory
Reading 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 WEB
aws 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

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article