System Architect AI

SystemArchitect.ai is an agentic GCP design partner that challenges risky choices, builds evidence-backed architectures, visualizes topology, and exports production-ready Terraform and ADRs.

Comment

System Architect AI

An evidence-backed GCP architecture copilot that challenges risky assumptions, maintains a living blueprint, and turns decisions into reviewable infrastructure artifacts.

Inspiration

Architecture decisions are often scattered across chat conversations, diagrams, documents, and infrastructure code. Traditional AI assistants can make this worse by agreeing too quickly, forgetting earlier constraints, or making confident recommendations without verifying them.

We built System Architect AI because engineers need more than a chatbot. They need an architecture partner that remembers the system being designed, identifies missing requirements, challenges unsafe assumptions, and explains the trade-offs behind every recommendation.

Our goal was to combine the accessibility of conversational AI with the discipline of a real architecture review.

What it does

System Architect AI is a stateful Google Cloud architecture copilot and systems CAD workbench.

It guides each architecture through a visible, bounded agent loop:

$$ \text{Observe} \rightarrow \text{Retrieve} \rightarrow \text{Decide} \rightarrow \text{Act} \rightarrow \text{Verify} \rightarrow \text{Adapt} $$

The application can:

  • Capture workload requirements such as peak RPS, p99 latency, availability, region, and monthly budget.
  • Maintain a living architecture blueprint throughout the conversation.
  • Retrieve relevant official Google Cloud guardrails with canonical source links.
  • Challenge risky proposals and provide two viable alternatives with trade-offs.
  • Separate user-provided facts from AI-proposed decisions.
  • Run deterministic architecture checks outside the language model.
  • Render the current system topology with Mermaid.
  • Model an analytical traffic-spike scenario and persist its assumptions.
  • Accept, correct, or reject recommendations.
  • Reuse approved feedback in future sessions.
  • Export the completed blueprint as Terraform and a Markdown Architecture Decision Record.
  • Run locally without falsely claiming that Gemini or Firestore is active.

For example, if someone proposes sending 40,000 writes per second to a single Cloud SQL primary, System Architect AI does not simply approve the design. It records the requirement, identifies the bottleneck, retrieves relevant evidence, proposes alternatives, and keeps the blueprint blocked until the risk is addressed.

How we built it

We built the backend with Python and FastAPI.

The production AI path uses Gemini 3.5 Flash through the Google GenAI SDK. Gemini can modify the architecture only through bounded server-side tools. After every update, deterministic Python checks verify the persisted blueprint independently of the model's response.

We use Cloud Firestore to store:

  • Architecture sessions
  • Conversation history
  • Living blueprint state
  • User feedback
  • Cross-session preferences
  • Agent activity and provenance

For local development and automated testing, we created a thread-safe in-memory implementation with the same contracts. The application clearly reports whether it is using Gemini or the deterministic local engine and whether persistence is backed by Firestore or memory.

The responsive browser workbench uses:

  • Server-Sent Events for observable agent progress
  • Mermaid for topology rendering
  • Sanitized Markdown for AI responses
  • A guided architecture workflow
  • An evidence and provenance inspector
  • Feedback and traffic-scenario dialogs
  • Terraform and MADR artifact previews

Terraform and MADR exports are generated from the current blueprint rather than disconnected chat text. Exports remain locked until the required constraints and core compute and storage decisions have been captured.

The application is containerized for Google Cloud Run, with environment-based configuration for Gemini, Firestore, CORS, and secrets.

Challenges we ran into

One of our biggest challenges was making the application genuinely agentic without exposing hidden chain-of-thought.

We solved this by displaying concise, server-confirmed activity records. Users can see what context was loaded, which evidence was retrieved, what state changed, and what verification found—without revealing private model reasoning.

Another challenge was keeping conversational recommendations synchronized with deterministic application state. A model could sometimes return a useful answer without invoking its update tool. To prevent explicit requirements from disappearing, we added deterministic reconciliation for facts and services directly stated by the user.

