Tutorial 2: High Level Architecture
In tutorial 1 we used the simple web app environment to create an implementation plan for a simple web application. We are going to go a bit further in this tutorial, we will:
1. Configure a client server architecture to sit on the same system/origin
2. Review the specification
3. Generate code for components
4. Evaluate the code to see how well it meets the spec
The High-Level Architecture environment is preferable to the Simple Web App environment because it provides richer controls and a wider range of components.
Stage 1: Exploring Scores
With the tutorial diagram open you should see something like this:
It is a pretty standard three tier architecture: Front-end talking to back-end talking to database. It has been configured with many controls enabled by default and almost everything is green (specified according to policy), except the Server App (Back-end) which is red with a -1. Tap the component to select it, then tap it again to open the configuration menu. Select the Scoring tab and you will see that CORS_SCORE is red. Tapping the red score indicator displays diagnostic information about the policy.
In tutorial 1 you were introduced to the ordinary model for controls, where they are switched on/off and that changes the score. CORS requires a little more consideration, you might have come across it as a misconfiguration reported in a penetration test or a DAST scan. One way to address this is to configure CORS with an explicit list of allowed sites. In this tutorial, however, we’ll take a different approach, which we’ll explore in the next stage.
Stage 2: Configuring Architecture
Click on the diagram background to close the context menu and open the component library. Towards the bottom of the component library is a Same Origin Zone which i would like you to drag into the diagram and drop it near the server app. Resize the Same Origin Zone, by dragging the corners/centre, so that it encompasses both the Web App and the Server App. Once you have finished positioning it, the Server App should automatically turn green.
The Same Origin Zone automatically configures the crossOrigin control for both the Client App and Server App to sameOrigin. Because both applications now share the same origin, explicit CORS configuration is no longer required. Same-origin communication is permitted by default.
You may also notice something interesting in the Spec tab of the Same Origin Zone’s context menu. The Spec tab wasn't available for the Simple Web App tutorial, but in this high level architecture environment there is a lot going on and so we sometimes need to zoom in and grab little bits of spec at a time.
Stage 3: Boundary/Component Specification Groups
Select the same origin boundary and tap it to bring up the context menu, navigate to the Spec tab. It's kind of hard to read in that tiny little tab, so click the Copy button and then got to the Workflow tab, clicking Specification if it isn't selected already.
The whole system is specified here and there is quite a lot there, click on the Paste tab and then paste your copied spec into there:
Now that we've pasted it into a slightly larger area, lets scroll throught the spec and take a look. It is written in yaml to be read by machines so don't worry if you don't understand it, we will transform it in a second. If you look through the text you can see at the top it has a Same Origin Zone but lower down there is mention of the website and api within the same origin zone. The same origin zone is acting as a specification group, pulling in the entires inside it into one grouped specifation. This is what we want as we want any requirements spec to understand that this is one origin or one system, not two.
Lets transform this next into a requirements list and task spec we can use. Go to the Outputs page and Click Clear Outputs if needed.
Stage 4: Generating Tasks/Requirements
Our next step is to turn that spec into a task list / requirements doc that we can use in a code generation tool. We can do this either by copy and pasting a prompt into our LLM of choice or for a smoother integration you can setup your AI of choice within the tool:
With the Outputs page selected either click Generate Outputs if integrated AI is setup or click Copy Outputs and paste the result into your AI of choice, potentially editing it to ask it to output a single markdown file (it helps). The integrated AI is generally going to give you a result that is easier to work with, whereas copy/paste gives you scope to add additional formatting.
If you used integrated AI and generated outputs then skip to the next step, otherwise copy the output from your AI tool and select the paste tab in outputs and paste the text in there.
Stage 5: Evaluating the Task/Requirements Quality
Next click Reviewer to bring up the reviewer page. Either click Copy Result or Evaluate Outputs and use your AI to review how well the task/requirements meets the spec.
As you get more well versed with the tool, you can edit or create new diagram environment files that make different requests like write infrastructure-as-code, code, reports... all withing a diagram->spec->generated-output->evaluation workflow.
Also notice there are other tabs like the manual test and manual audit tabs, these are not to be sniffed at. These include checklists so that you can review your systems manually to check constraints/controls are in place.
Detections provide a deterministic way of checking that your outputs meet the spec, but are only designed to work with the full spec, rather than this specification group example.
Stage 6: Coding Agents
The next step is to put that implementation plan to use in an AI coding tool. In the spec you may have seen mention of Kiro which is a particular vendor tool, you can use any tool and each will have different pros and cons, it is most important that you are happy with the result.
Click copy outputs to get the generated output into the clipboard, or grab it from wherever you generated it. Now depending on the tool, you could either paste it into a prompt in your AI coding tool or usually preferable: add it as a file to your (probably empty) working folder and prompt the AI coding tool to implement that tasks.md. You can give extra information about implementation specifics in that prompt as well so that you get anticipated folders and technology choices.