AI Systems Architecture•CASE STUDY N002

Multimodal AI Assistant

Enterprise Conversational Intelligence & Stateful Agent Platform

Next.jsFastAPILangGraphGoogle GeminiPostgreSQLShadcn UITailwind CSS

01. OBJECTIVE & SYSTEM CONSTRAINTS

The Engineering Problem

A high-performance full-stack conversational intelligence platform powered by Next.js and FastAPI—featuring NDJSON token streaming, stateful agent workflows orchestrated via LangGraph, in-memory multi-format document ingestion, and persistent thread checkpointing backed by PostgreSQL.

Systemic Bounds & Operational Constraints:

▶Low-latency Time to First Byte (TTFB) achieved via asynchronous FastAPI StreamingResponse and NDJSON chunking.
▶Durable conversational state persistence across process restarts via AsyncPostgresSaver.
▶Stateless in-memory file parsing eliminating temporary disk storage and I/O bottlenecks.

02. STACK RATIONALE & ARCHITECTURE DECISIONS

STACK_RATIONALE // AGENTIC_INFRASTRUCTURE

⚡LangGraph StateGraph(vs. Stateless LLM Chains / Raw Prompt Loops)

Provides a directed cyclic state machine with thread-level AsyncPostgresSaver checkpointing and automatic context window summarization when message limits are reached.

⚡Stateless In-Memory Stream Parsing (io.BytesIO)(vs. Temporary Disk File Storage)

Parses PPTX, DOCX, XLSX, PDFs, images, and code directly in RAM, completely eliminating disk I/O latency and storage leak vectors.

⚡NDJSON Server-Sent Events (SSE)(vs. Standard REST JSON Responses)

Asynchronous FastAPI StreamingResponse dispatches raw token chunks with low latency and instant client-side cancellation support.

⚡Stateful JWT + HTTP-Only Cookies(vs. Stateless LocalStorage Tokens)

Cross-origin SameSite=None cookie security with 1-click Guest Mode generating instant trial UUID sessions without registration friction.

03. SYSTEM ARCHITECTURE TOPOLOGY

HOVER NODES TO INSPECT SERVICE BOUNDARIES AND IMPLEMENTATION DETAILS

MULTIMODAL AI ASSISTANT // C4_CONTAINER_DIAGRAM

System Boundary: MULTIMODAL AI ASSISTANT

// PRESENTATION TIER

Next.js Client Interface

[Server-Rendered UI]

Next.js / TypeScript / Shadcn UI

NDJSON SSE TOKEN STREAM

// API GATEWAY

FastAPI Backend Service

[Async REST & Streaming API]

FastAPI / Python / Uvicorn

LANGGRAPH STATE DISPATCH

// ORCHESTRATION TIER

LangGraph Agent Engine

[State Machine]

LangGraph / LangChain

In-Memory Stream Parser

[Document Processor]

PyPDF2 / python-docx / openpyxl

Google Gemini API

[Multimodal Inference]

Google Gemini SDK

ASYNCPOSTGRESSAVER CHECKPOINT

// PERSISTENCE TIER

PostgreSQL & AsyncSaver

[State Persistence]

PostgreSQL / AsyncPostgresSaver

Next.js Client Interface [Server-Rendered UI]Next.js / TypeScript / Shadcn UI

Streams NDJSON tokens and renders Markdown dispatches with Prism syntax highlighting.

04. SYSTEM INTERFACES & PLATFORM GALLERY

Architect Space & Reasoning Dashboard

Document Analysis & Agentic Reasoning Session

Authentication & Access Portal

05. SUBSYSTEM ARCHITECTURE DEEP-DIVE

4 MASTER SUBSYSTEMS — 3 DATABASE TABLES — 11 API ENDPOINTS

LangGraph Agentic Orchestrator

ORCHESTRATOR

StateGraph state machine executing conversation routing, web search tool dispatches, and automatic context window summarization.

1 tables|3 endpoints

Stateless Multi-Format Ingestion

INGESTION

In-memory RAM parsing of PPTX, DOCX, XLSX, PDF, Vision Images, and source code files via io.BytesIO without disk writes.

0 tables|2 endpoints

Real-Time SSE Streaming Engine

STREAMING

Asynchronous NDJSON SSE token chunk generator powered by FastAPI StreamingResponse with keepalive heartbeat.

0 tables|2 endpoints

Auth & Thread Checkpointer

AUTH & STATE

Stateful JWT auth with HTTP-Only SameSite=None cookies, 1-click Guest Trial UUID generation, and PostgreSQL session persistence.

2 tables|4 endpoints

06. IMPLEMENTATION CHALLENGES & HARD BUGS

CHALLENGE 01

Cyclic Reasoning & LangGraph State Safety

Problem Encountered:

Multi-turn agent conversations required complex state preservation without losing context or looping infinitely during tool calls.

Architectural Solution:

Architected a LangGraph StateGraph utilizing PostgreSQL-backed AsyncPostgresSaver checkpointing to persist graph states after every execution step.

System Guardrail:Max super-step execution cap prevents infinite agent looping during complex multi-tool calls.

CHALLENGE 02

Real-Time NDJSON SSE Token Streaming

Problem Encountered:

Standard HTTP REST responses caused long latency delays while waiting for complete LLM completion dispatches.

Architectural Solution:

Integrated Server-Sent Events (SSE) from FastAPI StreamingResponse, streaming raw NDJSON token chunks with low latency directly to Next.js components.

System Guardrail:Schema-validated JSON events ensure client UI parsers never crash on partial chunk dispatches.

CHALLENGE 03

Stateless Multi-Format Ingestion in RAM

Problem Encountered:

Writing user-uploaded documents (PPTX, DOCX, XLSX, PDF) to disk caused I/O bottlenecks and potential storage leak vectors.

Architectural Solution:

Engineered in-memory file stream processing using Python io.BytesIO, extracting text and images directly in RAM before passing to Gemini API.

System Guardrail:Strict 10-file payload upload limit prevents server memory exhaustion.

07. TELEMETRY & METRIC STACK

NDJSON

TOKEN STREAMING

Raw chunk dispatch via FastAPI StreamingResponse

ZERO I/O

IN-MEMORY PARSING

Stateless document extraction via io.BytesIO

INDEXED

CHECKPOINT LOOKUP

Thread-level retrieval via AsyncPostgresSaver

DURABLE

STATE PERSISTENCE

Session state survives backend process restarts

08. ARCHITECTURAL TRADEOFFS & INSIGHTS

⚠ IN-MEMORY RAM SCALING & PAYLOAD LIMITS: Parsing multi-format files directly in RAM via io.BytesIO completely eliminates disk I/O latency, but memory usage scales linearly with concurrent large uploads. Enforcing strict payload caps (max 10 files upload limit) keeps backend RAM consumption predictable during multi-document chat sessions.

Technology Stack:

Next.jsFastAPILangGraphGoogle GeminiPostgreSQLShadcn UITailwind CSS

← BACK TO ALL PROJECTS