Contract Paranoia

Technical Architecture Blueprint
Cloud Run

Inspiration

We've all been there — standing at a gym counter or signing a software agreement, staring at pages of legalese designed to obscure rather than inform. Contract Paranoia was built to level that playing field. We wanted a legal guardian that doesn't just read a document but listens, watches, and talks you through it in real time. By building on Gemini 2.5 Flash Native Audio, we turned a stressful, silent signing process into a live, transparent conversation.

How we built it

We used Gemini as a coding collaborator throughout development, rapidly iterating on Para's persona and the multimodal feedback loop to ensure she feels like a supportive buddy rather than a cold legal tool. The architecture runs across three layers. The frontend is a React/TypeScript app using Web Audio Worklets to capture 16kHz PCM audio and pdf.js for real-time document rendering. A WebSocket Gateway handles bidirectional audio and vision frame streams between the browser and the agent layer. The agent layer is orchestrated using Google ADK and runs three components. Para is the user-facing root agent — she watches the document, speaks up when she spots danger, and stops the moment you interrupt her. The Analyzer is a sub-agent that extracts specific clauses and validates them against current law using Google Search grounding. The Judge Agent is completely independent — it runs on Vertex AI rather than the standard Gemini API, and audits every session for legal accuracy and conversational quality, acting as a trust layer between Para's output and the user. The entire stack is containerized and deployed on Google Cloud Run, giving the app production-grade scalability with zero cold-start issues during the live demo.

Challenges we ran into

The hardest problem was natural interruption. Para needed to stop mid-sentence the moment a user spoke — not after finishing her current thought, not after a 500ms delay. We solved this by implementing an adaptive buffer in the WebSocket layer that detects incoming user audio and flushes Para's output queue immediately, giving a genuine barge-in experience. The second challenge was grounding speed: maintaining sub-second response times while validating clauses against real legal sources required careful prompt caching and context window management.

What we learned

The biggest surprise was how much the move from traditional TTS chains to Native Audio changed the interaction quality. The difference isn't a feature — it's a completely different UX. Users stop feeling like they're querying a system and start feeling like they're talking to someone. We also learned that in sensitive domains like legal tech, the Judge audit layer isn't optional — it's what makes the product trustworthy rather than just impressive. Running it on Vertex AI separately from the main session ensures the evaluation is always objective and never influenced by Para's own context window.

Everything is in — Cloud Run, Judge Agent on Vertex AI, ADK, Google Search grounding, Para, Analyzer, WebSocket Gateway. All named and explained with purpose.