aws-architecture-studio
Open-source AWS architect studio: ADRs, Mermaid diagrams, and service catalog in one place.
git clone https://github.com/fernandofatech/aws-architecture-studio.gitAWS Architecture Studio is a Next.js 16 application I built to consolidate the two artifacts architects produce most — Architecture Decision Records and system diagrams — alongside a curated AWS service catalog and six ready-to-use reference patterns, all running in the browser with no backend required.
Why I built this
Every week I spend a non-trivial amount of time producing decision records and architecture diagrams. The tools available are either too generic (Confluence templates, blank Miro boards) or too heavyweight (enterprise modeling suites). I wanted something opinionated, fast, and tightly scoped to AWS work.
The ADR wizard follows the MADR format — the most widely adopted lightweight template — and walks through each section with a guided form, rendering live Markdown as you type so you can see the final document before you copy or download it. The diagram builder lets you pick services from the same catalog the app uses everywhere, draw edges between them, and get valid Mermaid source you can paste into any Markdown file or wiki.
The reference patterns section is the part I use most in client conversations: six canonical AWS architectures (3-tier web, serverless API, data lake, event-driven microservices, static SPA, batch ML) each pre-wired with a diagram, an ADR summary, a service list, Well-Architected pointers, and rough cost notes. Having those in one place means I can pull up a concrete starting point in seconds rather than rebuilding from memory.
What the application covers
.md download.Application structure and data flow
Everything runs in the browser. Next.js App Router serves static or server-rendered pages; Mermaid renders diagrams client-side. There is no backend API — catalog data and patterns are bundled at build time.
- Architect · browser
- Vercel · CDN / Edge
- / Hero · + Patterns
- /adr · ADR Wizard
- /diagrams · Diagram Builder
- /patterns · Reference Patterns
- /services · AWS Catalog
- Service Catalog · 37+ services
- Pattern Definitions · 6 architectures
- Mermaid 11 · Diagram renderer
- Markdown · Live preview
- GitHub Actions · CI + Security
Running locally
- 1
Clone the repository
Run
git clone https://github.com/fernandofatech/aws-architecture-studio.gitand enter the project directory. - 2
Install dependencies
The application lives under the
frontend/subdirectory. Runcd frontend && npm install. Node 18+ is recommended to match the Vercel runtime. - 3
Start the development server
Run
npm run devfrom insidefrontend/. Next.js starts onhttp://localhost:3000. Hot reload is active; Mermaid diagrams render in the browser without any additional setup. - 4
Build for production
Run
npm run buildthennpm startto validate the production bundle locally before deploying. The CI workflow runs this same sequence on every push. - 5
Review operations and setup docs
Check
OPERATIONS.mdfor deployment notes andSETUP.mdfor environment-specific configuration.docs/architecture.mdcovers the internal design decisions.
git clone https://github.com/fernandofatech/aws-architecture-studio.git
cd aws-architecture-studio/frontend
npm install
npm run dev
# → http://localhost:3000How the four modules fit together
The application is intentionally cohesive rather than loosely coupled. The same AWS service catalog data that powers the /services quick-reference page is the source of truth for the node picker in the diagram builder. When you select Lambda in the diagram builder, you are picking from the same record that shows its one-liner, pricing model, and when-to-use note in the catalog view. That consistency matters: it avoids the drift you get when catalog data and diagram tooling live in separate systems.
The reference patterns work similarly. Each pattern at /patterns/[slug] is a structured object containing a Mermaid diagram definition, an ADR summary, a list of service IDs that resolve against the catalog, Well-Architected pillar notes, and cost observations. Rendering a pattern detail page is just resolving those references — no separate data store, no API.
The ADR wizard at /adr is the most interactive piece. It walks through six sections (context, decision drivers, considered options, decision outcome, consequences, and status), keeps all state in React, and renders a MADR-compliant Markdown document in real time. The output is a plain .md file you can commit directly to a repo's docs/decisions/ directory — no proprietary format, no lock-in.
The CI setup reflects how I treat portfolio projects: three separate GitHub Actions workflows (general CI, frontend-specific build and Vercel deploy, and a security scan) run independently so a lint failure does not block a security report and vice versa.
Using the ADR output in a real project
The downloaded .md file is already MADR-compliant. Drop it into docs/decisions/ in your repo, number it sequentially (e.g. 0012-use-eventbridge-for-routing.md), and it will render correctly on GitHub without any post-processing. The wizard does not enforce a numbering scheme — that is intentional, since teams have different conventions.
Common questions
Does this store anything server-side or send data to external services?
No. All state lives in the browser. The ADR wizard and diagram builder are pure React components; nothing is persisted beyond what you explicitly copy or download.
Can I add my own AWS services or patterns?
Yes. The catalog and pattern definitions are structured data files in the codebase. Adding a service means adding an entry to the catalog object; adding a pattern means adding a new structured record with the required fields. The app resolves them at render time.
What version of Node.js do I need?
Node 18 or later is recommended. The project targets the Vercel runtime, which runs Node 18 LTS. Earlier versions may work but are not tested in CI.
Is the live site the same code as this repo?
Yes. The production deployment at studio.moretes.com is built directly from this repository via the GitHub Actions frontend workflow deploying to Vercel.
Who this is for
This is a focused tool for solution architects who work primarily with AWS and want to produce consistent, linkable decision records and diagrams without context-switching to a separate diagramming tool or starting from a blank ADR template every time. It is also a reference implementation for how I structure Next.js applications: App Router, TypeScript throughout, Tailwind for styling, client-side rendering for interactive components, and CI pipelines that treat security as a separate concern from build correctness.
If you are evaluating my work as a solutions architect or a TypeScript/Next.js engineer, the live site at studio.moretes.com is the fastest way to see what it does. If you want to understand the implementation choices, docs/architecture.md in the repository is the right starting point. Contributions are welcome via the process described in CONTRIBUTING.md.