Choose Chatbot Type

Pick how you want to interact with the assistant.

About the Architecture

This demo was built to showcase AI engineering, full stack product engineering, and production-minded system design in one cohesive application.

Purpose of This Demo

This project is intentionally broader than a basic chat UI. It was designed as a portfolio-quality demonstration of how AI features can be built as real systems: with workflow orchestration, durable persistence, asynchronous background jobs, realtime UI updates, and containerized deployment.

The goal is to show more than prompt-to-response integration. It demonstrates how to design an AI-backed product end to end: frontend UX, typed API boundaries, workflow composition, persistent chat state, job processing, infrastructure, and operational tooling.

This is an AI engineering demo, a full stack demo, and a deployment demo at the same time.

System Diagram

The application uses one shared backend chat workflow and exposes it through two frontend delivery patterns: direct synchronous responses and background processing with realtime updates.

User
  |
  v
Next.js Frontend
  |
  +--> Direct Response UI
  |      |
  |      v
  |   /api/chat/direct
  |      |
  |      v
  |   FastAPI /chat/direct
  |      |
  |      v
  |   Chat workflow runs immediately
  |      |
  |      v
  |   JSON response returned
  |      |
  |      v
  |   Next.js simulates streaming to the UI
  |
  +--> Background + Realtime UI
         |
         v
      /api/chat/websocket
         |
         v
      FastAPI /chat/websocket
         |
         v
      Event row created + Celery job queued
         |
         v
      Worker runs chat workflow
         |
         v
      chats table updated
         |
         v
      Supabase realtime update
         |
         v
      UI syncs from persisted history

The route named /chat/websocket is not a native WebSocket server. It is an HTTP endpoint for asynchronous background processing. The realtime behavior in the browser comes from Supabase change subscriptions after the backend worker updates the persisted chat row.

AI Engineering Highlights

The backend is structured around a reusable workflow engine rather than a single monolithic chat handler. Chat generation is broken into discrete nodes that load prior state, call the model, and persist the updated transcript.

Chat Workflow
  |
  +--> PrepareChatNode
  |      - loads the current chat by id
  |      - reads pydantic-compatible message history
  |
  +--> ChatCompletionNode
  |      - rebuilds prior model messages
  |      - sends the latest user message to the LLM
  |      - captures assistant output and updated history
  |
  +--> UpdateChatNode
         - appends user + assistant messages
         - updates persisted message_history
         - updates model-facing history
         - saves the final assistant reply

The chat feature is modeled as a real workflow, not just a single API call.
The same core workflow can run synchronously or asynchronously without changing the business logic.
The architecture separates model-facing history from UI-facing message history, which is important in real AI products.
Background execution allows the system to scale beyond request-time constraints.

Full Stack Engineering Highlights

The frontend is not just a thin wrapper around an API. It manages responsive layout, shared app state, chat selection, race-proof synchronization, and two distinct interaction models for the same backend capability.

A shared React context stores the selected chat, loaded transcript, and responsive shell state.
The sidebar creates chats, selects chats, and refreshes durable history from Supabase.
Direct mode uses the AI SDK useChat hook for a fast conversational request-response UX.
Background mode manages local state and listens to realtime database updates when the worker finishes.
The UI supports mode switching without losing persistent conversation state.

This demonstrates product engineering judgment: one shared data model, but different UX strategies depending on how work is delivered and observed.

Chat Modes Comparison

Both chat modes rely on the same persisted transcript and the same backend workflow. The difference is how much work happens inside the original request and how the UI receives the answer.

Direct Response

The workflow runs immediately and the final answer comes back in the same HTTP request. The frontend then renders that completed response with a simulated streaming effect for a more conversational UX.

Background + Realtime

The request queues work first, then a worker completes the workflow later. The browser reacts to the finished result by subscribing to realtime updates on the persisted chat record.

Direct Response vs Background Processing

Direct mode is best for low-latency request-response interactions. Background mode is better when the app should acknowledge the request immediately and let work continue independently in the background.

Direct response is easier to debug because one user action maps cleanly to one request lifecycle.
Background processing is more resilient for longer-running or bursty workloads because work is queued and handled by Celery.
Direct mode prioritizes immediate UX feedback.
Background mode prioritizes operational flexibility and async delivery.
Both modes still converge on the same durable chat transcript in storage.

State Management Strategy

The frontend uses a split state model. Shared application state lives in a provider, while mode-specific interaction behavior lives inside each chat implementation.

Shared context stores the selected chat id, the loaded persisted message history, and shell state like mobile sidebar visibility.
The sidebar is responsible for chat list management, chat creation, and refreshing the selected transcript from Supabase.
Direct mode uses useChat and re-syncs after completion so rendered messages align with durable persistence.
Background mode manages local message state but rehydrates from realtime database updates.
Persisted history acts as the cross-mode source of truth.

Race Condition Handling

This demo also highlights the kind of engineering details that matter in real products. The visible UI response can arrive before every part of the app has reloaded the final persisted transcript, especially when switching chats or modes.

To handle that safely, the app treats the database-backed transcript as the durable source of truth and performs explicit refreshes during mode switches and after completion.

Selecting a chat triggers a fresh transcript fetch rather than relying only on in-memory sidebar data.
Switching modes performs a race-proof refresh sequence before mounting the next view.
That sequence fetches immediately, waits briefly, and fetches again to catch delayed commits.
Direct mode performs a follow-up sync after completion.
Background mode ignores duplicate assistant updates to avoid replay artifacts.

Durable persisted state wins over temporary in-memory state.

Infrastructure & Deployment

The deployment story is part of the demo. The system is containerized and composed as a multi-service stack rather than being presented as a local-only prototype.

Docker Compose Stack
  |
  +--> frontend
  +--> api
  +--> celery_worker
  +--> redis
  +--> db
  +--> caddy
  |
  +--> Supabase services
         - kong
         - auth
         - rest
         - realtime
         - storage
         - studio
         - analytics
         - pooler
         - meta
         - functions

The Compose setup splits the app into dedicated frontend, API, worker, Redis, Postgres, and reverse proxy services.
The stack also includes self-hosted Supabase components for REST, auth, storage, analytics, and realtime capabilities.
The root Compose file includes both the application stack and the Supabase stack, which makes the environment reproducible as one system.
The deployment uses an external project-scoped Docker network so the services can communicate cleanly across the stack.

Operational Tooling

The project also demonstrates practical developer operations. Startup, shutdown, and log monitoring are scripted so the stack can be managed consistently.

start.sh creates the project Docker network if needed and then runs the full Compose stack with a build step.
stop.sh tears the environment down cleanly.
logs.sh provides an interactive way to tail logs for either the full stack or selected services.

This matters for interviews and production-minded demos because it shows attention to repeatability, observability, and operational ergonomics rather than only feature development.

Why This Demonstrates Job-Ready Engineering

This project is meant to communicate a specific story: I can build AI products as real software systems, not just isolated model demos.

AI engineering: workflow design, model integration, context management, and async execution patterns.
Frontend engineering: responsive UI, state management, multiple interaction modes, and realtime synchronization.
Backend engineering: typed APIs, persistence, job queues, and separation of concerns between chat state and workflow state.
Infrastructure: Dockerized services, reverse proxying, self-hosted Supabase components, and reproducible environment setup.
Product thinking: the system is designed around tradeoffs, operability, and user experience rather than just technical novelty.

The intent of this demo is to show the full shape of modern engineering work: AI workflows, application architecture, frontend UX, data persistence, background processing, and deployment.