The Living Blueprint

Stop writing architecture docs alone. Meet your AI Principal Architect that interrogates your design decisions and compiles production-ready specs in real time.

Comment

Inspiration

Most modern AI coding assistants act as passive, agreeable chatbots. When an engineer asks them to help design a complex, distributed cloud architecture, they respond with polite, generic walls of text that gloss over scaling bottlenecks, ignore quantitative limits (QPS, p99 latency ceilings, storage footprints), and avoid challenging flawed assumptions.

In real-world engineering organizations, the best technical designs are not created by asking polite chatbots; they are forged through rigorous peer-review with a Principal Technical Architect who interrogates decisions, red-teams trust boundaries, and forces you to confront edge cases before a single line of code is written.

We built The Living Blueprint Agent specifically for the Collaborative Partner Track of the All Things Agentic Hackathon. We created an assertive, analytical AI partner that does not just passively answer questions, but actively leads you through a structured 5-stage architectural review while compiling a comprehensive, production-grade 10-section technical specification document in real time.

What it does

The Living Blueprint Agent is a "Process-to-Document" collaborative design workspace featuring a dynamic dual-pane interface:

  1. State Machine Interrogation (Stages 0 to 4): The agent enforces an authoritative finite state machine across 5 strict stages:

    • Stage 0: System Goal & Scope (Forces boundary definitions, target users, and core objectives)
    • Stage 1: Scale, Limits & SLA Interrogation (Demands quantitative metrics: Peak QPS, p99 latency SLAs, partition sizes)
    • Stage 2: Data Models & State Flow (Evaluates database topologies, caching tiers, partition keys, and consistency contracts)
    • Stage 3: Edge Cases & Security Posture (Red-teams cascading failures, network partitions, circuit breakers, idempotency, and zero-trust auth)
    • Stage 4: Blueprint Sealed & Deployment (Finalizes containerized deployment, CI/CD canary strategies, OpenTelemetry observability, and ADRs)

  2. Multi-Blueprint Template Engine: Supports 4 specialized architectural domains, each with dedicated lead personas and stage taxonomies:

    • Engineering Architecture Spec (Principal Systems Architect)
    • Product Requirements Document (PRD) (Principal Product Manager)
    • Security Threat Model & STRIDE Review (Chief Information Security Architect)
    • GCP Cloud Migration & Modernization Plan (Google Cloud Principal Solutions Architect)

  3. Live "Living Document" Compilation with Visual Diffs: As you converse with the agent, background tool calls silently synthesize, format, and structure 10 comprehensive markdown sections in the right pane with real-time visual diff cues.

  4. Live Interactive Mermaid.js Architecture Visualizer: Automatically generates and renders interactive system topology and data-flow diagrams with native zoom, pan, fullscreen, and code-copy controls.

  5. Voice-Powered Interrogation & Audio Readout: Hands-free architecture reviews using the Web Speech API for continuous speech-to-text input and Speech Synthesis for audio critiques from the Lead Architect.

  6. In-Line Document Annotations & Targeted Refinement Directives: Every section includes a Revise button allowing users to submit targeted revision instructions that trigger pinpoint re-synthesis without corrupting the rest of the blueprint.

  7. Interactive Google Cloud FinOps & Latency SLA Estimator: A built-in FinOps widget with interactive sliders calculating estimated monthly Google Cloud infrastructure costs (Cloud Run, Firestore, GCS, Egress) and p99 SLA latency guarantees.

  8. 1-Click GitHub Architecture Decision Record (ADR-001) Generator: Instantly formats and exports finalized architectural decisions into GitHub-standard ADR-001 Markdown documents ready for repository commits.

  9. Persistent User Memory & Session History: Learns and remembers your tech stack preferences, cloud bias, and architectural styles across sessions, with instant 1-click session switching and restoration.

How we built it

