Runi: Architecting a Real-Time, Multi-User AI Session System with Google Gemini

Luke Geenen — Wed, 04 Mar 2026 14:02:29 +0000

This is a submission for the Built with Google Gemini: Writing
Challenge

Runi: Architecting a Real-Time, Multi-User AI Session System with Google Gemini

What I Built with Google Gemini

Runi is a real-time, multi-user AI session framework designed to embed a
large language model inside a structured collaborative environment.

Instead of treating Google Gemini as a conversational interface, I
designed it as a state-aware reasoning layer operating within a
distributed session architecture.

The system's goal is not simply to generate responses. It is to:

Manage structured session state\
Enforce permission-aware AI behavior\
Coordinate multi-user interactions\
Persist and update pinned objects\
Operate within deterministic guardrails

System Architecture Overview

Runi is built around four primary layers.

1. Real-Time Session Layer

Each session is a structured document stored in Firestore containing:

Session ID\
Member list with assigned roles\
Pinned object references\
Active system-layer apps\
Permission mappings\
Metadata

Sessions are:

Multi-user\
Real-time synchronized\
Permission-scoped\
AI-aware

Firestore listeners maintain live synchronization between clients.

All state mutations are validated server-side before persistence.

2. Permission Model

Users are assigned roles at invitation time:

Viewer\
Editor\
Admin

Every Google Gemini invocation includes:

The current user's role\
An explicit list of allowed actions\
A structured session state snapshot\
Referenced pinned objects

This prevents the AI from proposing state mutations the user is not
authorized to perform.

All AI-generated actions are treated as structured mutation proposals
and must pass validation before execution.

3. Pinned Object Model

Runi separates conversation from structured state.

Pinned objects are atomic entities that:

Exist independently from chat history\
Can be referenced by ID\
Are versioned\
Are schema-validated\
Support controlled updates

The AI never directly mutates Firestore.

Instead, it returns structured mutation proposals which are validated
for:

Schema conformance\
Permission compliance\
Object existence\
Referential integrity

This separation prevents hallucinated writes and corrupted session
state.

4. System-Layer Apps

Sessions can instantiate structured applications inside the environment,
including:

File Manager\
Image Gallery\
Image and Video Generation\
Wiki Layer\
Space Weather Module

Each app:

Defines its own schema\
Registers allowed actions\
Maintains scoped storage\
Exposes controlled interaction boundaries to the AI

Example flow for image generation:

A user triggers media generation.\
The controller sends structured intent to Gemini.\
Gemini returns refined prompt metadata and structured output.\
Media is generated and stored in Firebase Storage.\
A versioned pinned object is created.\
Firestore propagates the update in real time to all session members.

All writes pass through validation middleware.

Technology Stack

Frontend

Vite\
React\
Component-based dashboard architecture\
Firestore real-time listeners\
Blob-based iframe isolation for project environments

Backend

Node.js controller\
Structured task runner\
Schema validation layer\
Mutation validator\
Firestore (real-time state + indexes)\
Firebase Storage (files + media assets)

Every AI response is treated as untrusted structured input.

AI Layer: Google Gemini

Gemini is used for:

Intent classification\
Structured JSON planning\
Context-aware reasoning\
Media prompt refinement\
Wiki summarization\
Permission-aware action proposals

Prompts are structured and always include:

System role definition\
Session state snapshot\
User role\
Allowed actions\
Pinned object references\
Expected output schema

Gemini functions as a probabilistic planner operating inside a
deterministic execution layer.

Key Engineering Challenges

AI in a Distributed Real-Time System

LLMs are non-deterministic.

Real-time collaborative systems are state-sensitive.

To reconcile this:

All AI outputs are proposals\
No direct database writes are allowed\
All changes require validation\
Session versioning mitigates race conditions

Context Scaling

Multi-user sessions rapidly expand context size.

Mitigation strategies:

Structured state snapshots instead of replaying full conversation history\
Object referencing instead of full content injection\
Metadata summaries in place of raw file bodies

Role-Aware AI Behavior

Gemini must behave differently for:

Viewers\
Editors\
Admins

Explicit role and action injection significantly improves compliance and
reduces invalid action proposals.

Google Gemini Feedback

Strengths

Strong structured JSON generation\
Reliable schema adherence when constrained\
Effective reasoning over structured session state\
High-quality summarization of linked knowledge objects

Limitations Observed

Schema drift in very long sessions\
Occasional assumption of unavailable system apps\
Requires strong validation layers for deterministic workflows\
Long context windows require active pruning strategies

Gemini performs best when embedded inside a clearly bounded execution
architecture.

What's Next

Cross-session shared memory graphs\
Version-controlled session file systems\
More granular permission hierarchies\
Domain-specific session templates\
Bounded autonomous planning loops

Closing Reflection

Embedding an LLM inside a real-time collaborative system is not
primarily a prompt engineering challenge.

It is a distributed systems design challenge.

Google Gemini becomes most powerful when treated as a reasoning engine
inside a controlled, validated execution architecture.

That shift --- from chatbot to state-aware planner --- defines Runi.

Forem: Luke Geenen

Runi: Architecting a Real-Time, Multi-User AI Session System with Google Gemini