Persistence also required careful design. Blueprint updates needed to merge new constraints and decisions without duplicating risks, losing evidence, or accepting unbounded model-generated payloads. We introduced strict schemas, bounded histories, sanitized identifiers, and atomic state updates.

The interface created another challenge. Long conversations initially expanded the document and pushed the workflow and evidence panels outside the viewport. We reproduced the issue with a multi-turn conversation, fixed the grid and scrolling behavior, and verified the result on desktop and mobile layouts.

We also had to communicate uncertainty honestly. Our traffic-spike feature is an analytical model—not a load generator.

If (R_b) is the baseline request rate, (R_p) is the peak rate, and (L_t) is the target p99 latency, the current planning model calculates:

$$ \rho = \frac{R_p}{R_b} $$

$$ L_{\text{estimated}} = \max\left(L_t,\;L_t \times \rho\right) $$

Its buffer-health indicator is:

$$ B = \min\left(100,\;\max\left(0,\;\frac{100}{\rho}\right)\right) $$

These values are transparent planning signals, not measured production telemetry. We deliberately label them as estimates and recommend calibration through representative load testing.

Accomplishments that we're proud of

We are proud that System Architect AI connects conversation, state, evidence, verification, diagrams, and generated artifacts into one continuous workflow.

Our accomplishments include:

  • Building a visible six-stage agent loop backed by server-confirmed activity.
  • Applying constructive friction to unsafe architecture proposals.
  • Maintaining a living blueprint instead of disposable chat context.
  • Running deterministic verification outside the language model.
  • Tracking provenance for user facts, AI proposals, rules, and estimates.
  • Supporting cross-session adaptation from explicit user feedback.
  • Generating synchronized Mermaid topology diagrams.
  • Exporting Terraform and MADR artifacts from verified decisions.
  • Providing honest local fallbacks when cloud credentials are unavailable.
  • Verifying responsive desktop and mobile behavior through browser QA.
  • Passing all 14 automated tests without making billable model calls.

What we learned

We learned that a dependable AI engineering product needs more than a strong prompt.

Reliability comes from combining:

$$ \text{Model judgment} + \text{Bounded tools} + \text{Structured state} + \text{Deterministic verification} + \text{Provenance} $$

We also learned that memory is valuable only when users can inspect and correct it. Capturing feedback as an explicit product action was safer than silently treating every conversational statement as a permanent preference.

Another important lesson was that architecture artifacts should share a single source of truth. When the topology, findings, ADR, and Terraform are derived from the same living blueprint, they are less likely to contradict one another.

Most importantly, we learned to make uncertainty visible:

  • An analytical scenario is not a load test.
  • A planning estimate is not a billing quote.
  • Valid Terraform is not proof that quotas, IAM, capacity, or regional availability are correct.
  • An AI recommendation is not a confirmed engineering decision.

What's next for System Architect AI

Next, we want to evolve System Architect AI from an architecture workbench into a production-ready collaborative design platform.

Our roadmap includes:

  • Validating the complete Gemini, Firestore, and Cloud Run deployment path.
  • Integrating real load-testing and observability data.
  • Connecting recommendations to current pricing and project-specific quotas.
  • Expanding deterministic checks for networking, IAM, security, disaster recovery, and data governance.
  • Supporting architecture revisions with visual diffs and decision history.
  • Adding collaborative reviews, approvals, and shareable workspaces.
  • Generating deployment pipelines and operational runbooks.
  • Evaluating recommendations against expert-reviewed architecture scenarios.

Our long-term vision is to make System Architect AI a trusted architecture partner—one that helps teams move faster while keeping their assumptions, evidence, risks, and decisions visible.

Learn more about the platform technologies in the Google Cloud documentation.

Built With

  • artifact-registry
  • cloud-firestore
  • cloud-run
  • css3
  • docker
  • dompurify
  • fastapi
  • google-cloud
  • google-gemini
  • google-gen-ai-sdk
  • html5
  • httpx
  • javascript
  • lucide
  • marked.js
  • mermaid.js
  • pydantic
  • pytest
  • python
  • rest-api
  • secret-manager
  • server-sent-events
  • terraform
  • uvicorn
Share this project:

Updates