We built The Living Blueprint Agent using a full-stack, enterprise-grade architecture:

  • AI Reasoning & Model Tier:

    • Google Gemini 3.5 Pro & Gemini 3.5 Flash as primary frontier models via the official Google GenAI SDK (google-genai) for multi-turn reasoning, streaming SSE token delivery, and autonomous tool calling.
    • Google Gemma 3 & Gemma 4 (via local Ollama runtime) for on-device, zero-cost, and privacy-preserving local offline execution.
    • Deterministic Simulation Engine for zero-API-key offline evaluator fallback.

  • Agent Orchestration Framework:

    • Built using the Google Agent Development Kit (google-adk) and Google Antigravity SDK, orchestrating finite state transitions and background tool dispatching (update_document_section, transition_state, extract_user_preference, query_past_projects).

  • Backend Microservice:

    • High-performance Python 3.14 + FastAPI with Server-Sent Events (SSE) streaming for real-time token delivery and background tool event dispatching.

  • Persistence Layer:

    • Dual-adapter persistence architecture supporting Google Cloud Firestore (google-cloud-firestore) for production cloud deployments and a zero-cost local JSON storage adapter for offline development.

  • Frontend Split-Screen Workspace:

    • Next.js 16 (React 19, TypeScript, Turbopack, App Router) styled with a Cyber-Architect dark glassmorphism design system, Lucide icons, and Mermaid.js SVG rendering.

  • Cloud Deployment:

    • Containerized production Dockerfile configured for serverless deployment on Google Cloud Run.

Challenges we ran into

  1. Synchronizing Token Streams with Background Tool Executions: Merging real-time LLM token streaming with structured background tool call events (e.g., updating a 10-section markdown document while simultaneously generating analytical critique text) required developing a custom multi-channel Server-Sent Events (SSE) event dispatcher protocol.

  2. Strict State-Machine Gatekeeping: Standard LLMs tend to be overly eager to agree and finish tasks quickly. Crafting system prompts and state transition validators that forced the agent to act as an uncompromising gatekeeper—refusing to advance to subsequent architectural stages until concrete numerical limits (QPS, p99 latencies, partition keys) were provided—required deep iterative prompt engineering and structured tool contracts.

  3. Robust Dual-Mode Execution: Ensuring that judges and evaluators without active Gemini API keys or GCP billing accounts could experience 100% of the interactive state machine, Mermaid rendering, and dual-pane synchronization without a single crash required building a fully deterministic local simulation engine that mirrors Gemini's exact function calling lifecycle.

Accomplishments that we're proud of

  • True Collaborative Partnership: Creating an agent that feels like a real, senior engineering peer who is not afraid to challenge flawed ideas and push for quantitative rigor.
  • Process-to-Document Paradigm: Eliminating the friction of manual specification writing by letting the engineer focus purely on decisions while the agent handles synthesis, formatting, diagrams, and ADRs.
  • Rich Multi-Blueprint Flexibility: Seamlessly adapting personas, stage steppers, and document sections across Systems Architecture, Product PRDs, Security Threat Models, and GCP Cloud Migrations.
  • Full Google Ecosystem Integration: Leveraging Gemini 3.5, Google ADK, Google GenAI SDK, Google Gemma, Google Cloud Firestore, and Google Cloud Run.
  • Rock-Solid Engineering: 100% automated test coverage with pytest and clean Next.js 16 production compilation with 0 TypeScript/lint errors.

What we learned

  • How to combine Google ADK function declarations and Google GenAI streaming for complex multi-artifact workflows.
  • The value of "Process-to-Document" agent architectures: users make high-leverage architectural decisions while the AI agent structures the artifacts, calculates FinOps metrics, and maintains consistency.
  • How to design resilient hybrid AI systems that seamlessly bridge cloud frontier models (Gemini 3.5) with local open-weights models (Gemma via Ollama) and offline fallbacks.

What's next for The Living Blueprint

  • Direct GitHub PR Integration: Automatically opening pull requests with generated ADRs and .github/docs/architecture.md files directly into developer repositories.
  • Automated Infrastructure-as-Code (IaC) Generation: Transforming finalized Living Blueprints into deployable Terraform and Pulumi scripts for Google Cloud.
  • Multiplayer Collaborative Architecture Reviews: Allowing multiple human engineers and stakeholder personas to participate in the interrogation session simultaneously.
  • Live Cloud Architecture Simulation: Integrating with Google Cloud monitoring APIs to stress-test generated architectures against historical traffic profiles.

Built With

Share this project:

Updates

Submission history