Forem: Ekemini Samuel

Clone MedTalk: HIPAA-Ready Video and Chat Consultations in Flutter

Ekemini Samuel — Mon, 12 Jan 2026 21:28:52 +0000

Telehealth is transforming the way patients and providers connect, offering faster access to care and reducing barriers caused by distance or scheduling. A critical part of this experience is enabling secure, real-time video consultations alongside features like chat messaging for sharing updates, questions, and follow-ups.

With Stream's healthcare chat solution, developers can build HIPAA-ready communication features into their apps.

In this tutorial, you'll learn how to clone MedTalk, a telehealth platform designed for seamless communication between doctors and patients. We'll use Flutter Web to deliver a responsive cross-platform experience and Stream's Chat & Video SDKs to power HIPAA-ready messaging and video calls.

Here’s a demo video of the complete application:

Prerequisites

A free Stream account and API key
VS Code
Android Studio
Flutter SDK installed on your computer

Set Up Your Development Environment

To install Flutter on your computer, first open flutter.dev.

Note:

If you already have your development environment set up, you can clone the project and get started quickly.

git clone <https://github.com/Tabintel/medtech.git>

cd medtech

Run this command to install the dependencies needed for the app:

flutter pub get

If not, then continue with the steps below.

First, download the version compatible with your computer’s operating system: Windows, macOS, Linux, or ChromeOS.

Then choose the type of app you’ll be building. For this tutorial, we’re building a Flutter web application, so select Web from the list.

After selecting the type of app you’re building, the next step is setting up the requirements to begin building with Flutter. Follow the steps in the Flutter documentation to proceed.

If you’re using another operating system, follow the guide for your OS.

Specific requirements for a Windows OS are:

Use Git for Windows to manage Flutter versions and your source code versioning.
Google Chrome to debug JavaScript code for web apps.
Visual Studio Code with the Flutter extension for VS Code.
Also, note that we are installing Flutter with VS Code.
Once you meet all these requirements, you’re ready to start building.

Install the Flutter SDK

In your VS Code editor, run the Ctrl + Shift +p command.

Then select Download when this window shows.

After downloading and installing the Flutter SDK, you will choose the type of Flutter template you want to install.

For this project, select Application as shown below.

Now that we have the Flutter SDK, we can proceed to further develop the Virtual Health consultation platform with Stream and Flutter.

If you need any clarification, read the Flutter docs.

To confirm that you installed Flutter correctly, run flutter doctor -v in your command prompt terminal.

It should print out a similar response like so:

Follow these steps to set up the project for building with Flutter Web.

Create a medtech folder on your computer, and open it in the VS Code editor. In your command prompt, run:

flutter create . \--platforms web

The output then displays like so:

It creates the structure for the Flutter web project. It also makes a web/ directory containing the web assets used to bootstrap and run your Flutter app, like so:

In the following steps, we will look at how to set up Stream for the virtual health consultation platform with Flutter SDK.

Get Started with Stream

First, create an account in the Stream dashboard.

Then click on Create App to create a new application.

Enter the details of the application.

After creating the Stream app, go to your dashboard and click Chat Messaging in the top right. You will then see the App Access Keys displayed.

Create an .envfile in your project’s root directory, copy the App key and secret, and save it like so:

STREAM\_API\_KEY=your-api-key  
STREAM\_API\_SECRET=your-api-secret

Now you’re ready to build and integrate Stream using the Flutter SDK.

In your terminal, run this command:

flutter pub get

This command installs all the dependencies listed in your pubspec.yaml, making packages like stream_chat_flutter, flutter_dotenv, available to your app. It’s required after any change to pubspec.yaml before you can use new packages in your code.

To integrate prebuilt UI components for chat in Flutter, use the stream_chat_flutter package. This package includes reusable and customizable UI components already integrated with Stream’s API.

Add the package to your dependencies like so:

dependencies:  
  stream\_chat\_flutter: ^1.0.1-beta

This package provides full chat UI widgets you can use directly in your app for fast integration.

For video, UI components to Stream Video in Flutter, check out the documentation.

Build the Role Selection Screen

As we develop the app, the codebase will increase to what is in the image below.

In the lib/screen/auth directory, create a file called role_selection_screen.dart and enter the code below:

import 'package:flutter/material.dart';  
import '../../stream\_client.dart';  
class RoleSelectionScreen extends StatefulWidget {  
  const RoleSelectionScreen({super.key});  
  @override  
  State\<RoleSelectionScreen\> createState() \=\> \_RoleSelectionScreenState();  
}  
class \_RoleSelectionScreenState extends State\<RoleSelectionScreen\> {  
  bool \_loading \= false;  
  Future\<void\> \_connectAndNavigate(String userId, String route, {String? name}) async {  
    setState(() \=\> \_loading \= true);  
    await StreamClientProvider.connectUser(userId, name: name);  
    setState(() \=\> \_loading \= false);  
    Navigator.pushNamed(context, route);  
  }  
  @override  
  Widget build(BuildContext context) {  
    return Scaffold(  
      backgroundColor: const Color(0xFFF7F9FC),  
      body: Center(  
        child: Padding(  
          padding: const EdgeInsets.all(24.0),  
          child: Column(  
            mainAxisAlignment: MainAxisAlignment.center,  
            children: \[  
              Image.asset(  
                'assets/images/medtalk\_logo.png',  
                height: 120,  
              ),  
              const SizedBox(height: 32),  
              const Text(  
                'MedTalk',  
                style: TextStyle(fontSize: 32, fontWeight: FontWeight.bold, color: Color(0xFF2A4D9B)),  
              ),  
              const SizedBox(height: 8),  
              const Text(  
                'Talk to a doctor anytime, anywhere',  
                style: TextStyle(fontSize: 16, color: Color(0xFF4A4A4A)),  
                textAlign: TextAlign.center,  
              ),  
              const SizedBox(height: 48),  
              \_loading  
                  ? const CircularProgressIndicator()  
                  : Column(  
                      children: \[  
                        ElevatedButton(  
                          onPressed: () \=\> \_connectAndNavigate('doctor', '/doctor', name: 'Dr. Sarah Lee'),  
                          style: ElevatedButton.styleFrom(  
                            minimumSize: const Size.fromHeight(48),  
                            backgroundColor: Color(0xFF2A4D9B),  
                            foregroundColor: Colors.white,  
                            textStyle: const TextStyle(fontWeight: FontWeight.bold),  
                            shape: RoundedRectangleBorder(  
                              borderRadius: BorderRadius.circular(12),  
                            ),  
                          ),  
                          child: const Text('Continue as Doctor'),  
                        ),  
                        const SizedBox(height: 16),  
                        OutlinedButton(  
                          onPressed: () \=\> \_connectAndNavigate('patient', '/patient', name: 'Patient'),  
                          style: OutlinedButton.styleFrom(  
                            minimumSize: const Size.fromHeight(48),  
                            foregroundColor: Color(0xFF2A4D9B),  
                            textStyle: const TextStyle(fontWeight: FontWeight.bold),  
                            side: const BorderSide(color: Color(0xFF2A4D9B), width: 2),  
                            shape: RoundedRectangleBorder(  
                              borderRadius: BorderRadius.circular(12),  
                            ),  
                          ),  
                          child: const Text('Continue as Patient'),  
                        ),  
                      \],  
                    ),  
            \],  
          ),  
        ),  
      ),  
    );  
  }  
}

Note: You can get the asset in assets/images/medtalk_logo.png from this GitHub repository. Download the medtalk_logo.png file and add it to the /assets/images directory.

The role selection screen is the entry point to the virtual health consultation application. It allows users to choose between doctor and patient roles. This screen sets the user's identity and routes to the appropriate dashboard.

The state management uses Flutter's built-in StatefulWidget to manage UI states and tracks the loading state with a _loading boolean to show/hide the loading indicator.

class \_RoleSelectionScreenState extends State\<RoleSelectionScreen\> {  
  bool \_loading \= false;  
  // ...  
}

We import flutter/material.dart for UI components and ../../stream_client.dart to manage connections to Stream Chat using a user’s ID and name.

The screen is built as a stateful widget to handle dynamic changes, such as displaying a loading spinner during Stream connection, with a _loading boolean (shown in the code snippet above) that tracks this connection status.

_connectAndNavigate function sets _loading to true, calls StreamClientProvider.connectUser(userId, name: name) to connect the user, then navigates to either /doctor or /patient once connected.

The UI has an off-white background, the MedTalk logo, and a tagline. If _loading is true, a CircularProgressIndicator is shown; otherwise, two buttons appear — “Continue as Doctor” (blue, connects with Dr. Sarah Lee) and “Continue as Patient” (outlined, connects with Patient).

This screen is the entry point to the virtual health consultation platform, guiding users with a personalized experience based on their role; Doctor or Patient.

Build the Doctor’s Home Screen

After users select their role and connect to Stream, doctors are taken to the DoctorHomeScreen. This is the main dashboard for doctors, where they can see demo patients, start chats, and view existing conversations.

In lib/screens/doctor/ create a file: doctor_home_screen.dart, and enter the code below:

The full code is in the GitHub repository.

import 'package:flutter/material.dart';  
import 'package:stream\_chat\_flutter/stream\_chat\_flutter.dart';  
import '../../stream\_client.dart';  
import '../../demo\_users.dart';  
class DoctorHomeScreen extends StatefulWidget {  
  const DoctorHomeScreen({Key? key}) : super(key: key);  
  @override  
  State\<DoctorHomeScreen\> createState() \=\> \_DoctorHomeScreenState();  
}  
class \_DoctorHomeScreenState extends State\<DoctorHomeScreen\> {  
  late final StreamChannelListController \_channelListController;  
  @override  
  void initState() {  
    super.initState();  
    \_channelListController \= StreamChannelListController(  
      client: StreamClientProvider.client,  
      filter: Filter.in\_('members', \[StreamClientProvider.client.state.currentUser\!.id\]),  
      limit: 20,  
    );  
  }  
  @override  
  Widget build(BuildContext context) {  
    final currentUser \= StreamClientProvider.client.state.currentUser;  
    return Scaffold(  
      backgroundColor: const Color(0xFFF7F9FC),  
      appBar: AppBar(  
        title: const Text('Doctor', style: TextStyle(color: Color(0xFF2A4D9B), fontWeight: FontWeight.bold)),  
        backgroundColor: Colors.white,  
        iconTheme: const IconThemeData(color: Color(0xFF2A4D9B)),  
        elevation: 1,  
      ),  
      body: Padding(  
        padding: const EdgeInsets.all(8.0),  
        child: Column(  
          children: \[  
            // Patient list  
            SizedBox(  
              height: 120,  
              child: ListView.separated(  
                scrollDirection: Axis.horizontal,  
                itemCount: demoPatients.length,  
                separatorBuilder: (\_, \_\_) \=\> const SizedBox(width: 16),  
                itemBuilder: (context, index) {  
                  final patient \= demoPatients\[index\];  
                  return Card(  
                    elevation: 2,  
                    shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),  
                    child: Container(  
                      width: 200,  
                      padding: const EdgeInsets.all(12),  
                      child: Column(  
                        mainAxisAlignment: MainAxisAlignment.center,  
                        children: \[  
                          Text(patient.name, style: const TextStyle(fontWeight: FontWeight.bold)),  
                          const SizedBox(height: 8),  
                          ElevatedButton(  
                            onPressed: () async {  
                              final client \= StreamClientProvider.client;  
                              final currentUser \= client.state.currentUser;  

                              if (currentUser \== null) {  
                                ScaffoldMessenger.of(context).showSnackBar(  
                                  SnackBar(content: Text('Current user not found. Please log in again.')),  
                                );  
                                return;  
                              }  
                              try {  
                                // Create the channel  
                                final channel \= client.channel(  
                                  'messaging',  
                                  extraData: {  
                                    'members': \[currentUser.id, patient.id\],  
                                    'created\_by\_id': currentUser.id,  
                                  },  
                                );  

                                // Create the channel on Stream  
                                await channel.create();  

                                // Navigate to the chat  
                                if (\!mounted) return;  
                                Navigator.push(  
                                  context,  
                                  MaterialPageRoute(  
                                    builder: (context) \=\> StreamChannel(  
                                      channel: channel,  
                                      child: const StreamChannelPage(),  
                                    ),  
                                  ),  
                                );  
                              } catch (e) {  
                                if (\!mounted) return;  
                                ScaffoldMessenger.of(context).showSnackBar(  
                                  SnackBar(content: Text('Error creating chat: ${e.toString()}')),  
                                );  
                              }  
                            },  
                            child: const Text('Start Chat'),  
                          ),  
                        \],  
                      ),  
                    ),  
                  );  
                },

We import four files:

flutter/material.dart for UI components.
stream_chat_flutter.dart for prebuilt Stream Chat widgets and controllers.
stream_client.dart for the connected Stream client instance.
demo_users.dart for sample patient data, so the demo works without a real backend.

DoctorHomeScreen is a stateful widget because it manages a StreamChannelListController, which fetches channels based on filters. In initState(), the controller is created with:

client: StreamClientProvider.client — the active Stream connection.
filter: Filter.in_('members', [currentUser.id]) — returns only channels that include the logged-in doctor.
limit: 20 — loads the latest 20 channels.

In the build method, we get the currentUser to display their info and use it when creating new chats. The UI has two main sections:

1. Patient List (top horizontal list)
A scrollable row of demo patients from demoPatients. Each patient card shows their name and a Start Chat button. It then:

Creates a messaging channel with members [doctorId, patientId].
Calls await channel.create() to set up the conversation in Stream.
Navigates to StreamChannelPage, which shows the chat UI if there’s an error, and a SnackBar displays the message.

2. Chat List (main section)
A StreamChannelListView that automatically lists all the doctor’s existing chats based on the controller’s filter. Tapping a channel opens it in StreamChannelPage.

The StreamChannelPage
This uses three widgets from stream_chat_flutter:

StreamChannelHeader(): shows the other user’s name and a back button.
StreamMessageListView(): displays real-time messages.
StreamMessageInput(): lets users send new messages with emoji and attachments.

Stream Chat’s Flutter SDK handles message syncing, typing indicators, history, and UI updates, so we don’t build these features manually.

This setup allows doctors to see their patients, start conversations, view existing chats, and message in real time. Because this is Flutter Web, you can even open two browser tabs: one as a doctor and one as a patient.

Next, we’ll switch to the patient’s view in lib/screens/patient/patient_home_screen.dart to see how the experience mirrors the doctor’s while keeping roles separate.

Build the Patient’s Home Screen

Just like the doctor’s view, our patient home screen gives users two main capabilities:

See available doctors.
Start or continue chats with them.

Create a patient_home_screen.dart file in the lib/screens/patient directory and enter the code below:

import 'package:flutter/material.dart';  
import 'package:stream\_chat\_flutter/stream\_chat\_flutter.dart';  
import '../../stream\_client.dart';  
import '../../demo\_users.dart';  
class PatientHomeScreen extends StatefulWidget {  
  const PatientHomeScreen({Key? key}) : super(key: key);  
  @override  
  State\<PatientHomeScreen\> createState() \=\> \_PatientHomeScreenState();  
}  
class \_PatientHomeScreenState extends State\<PatientHomeScreen\> {  
  late final StreamChannelListController \_channelListController;  
  @override  
  void initState() {  
    super.initState();  
    \_channelListController \= StreamChannelListController(  
      client: StreamClientProvider.client,  
      filter: Filter.in\_('members', \[StreamClientProvider.client.state.currentUser\!.id\]),  
      limit: 20,  
    );  
  }  
  @override  
  Widget build(BuildContext context) {  
    final currentUser \= StreamClientProvider.client.state.currentUser;  
    return Scaffold(  
      backgroundColor: const Color(0xFFF7F9FC),  
      appBar: AppBar(  
        title: const Text('Patient', style: TextStyle(color: Color(0xFF2A4D9B), fontWeight: FontWeight.bold)),  
        backgroundColor: Colors.white,  
        iconTheme: const IconThemeData(color: Color(0xFF2A4D9B)),  
        elevation: 1,  
      ),  
      body: Padding(  
        padding: const EdgeInsets.all(8.0),  
        child: Column(  
          children: \[  
            // Doctor list  
            SizedBox(  
              height: 120,  
              child: ListView.separated(  
                scrollDirection: Axis.horizontal,  
                itemCount: demoDoctors.length,  
                separatorBuilder: (\_, \_\_) \=\> const SizedBox(width: 16),  
                itemBuilder: (context, index) {  
                  final doctor \= demoDoctors\[index\];  
                  return Card(  
                    elevation: 2,  
                    shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),  
                    child: Container(  
                      width: 200,  
                      padding: const EdgeInsets.all(12),  
                      child: Column(  
                        mainAxisAlignment: MainAxisAlignment.center,  
                        children: \[  
                          Text(doctor.name, style: const TextStyle(fontWeight: FontWeight.bold)),  
                          const SizedBox(height: 8),  
                          ElevatedButton(  
                            onPressed: () async {  
                              final client \= StreamClientProvider.client;  
                              final currentUser \= client.state.currentUser;  

                              if (currentUser \== null) {  
                                if (\!mounted) return;  
                                ScaffoldMessenger.of(context).showSnackBar(  
                                  const SnackBar(content: Text('Error: User not logged in')),  
                                );  
                                return;  
                              }  

                              try {  
                                // Create the channel  
                                final channel \= client.channel(  
                                  'messaging',  
                                  extraData: {  
                                    'members': \[currentUser.id, doctor.id\],  
                                    'created\_by\_id': currentUser.id,  
                                  },  
                                );  

                                // Create the channel on Stream  
                                await channel.create();  

                                // Navigate to the chat  
                                if (\!mounted) return;  
                                Navigator.push(  
                                  context,  
                                  MaterialPageRoute(  
                                    builder: (context) \=\> StreamChannel(  
                                      channel: channel,  
                                      child: const StreamChannelPage(),  
                                    ),  
                                  ),  
                                );  
                              } catch (e) {  
                                if (\!mounted) return;  
                                ScaffoldMessenger.of(context).showSnackBar(  
                                  SnackBar(content: Text('Error creating chat: ${e.toString()}')),  
                                );  
                              }  
                            },  
                            child: const Text('Start Chat'),  
                          ),

Get the full code in GitHub.

When the screen loads, initState() creates a StreamChannelListController that acts as the inbox manager. It connects to StreamClientProvider.client (set up in role_selection_screen.dart) and filters for any channels where the logged-in patient is a member:

filter: Filter.in\_('members', \[StreamClientProvider.client.state.currentUser\!.id\]),

This works because the patient is connected to Stream through getstream-token-server.js. (We will explain this later in the article.)

The Node server takes the patient’s ID ("patient"), uses the Stream API key and secret from .env, generates a user token, and registers them with Stream. Without that step, currentUser would be null and chats wouldn’t work.

The UI starts with a horizontal list of doctors pulled from demoDoctors.

When a patient taps Start Chat:

We create or retrieve a messaging channel with both patient and doctor IDs.
If it doesn’t exist, Stream creates it automatically.
We call await channel.create() to finalize it.
We navigate to StreamChannelPage, which uses StreamMessageListView() for real-time messages and StreamMessageInput() for sending new ones.

At the bottom, StreamChannelListView displays all active chats, including ones started by doctors. Stream’s SDK updates this list instantly, so new messages appear in real time.

With both doctor and patient home screens complete, we have a two-way chat system using Flutter Web, Stream Flutter SDK, and a Node token server. The next step is to add a shared chat screen functionality.

Build the Shared Chat Screen

Both doctors and patients use the shared chat screen. It provides a reusable UI for a single channel, powered by the Stream Chat Flutter SDK. You pass in a channelId and userId, and the screen connects to that channel, showing real-time messages with Stream’s prebuilt widgets.

Create a chat_screen.dart file in the lib/screens/shared directory and enter the code below:

import 'package:flutter/material.dart';  
import 'package:stream\_chat\_flutter/stream\_chat\_flutter.dart';  
import '../../stream\_client.dart';  
class ChatScreen extends StatefulWidget {  
  final String channelId;  
  final String userId;  
  const ChatScreen({super.key, required this.channelId, required this.userId});  
  @override  
  State\<ChatScreen\> createState() \=\> \_ChatScreenState();  
}  
class \_ChatScreenState extends State\<ChatScreen\> {  
  late Channel channel;  
  @override  
  void initState() {  
    super.initState();  
    channel \= StreamClientProvider.client.channel(  
      'messaging',  
      id: widget.channelId,  
      extraData: {'members': \[widget.userId\]},  
    );  
    channel.watch();  
  }  
  @override  
  Widget build(BuildContext context) {  
    return StreamChannel(  
      channel: channel,  
      child: Scaffold(  
        appBar: StreamChannelHeader(),  
        body: Column(  
          children: \[  
            Expanded(child: StreamMessageListView()),  
            StreamMessageInput(),  
          \],  
        ),  
      ),  
    );  
  }  
}

When the widget loads, initState() creates a Channel from the global client in StreamClientProvider.

It calls:

client.channel(  
  'messaging',  
  id: widget.channelId,  
  extraData: {'members': \[widget.userId\]},  
)

This communicates with Stream to:

“Get or create this messaging channel with these members.”

If the channel doesn’t exist yet, Stream will create it when channel.create() is called earlier in the flow. The extraData helps identify channel members and supports filtering and admin logic.

After creating the channel object, the code calls channel.watch(). This starts streaming channel state and events—messages, typing indicators, presence updates, and reactions—over a WebSocket connection. Updates arrive instantly without polling.

In the build() method, the UI is wrapped in StreamChannel(channel: channel, child: ...). StreamChannel is a provider widget that makes the channel available to its children. Inside, the prebuilt widgets handle the chat experience:

StreamChannelHeader() → shows the channel name and back button.
StreamMessageListView() → displays the live message feed with avatars, ordering, and read receipts.
StreamMessageInput() → sends messages, attachments, and reactions.

These widgets handle sending and receiving messages, rendering updates, retry logic, and syncing with Stream’s servers.

This screen assumes the user is already connected to Stream through StreamClientProvider—a step that happens earlier (for example, in role_selection_screen.dart). That connection involves calling your Node-based token server (getstream-token-server.js), which uses your API secret to generate a user token. The Flutter app then calls client.connectUser(User(id: ...), token) to authenticate.

When a doctor or patient clicks “Start Chat” from their home screen, the app either creates the channel there or navigates into this ChatScreen with the existing channelId. As long as both members are included in the channel’s members list, Stream will route messages correctly and store them in your dashboard.

Connect to Stream Client

To connect the Flutter app to the Stream client, create a stream.dart file in the lib/stream directory and enter the code below:

import 'package:stream\_chat\_flutter/stream\_chat\_flutter.dart';  
import 'package:flutter\_dotenv/flutter\_dotenv.dart';  
import 'dart:convert';  
import 'package:http/http.dart' as http;  
class StreamClientProvider {  
  static final StreamChatClient client \= StreamChatClient(  
    dotenv.env\['STREAM\_API\_KEY'\]\!,  
    logLevel: Level.INFO,  
  );  
  /// Connect a user to the Stream Chat client (production, fetch token from backend)  
  static Future\<void\> connectUser(String userId, {String? name}) async {  
    if (client.state.currentUser?.id \== userId) return;  
    await client.disconnectUser();  
    // Fetch token from backend  
    final tokenEndpoint \= dotenv.env\['TOKEN\_ENDPOINT'\] ?? 'http://localhost:3000/token';  
    final response \= await http.get(Uri.parse('$tokenEndpoint?user\_id=$userId'));  
    if (response.statusCode \!= 200\) {  
      throw Exception('Failed to fetch Stream Chat token: ${response.body}');  
    }  
    final token \= jsonDecode(response.body)\['token'\];  
    await client.connectUser(  
      User(id: userId, name: name ?? userId),  
      token,  
    );  
  }  
}

This connects the Flutter app and the Stream Chat API. It loads your API key from .env, initializes a single Stream client for the whole app, and connects users by fetching their token from your backend.

At the top, we import:

import 'package:stream\_chat\_flutter/stream\_chat\_flutter.dart';  
import 'package:flutter\_dotenv/flutter\_dotenv.dart';  
import 'dart:convert';  
import 'package:http/http.dart' as http;

stream_chat_flutter – The official Flutter SDK for Stream Chat.
flutter_dotenv – Loads environment variables from .env, such as your API key and backend URL.
dart:convert – Decodes JSON responses from the server.
http – Makes HTTP requests to your backend to get the chat token.

The main class is StreamClientProvider, which creates one StreamChatClient for the entire app:

static final StreamChatClient client \= StreamChatClient(  
  dotenv.env\['STREAM\_API\_KEY'\]\!,  
  logLevel: Level.INFO,  
);

Here, the API key comes from .env, and the log level is set to INFO so you can see helpful debug messages about chat events.

The connectUser method is where the actual login happens:

static Future\<void\> connectUser(String userId, {String? name}) async {  
  if (client.state.currentUser?.id \== userId) return;  
  await client.disconnectUser();

First, it checks if the user is already connected with the same ID. If so, it skips the rest. If not, it disconnects any existing users to avoid conflicts.

Next, it fetches the token from your backend:

final tokenEndpoint = dotenv.env['TOKEN_ENDPOINT'] ?? 'http://localhost:3000/token';

final response = await http.get(Uri.parse('$tokenEndpoint?user_id=$userId'));

The token endpoint is read from .env (falling back to localhost for development). The request includes the user ID as a query parameter.

If the server responds with anything other than 200 OK, it throws an error. Otherwise, it extracts the token from the JSON:

if (response.statusCode != 200) {
  throw Exception(
    'Failed to fetch Stream Chat token: ${response.body}',
  );
}
final token = jsonDecode(response.body)['token'];

Finally, it connects the user to Stream:

await client.connectUser(  
  User(id: userId, name: name ?? userId),  
  token,  
);

The SDK uses this ID, optional display name, and the JWT token from your backend to log in securely. The token is generated server-side using your API key and secret, so those sensitive credentials never touch the Flutter app.

Basically, the stream_client.dart file loads your API key from .env, requests a secure token from the server, and connects the user to Stream Chat so they can send and receive messages in real time.

Set Up the Main App Entry Point

In the lib directory, create a main.dart file. This will serve as the entry point for your Flutter application.

import 'package:flutter/material.dart';  
import 'package:flutter\_dotenv/flutter\_dotenv.dart';  
import 'package:stream\_chat\_flutter/stream\_chat\_flutter.dart';  
import 'package:flutter\_localizations/flutter\_localizations.dart';  
import 'stream\_client.dart';  
import 'screens/auth/role\_selection\_screen.dart';  
import 'screens/doctor/doctor\_home\_screen.dart';  
import 'screens/patient/patient\_home\_screen.dart';  
import 'screens/shared/video\_call\_screen.dart';  
Future\<void\> main() async {  
  WidgetsFlutterBinding.ensureInitialized();  
  await dotenv.load(fileName: '.env');  
  runApp(MedTalkApp());  
}  
class MedTalkApp extends StatelessWidget {  
  MedTalkApp({super.key});  
  final StreamChatClient client \= StreamClientProvider.client;  
  @override  
  Widget build(BuildContext context) {  
    return MaterialApp(  
      title: 'MedTalk',  
      theme: ThemeData(  
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),  
        useMaterial3: true,  
      ),  
      localizationsDelegates: \[  
        GlobalMaterialLocalizations.delegate,  
        GlobalWidgetsLocalizations.delegate,  
        GlobalCupertinoLocalizations.delegate,  
      \],  
      supportedLocales: \[  
        Locale('en'),  
      \],  
      initialRoute: '/',  
      routes: {  
        '/': (context) \=\> const RoleSelectionScreen(),  
        '/doctor': (context) \=\> const DoctorHomeScreen(),  
        '/patient': (context) \=\> const PatientHomeScreen(),  
        '/video': (context) \=\> const VideoCallScreen(participantName: 'Dr. Sarah Lee'),  
      },  
      builder: (context, child) \=\> StreamChat(  
        client: client,  
        child: child\!,  
      ),  
    );  
  }  
}

We start by importing the required packages:

flutter/material.dart for core Flutter UI components
flutter_dotenv to load environment variables from the .env file
stream_chat_flutter for integrating the Stream Chat SDK
flutter_localizations to add localization support
stream_client.dart` (local file) and screen widgets for different roles and features.

Next, we set up the main() function, which ensures Flutter’s bindings are initialized, loads our environment variables, and finally runs the MedTalkApp.

The MedTalkApp widget extends StatelessWidget and defines the app’s overall configuration. It creates a StreamChatClient instance (from StreamClientProvider.client) and sets up the app theme, localization delegates, and supported locales.

For navigation, we define our initial route ('/'), which takes the user to the Role Selection Screen, and register other routes for the Doctor Home, Patient Home, and Video Call screens. This makes navigating between different app parts easy, depending on the user’s role and actions.

The builder property of MaterialApp wraps the child widget with the StreamChat widget, passing it on to the client. This ensures the Stream Chat SDK is available throughout the app’s widget tree, enabling messaging and chat features in any screen.

With the app’s entry point ready, the next step is to create a node server to generate Stream Chat tokens.

Set Up the Node.js Server

Create a getstream-token-server.js file in the root directory and enter the code in the GitHub repository.

This runs a Node.js + Express server that generates secure JWT tokens for authenticating users with the Stream Chat API.

Note: In production, do not hardcode your Stream API secret directly in your Flutter app. Instead, the server/backend generates a timed token for the authenticated user, and your Flutter app uses that token to connect to Stream. This is exactly what this Node token server does in this context.

We start by importing the required packages:

express to create a simple HTTP server
stream-chat to talk to Stream’s API and create tokens
cors so our Flutter web app can call the server without CORS issues
dotenv so we can store our API key and secret safely in a .env file

Next, we load the environment variables and check if the STREAM_API_KEY and STREAM_API_SECRET are set. The server will stop immediately if they're missing; we can’t run without them.

We then initialize a StreamChat server client using the API key and secret. This client will be able to create tokens, seed users, and perform admin operations.

The server exposes two main endpoints:

/token?user_id=USER_ID – This generates a JWT token for the given user_id. Flutter will call this when connecting to Stream.
/ – A simple HTML page just to verify that the server is running.

We also added:

Request logging so you can see when tokens are requested.
A *user seeding script *(seedUsers) that adds demo doctors and patients to Stream. These IDs and names match the ones in our Flutter app, so you can test right away.
Graceful shutdown handling so the server closes cleanly when you stop it.

Open a terminal and start the server with this command:

node getstream-token-server.js

Now your Flutter app can request tokens securely and connect to Stream Chat.

Set Up Demo Users for MedTalk

To keep development simple, we’ll define a set of demo doctors and patients that our MedTalk app can use for testing. This will allow us to quickly switch between roles (doctor or patient).

In the lib directory, create a new file called demo_users.dart and add the following code from the GitHub repository.

With this setup, we can easily pull a list of doctors or patients in the UI, making it much faster to test the application.

Now the full Flutter app is set up, and we can begin testing it!

Test the Virtual Health Consultation App

Select Chrome as your app's target device to run and debug a Flutter web app:

bash flutter run \-d chrome

You can also choose Chrome as a target device in your IDE.

If you prefer, you can use the edge device type on Windows, or use web-server to navigate to a local URL in the browser of your choice.

Run From the Command Line

If you use Flutter run from the command line, you can now run hot reload on the web with the following command:

bash flutter run \-d chrome \--web-experimental-hot-reload
When hot reload is enabled, you can restart your application by pressing "r" in the running terminal or "R".

The Flutter web app loads and opens this URL in the Chrome browser:

http://localhost:60767/

This is the application's landing page.

When you click on either Continue as Doctor or Continue as Patient, it then redirects to a loading screen for a few seconds, like so:

Which then redirects to the chat page, with this URL (if you selected Patient role), like so:

http://localhost:57331//#/patient

At the moment, there are no active chats yet.

The users then show:

Then the patients:

And the Patient/Doctor chat loads:

From the Stream dashboard, check the chat logs to confirm the application is integrated with Stream through the Flutter SDK.

Note: We built a Node.js server for handling the Stream tokens for chat/video.

Test the endpoint in your browser or with curl:

You should get a JSON response like:

How to Run the Flutter Web App

To connect the Flutter web app with the Stream Flutter SDK, we set up a server using Node.js, as shown in the step above. This server generates tokens from Stream Chat using the Stream API, which is connected through the API key set up in the .env file at the root of the project directory codebase.

To do this, we first need to run the Node.js server, seed some users (Doctors and Patients), and assign Stream tokens to each user. This enables users to chat asynchronously on the platform.

To get started running the app, first run the Node.js server in a different terminal.

Note: We use two command prompts in a terminal to run this application.

In the first terminal, run this command:

bash node getstream-token-server.js

This starts the node server and shows an output like so:

To test an endpoint, open this URL in your browser: http://localhost:3000/token?user_id=doctor_anna

It then loads this HTML page, and when you click Get token for doctor anna.

It generates a token like so:

You can also view the server logs in the Node.js terminal.

The token server is now up and running perfectly with this setup:

Server is listening on http://localhost:3000
It has successfully generated a token for a Doctor user, doctor_anna
All demo users are seeded in Stream Chat

Next, let's test the Flutter app, which should now be able to:

Connect to the token server
Authenticate users
Create chat channels

Run the Flutter app with this command:

flutter run \-d chrome

The Flutter app begins to start and shows these logs in your terminal. If you look closely at the log messages, you will see that the Flutter app is connected to the Stream API.

The Flutter app then loads and opens in your Chrome browser.

Click on either Continue as Doctor or Patient, and then try starting a new chat. If you select the Doctor role, the chat loads, showing the history of previous chats with Patients.

Click on any user, say Bob Brown, to start a chat

You can also confirm that the messages are sent through Stream by viewing the real-time chat logs in your dashboard.

Now let’s try out the Patient's chat!

Navigate to the homepage of the application with http://localhost:64150, and then click on Continue as Patient, which then loads the view as shown below:

The direct URL to the patient view of the app is: http://localhost:64150/#/patient

Click on any of the Doctors, say Doctor Emily, to start a conversation:

1. As a Doctor:

Click "Start Chat" with a patient
Send a message in the chat
The chat should now appear in your chat list

2. As a Patient:

Log in as the patient you chatted with
You should see the chat in your chat list
You can reply, and the doctor will see it immediately

3. Verify Real-time Sync:

Open the same chat on two devices (or two different user accounts)
Messages should appear instantly on both devices when sent from either side

You can view the total number of messages on the Stream chat dashboard.

To run the app locally, clone the GitHub repository with this command.

git clone

Note: As mentioned in the article earlier, make sure you have Flutter set up and installed on your computer.

Navigate to the project directory, then run this command to install the dependencies needed for the app.

flutter pub get

Also, ensure your Stream API keys are added to an .env file in the project directory.

Then run the application with:

flutter run \-d chrome

And that’s it! You have a working virtual consultation app, fully set up.

Conclusion

In this tutorial, you built a MedTalk clone, a HIPAA-compliant telehealth application powered by Flutter and Stream. By integrating Stream Chat and Stream Video, you enabled secure messaging and real-time video consultations between doctors and patients. This prototype shows how quickly you can deliver compliant, modern healthcare communication experiences with Stream’s SDKs.

Build AI-Powered Smart Replies with React and Synthetic

Ekemini Samuel — Fri, 19 Dec 2025 07:59:08 +0000

You’ve probably used Gmail’s Smart Reply or Slack’s suggested messages, which are short, AI-generated responses like “Sounds good 👍” or “Let’s do it!”. With a single tap response, you can save time and keep conversations flowing.

By reducing time spent typing, conversations stay active, drop-off rates decrease, and chat apps feel more innovative and modern.

Smart replies can be used in customer support apps (agents pick relevant replies and respond faster), marketplaces or communities (buyers and sellers exchange quick transactional messages), or even productivity tools or workplace chat platforms (users save time on repetitive confirmations like “Yes,” “Got it,” or “On it”).

In this tutorial, we’ll use Stream’s React SDK and Synthetic’s inference API to bring smart replies into chat. You’ll build a chat application that generates real-time, context-aware reply suggestions directly within conversations.

Watch a demo of what you’ll build:

Prerequisites

To follow along, make sure you have the following prerequisites:

Node.js (version 16 or higher) and NPM installed
A free Stream account with your API key
A Synthetic API key for accessing the inference API
Basic knowledge of React, Next.js, and Typescript

Ready? Let’s begin!

Stream is a platform that provides APIs and SDKs for developers to build real-time chat, video, and activity feeds into their applications.

To get started with Stream, create your free account.

Learn how to set up your Stream account in this guide.

After you’ve signed up, navigate to your dashboard and click on the Create App button in the top right of the page, like so:

This modal then loads, where you enter details of the new app you’re creating. Enter the app name and then select the chat & video data region, feed data storage location, and environment (you can choose 'development'). Click 'Create App' to proceed.

Next, you’ll get your App API Access Keys from the Chat Overview in your dashboard. Copy the Key and Secret and add it to your .env file in your codebase.

STREAM_API_KEY=”your_stream_api”
STREAM_API_SECRET=”your_stream_secret”

We will be using the Stream React Chat SDK for this application. Learn more about it in the documentation.

Setting Up the React Project

Open your terminal and enter this command to create a new app:

npx create-next-app@latest smart-chat --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

This creates a new Next.js app in your directory called “smart-chat”, with Typescript and Tailwind configuration. It also adds an Import alias.

Note: Import aliases help with better imports and readability in your codebase. When adding new imports, simply update the alias configuration in tsconfig.json or jsconfig.json, rather than updating import paths throughout your codebase.

Next, navigate to the new project directory we just created with this command.

cd smart-chat

Then, install the Stream Chat React SDK with this command:

npm install stream-chat stream-chat-react

This command installs the stream-chat and stream-chat-react packages. We will import the required components, such as Chat, Channel, MessageList, and MessageInput, from stream-chat-react into the main application file, which is the page.tsx file.

Next, create a stream-chat-container.tsx file in the components/ directory and import the necessary components from stream-chat-react to build the chat interface:

import { StreamChat } from "stream-chat"
import {
  Chat,
  Channel,
  ChannelHeader,
  MessageList,
  MessageInput,
  Window,
} from "stream-chat-react"
import "stream-chat-react/dist/css/v2/index.css"

The stream-chat package provides the core Stream Chat client for initialising and managing chat functionality, while stream-chat-react offers pre-built React components like Chat,Channel, MessageList, and MessageInput.

Chat component acts as a provider, wrapping the chat interface to manage the Stream client.
Channel component renders a specific chat channel.
MessageList displays the conversation history, and <MessageInput> allows you to compose messages.

The full implementation is available in the GitHub repository.

In your project’s root directory, create a page.tsx file in the /app directory and enter the code below:

"use client"

import { useState } from "react"
import { StreamChatContainer } from "@/components/stream-chat-container"

export default function Home() {
  const [isLoggedIn, setIsLoggedIn] = useState(false)
  const [userId, setUserId] = useState("")
  const [userName, setUserName] = useState("")
  const [inputUserId, setInputUserId] = useState("")
  const [inputUserName, setInputUserName] = useState("")

  const handleLogin = () => {
    if (inputUserId && inputUserName) {
      setUserId(inputUserId)
      setUserName(inputUserName)
      setIsLoggedIn(true)
    }
  }

  if (isLoggedIn) {
    return <StreamChatContainer userId={userId} userName={userName} />
  }

}

Due to the length of the code file above, we have included only a snippet here. The complete code is available in the GitHub repository.

This sets up the main entry point for the application by prompting you to enter a User ID and Display Name before rendering the chat interface.

It uses React’s useState hook to manage user login state. When you enter a User ID and Display Name and click the Join Chat button, the handleLogin function updates the state and renders the component, passing the userId and userName props.

For the UI, we’re adapting a Discord-like interface.
To set up the layout for this application, create a layout.tsx file also in the /app directory, and enter this code:

import type React from "react"
import type { Metadata } from "next"
import "./globals.css"


import { Geist, Geist_Mono } from 'next/font/google'


// Initialize fonts
const geist = Geist({
  subsets: ["latin"],
  variable: "--font-geist",
  weight: ["100", "200", "300", "400", "500", "600", "700", "800", "900"],
})


const geistMono = Geist_Mono({
  subsets: ["latin"],
  variable: "--font-geist-mono",
  weight: ["100", "200", "300", "400", "500", "600", "700", "800", "900"],
})


export const metadata: Metadata = {
  title: "AI-Powered Live Chat with Intelligent Replies",
  description: "Real-time chat with context-aware AI reply suggestions powered by Synthetic",
}


export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode
}>) {
  return (
    <html lang="en" className={`${geist.variable} ${geistMono.variable}`}>
      <body className="font-sans">{children}</body>
    </html>
  )
}

Connecting to the Chat App

Next, we initialise the Stream client with your API Key from the app we created earlier in the Stream Dashboard above.

In the app directory, create a file named api/token/route.ts to handle user authentication for Stream’s Chat React SDK. Add the following code:

/token/route.ts

import { type NextRequest, NextResponse } from "next/server"
import { StreamChat } from "stream-chat"


const apiKey = process.env.NEXT_PUBLIC_STREAM_API_KEY
const apiSecret = process.env.STREAM_API_SECRET


export async function POST(request: NextRequest) {
  try {
    if (!apiKey || !apiSecret) {
      console.error("Missing Stream credentials - NEXT_PUBLIC_STREAM_API_KEY or STREAM_API_SECRET not set")
      return NextResponse.json(
        {
          error:
            "Stream credentials not configured. Please add NEXT_PUBLIC_STREAM_API_KEY and STREAM_API_SECRET environment variables.",
        },
        { status: 500 },
      )
    }


    const { userId, userName } = await request.json()


    if (!userId || !userName) {
      return NextResponse.json({ error: "userId and userName are required" }, { status: 400 })
    }


    console.log("Generating token for user:", userId)


    // Use Stream official server client to create a user token
    const serverClient = StreamChat.getInstance(apiKey, apiSecret)
    // Ensure the user exists/updated on Stream
    await serverClient.upsertUser({ id: userId, name: userName })
    const token = serverClient.createToken(userId)


    console.log("Token generated successfully")


    return NextResponse.json({
      token,
      userId,
      userName,
    })
  } catch (error) {
    console.error("Token generation error:", error)
    return NextResponse.json(
      { error: error instanceof Error? error.message : "Failed to generate token" },
      { status: 500 },
    )
  }
}

This API route authenticates users for the React SDK. It uses the StreamChat.getInstance method to create a server-side client with your NEXT_PUBLIC_STREAM_API_KEY and STREAM_API_SECRET (set these in your .env file from your Stream dashboard).

The createToken method generates a JWT token for the user (from the API key), which is used to connect to Stream’s chat service. This token is returned to the client for use in components/stream-chat-container.tsx. The route includes error handling for missing credentials or invalid requests to ensure secure authentication.

Then, in components/stream-chat-container.tsx, initialise the Stream client and connect the user like so:

const apiKey = process.env.NEXT_PUBLIC_STREAM_API_KEY

useEffect(() => {
  const init = async () => {
    if (!apiKey) {
      setError("Stream API key is not configured. Please check your environment variables.")
      setIsLoading(false)
      return
    }

    try {
      setIsLoading(true)
      setError(null)

      const res = await fetch("/api/token", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ userId, userName }),
      })

      if (!res.ok) {
        const errorData = await res.json().catch(() => ({}))
        throw new Error(errorData.error || "Failed to get authentication token")
      }

      const { token } = await res.json()
      const c = StreamChat.getInstance(apiKey)

      await c.connectUser({ id: userId, name: userName }, token)

      if (!c.userID) {
        throw new Error("Failed to establish connection with Stream Chat")
      }

      setClient(c)
    } catch (e) {
      const errorMessage = e instanceof Error ? e.message : "An unknown error occurred"
      console.error("Stream initialization error:", e)
      setError(`Failed to initialize chat: ${errorMessage}`)
      setClient(null)
    } finally {
      setIsLoading(false)
    }
  }
  init()

  return () => {
    if (client) client.disconnectUser()
  }
}, [userId, userName, apiKey])

In components/stream-chat-container.tsx, the useEffect hook initialises the Stream client using StreamChat.getInstance with the NEXT_PUBLIC_STREAM_API_KEY. It fetches a user token from the api/token/route.ts endpoint, passing userId and userName from the login form at app/page.tsx.

The connectUser method authenticates the user with the token, establishing a real-time connection to Stream’s chat service.

The useMemo hook creates an AI Smart Replies channel and adds the authenticated user as a member:

const channel = useMemo(() => {
  if (!client) return null
  return client.channel("team", channelId, {
    name: "AI Smart Replies",
    members: [userId],
    created_by_id: userId
  })
}, [client, channelId, userId])

The full initialisation logic, including error handling and loading states, is in the GitHub repository.

Still in the /app directory, create an app folder, which will have these sub-folders and files:

/smart-replies/route.ts

import { type NextRequest, NextResponse } from "next/server"
import { generateSmartReplies } from "@/lib/synthetic-ai"


export async function POST(request: NextRequest) {
  try {
    const { messages } = await request.json()


    if (!messages || !Array.isArray(messages)) {
      return NextResponse.json({ error: "messages array is required" }, { status: 400 })
    }


    const result = await generateSmartReplies(messages)


    return NextResponse.json({
      replies: result.replies,
      isAI: result.isAI,
      model: result.model,
    })
  } catch (error) {
    console.error("Smart replies API error:", error)
    return NextResponse.json({ error: "Failed to generate smart replies" }, { status: 500 })
  }
}

Here is an overview of how the project’s directory looks:

Creating the Chat UI

To set up the chat UI, we start with the <Chat> component we added earlier in the stream-chat-container.tsx file. This wraps the interface, passing the initialised client to provide access to Stream’s chat functionality.

The <Channel> component renders the active channel (created in the useMemo hook), and the <Window> organises the layout.

"use client"
import { useEffect, useMemo, useState } from "react"
import { StreamChat } from "stream-chat"
import {
  Chat,
  Channel,
  ChannelHeader,
  MessageList,
  MessageInput,
  Window,
} from "stream-chat-react"
import "stream-chat-react/dist/css/v2/index.css"
import { SmartReplyBar } from "./smart-reply-bar"

return (
  <Chat client={client} theme="str-chat__theme-dark">
    <Channel channel={channel}>
      <Window>
        <ChannelHeader title="Live Stream Chat" live />
        <MessageList />
        <SmartReplyBridge />
        <MessageInput focus />
      </Window>
    </Channel>
  </Chat>
)

ChannelHeader displays the channel name (Live Stream Chat) with a live indicator, MessageList shows the conversation history, and MessageInput provides a text input for sending messages. For custom styling, we use styles/globals.css to define a dark theme with Tailwind CSS:

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  // ... (Other theme variables)
}

The complete code for the UI is available in the GitHub repository.

For the chat UI, we adapt a Discord-like feel to the interface, create a discord-chat-layout.tsx file in the /components directory, and enter the code below:

"use client"

import { useEffect, useRef } from "react"
import { StreamChat } from "stream-chat"
import { Chat, Channel, MessageList, MessageInput, useChatContext, useChannelStateContext } from "stream-chat-react"
import { SmartReplyBar } from "./smart-reply-bar"

// Component to bridge Stream messages to SmartReplyBar
function MessageBridge() {
  const { messages = [] } = useChannelStateContext()
  const { channel } = useChatContext()

  const handleSelectReply = (reply: string) => {
    if (channel) {
      void channel.sendMessage({ text: reply })
    }
  }

  const simplifiedMessages = messages.map((m: any) => ({
    id: m.id,
    userId: m.user?.id || '',
    userName: m.user?.name || m.user?.id || 'User',
    text: m.text || '',
    timestamp: m.created_at ? new Date(m.created_at) : new Date(),
  }))

  return <SmartReplyBar messages={simplifiedMessages} onSelectReply={handleSelectReply} />
}

export function DiscordChatLayout({ userId, userName, client, channel }: DiscordChatLayoutProps) {
  const messagesEndRef = useRef<HTMLDivElement>(null)

  // Auto-scroll to bottom when messages change
  useEffect(() => {
    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" })
  }, [channel?.state?.messages])

  return (
    <div className="flex h-screen bg-[#1e1f22]">
      {/* Sidebar */}
      <div className="w-16 bg-[#2b2d31] flex flex-col items-center py-4">
        {/* Server icon and channels would go here */}
      </div>

      {/* Main Chat Area */}
      <div className="flex-1 flex flex-col">
        {/* Channel Header */}
        <div className="h-14 border-b border-[#1e1f22] bg-[#2b2d31] flex items-center px-4">
          <h2 className="text-white font-semibold"># general</h2>
        </div>

        {/* Messages */}
        <div className="flex-1 overflow-y-auto p-4 bg-[#313338]">
          <MessageList />
          <div ref={messagesEndRef} />
        </div>

        {/* Message Input */}
        <div className="p-4 border-t border-[#1e1f22] bg-[#383a40]">
          <MessageInput />
          <MessageBridge />
        </div>
      </div>
    </div>
  )
}

In the code above, we adapted a Discord-style UI for the interface with a dark theme and a message display area, styled with Tailwind. We customised Stream’s built-in components, such as MessageList and MessageInput, to align with Discord’s aesthetic while maintaining their real-time functionality.

We also added a connector component that bridges Stream’s message system with our AI Smart Reply feature. This component handles message data transformation to make sure that AI-generated replies appear seamlessly within the chat flow.

Now that we have the chat set up and integrated with Stream’s React SDK, let’s set up Synthetic, which we will use for the AI smart replies.

Setting up Synthetic

Synthetic is an AI Inference platform that provides a solution for running open-source AI LLMs, such as Llama, Mistral, and DeepSeek.

Visit the synthetic website and click on “Sign up” like so:

The authentication page will then load. You can sign up using your email address or use Google social login.

After signing up, you will be prompted to enter your username like so:

Next, your Synthetic dashboard loads like so:

Click on the icon in the top left to open the sidebar shown below, where you will get your API key.

In the API settings, copy your API key and add it to your environment variable file .env in the project’s codebase.

SYNTHETIC_API_KEY="your_api_key"

STREAM_API_KEY=”your_stream_api”
STREAM_API_SECRET=”your_stream_secret”

For this project, we will utilise the OpenAI LLM and its API URL within the codebase. You can find all the necessary information on the page shown above.

OpenAI API Base URL: https://api.synthetic.new/openai/v1

Note:

These are the available OpenAI-compatible endpoints to use with the base URL from Synthetic:

/models - Lists all always-on models and any recently used on-demand models
/chat/completions - Chat-based completions with conversation history
/completions - Traditional text completions
/embeddings - Transforms text into vector embeddings

We are integrating the chat completions feature in the app we’re building here in this guide. The chat completion from the LLM model will create a model response for a given chat conversation. The Synthetic documentation provides a guide on how to integrate this feature.

In the code, we will be making a POST request to the API base URL endpoint like so:

POST https://api.synthetic.new/openai/v1/chat/completions

When adding the LLM URLs, make sure they are added with this prefix, like so:

hf:openai/gpt-oss-120b

hf:meta-llama/Llama-3.1-405B-Instruct

These are the Always-on models available on Synthetic:

You can also use a specific LLM model by copying the model’s name to be used in the API. Learn more in the Synthetic API documentation.

Synthetic also supports LoRA models, which are Low-rank adapters, called "LoRAs"; they are small, efficient fine-tunes that run on top of existing models. They can modify a model to be much more effective at specific tasks.

Learn about other models like Embedding Models and On-Demand Models here.

Note: Depending on the length of the content you’re prompting using the AI inference API from Synthetic, you may be required to use a pay-as-you-go service or upgrade to a pro plan on Synthetic.

So, don’t fret if you come across errors like this 🙂

fetch to https://api.synthetic.new/openai/v1/chat/completions failed with status 402 and body: {"error":"Insufficient credits and no active subscription. Due to context lengths, a minimum balance of $1.1179648 is required to run meta-llama/Llama-3.3-70B-Instruct. Your current balance is $0.00. Go to https://synthetic.new/billing to subscribe or purchase credits."}

Synthetic API error (HTTP ${response.status}): {"error":"Insufficient credits and no active subscription. Due to context lengths, a minimum balance of $1.1179648 is required to run meta-llama/Llama-3.3-70B-Instruct. Your current balance is $0.00. Go to https://synthetic.new/billing to subscribe or purchase credits."}

at generateSmartReplies (/lib/synthetic-ai)

Now that we have the Synthetic setup, let’s integrate it into the codebase for the smart chats application.

Capturing Messages and Sending to Synthetic

We’ll use Stream’s message.new event to capture incoming messages from the chat, and then forward the message text and context (recent conversation history) to Synthetic’s inference API.

In components/stream-chat-container.tsx, create a component to capture messages and send them to Synthetic’s API. Add this code within components/stream-chat-container.tsx:

function SmartReplyBridge() {
  const { useChannelStateContext } = require("stream-chat-react") as typeof import("stream-chat-react")
  const { messages } = useChannelStateContext()

  type SRMessage = { id: string; userId: string; userName: string; text: string; timestamp: Date }
  const simplified: SRMessage[] = (messages ?? []).slice(-10).map((m: any) => ({
    id: m.id,
    userId: m.user?.id ?? "",
    userName: m.user?.name ?? m.user?.id ?? "User",
    text: m.text ?? "",
    timestamp: new Date(m.created_at || Date.now()),
  }))

  const { useChatContext } = require("stream-chat-react") as typeof import("stream-chat-react")
  const { channel } = useChatContext()

  const handleSelect = async (reply: string) => {
    await channel?.sendMessage({ text: reply })
  }

  return <SmartReplyBar messages={simplified} onSelectReply={handleSelect} />
}

The component uses Stream’s useChannelStateContext hook to access the latest messages in the channel. It captures the last 10 messages, mapping them to a simplified format (SRMessage) with IDs, user IDs, user names, texts, and timestamps.

These messages are passed to the component, which sends them to Synthetic’s API via the [api/smart-replies/route.ts](https://github.com/Tabintel/smart-chat/tree/master/app/api/smart-replies) endpoint. The useChatContext hook provides access to the channel object, used later for sending replies.

This setup listens for Stream’s message component implicitly through the reactive messages state, with real-time updates.

Generating Smart Reply Suggestions with Synthetic API

We define a function to call Synthetic’s API endpoint with the chat context and parse the API response to extract multiple thoughtful reply options.

In your lib directory, create a file named synthetic-ai.ts to integrate Synthetic’s LLM models, and enter the code below:

interface SimpleMessage {
  user: string
  text: string
}

export interface SmartReplyResult {
  replies: string[]
  isAI: boolean
  model?: string
}

export async function generateSmartReplies(messages: SimpleMessage[]): Promise<SmartReplyResult> {
  try {
    const apiKey = process.env.SYNTHETIC_API_KEY

    if (!apiKey) {
      return {
        replies: getContextualReplies(messages),
        isAI: false,
      }
    }

    const conversationContext = messages
      .slice(-10)
      .map((msg) => `${msg.user}: ${msg.text}`)
      .join("\n")

    const systemPrompt = `You are a smart reply assistant for a live chat application. Your job is to generate 3 short, contextually relevant, and natural reply suggestions based on the conversation.

Guidelines:
- Each reply should be 5-50 characters
- Make them casual, friendly, and conversational
- Match the tone of the conversation
- Use emojis sparingly and naturally
- Avoid generic responses
- Be authentic and human-like

Return ONLY a valid JSON array of 3 strings, nothing else. Example: ["That's awesome!", "Let's go!", "I'm down"]`

    const response = await fetch("https://api.synthetic.new/openai/v1/chat/completions", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${apiKey}`,
      },
      body: JSON.stringify({
        model: "hf:meta-llama/Llama-3.3-70B-Instruct",
        messages: [
          {
            role: "system",
            content: systemPrompt,
          },
          {
            role: "user",
            content: `Recent conversation:\n${conversationContext}\n\nGenerate 3 smart reply suggestions as a JSON array.`,
          },
        ],
        temperature: 0.7,
        max_tokens: 200,
      }),
    })

    // ... (Error handling and response parsing as provided)
  } catch (error) {
    console.error("Synthetic API error:", error)
    return {
      replies: getContextualReplies(messages),
      isAI: false,
    }
  }
}

The generateSmartReplies function integrates Synthetic’s LLM model: hf:meta-llama/Llama-3.3-70B-Instruct, to generate context-aware smart replies.

It retrieves the last 10 messages, formats them within a conversation context, and sends them to Synthetic’s API endpoint: https://api.synthetic.new/openai/v1/chat/completions, along with a system prompt that defines guidelines for concise, natural replies.

The API returns a JSON array of three replies, which are parsed and returned with isAI: true and the model name. If the API call fails (for example, due to a missing SYNTHETIC_API_KEY or rate limits), the getContextualReplies function provides fallback replies based on the conversations.

Here is the LLM system prompt in use for the chat app:

You are a smart reply assistant for a live chat application. Your job is to generate 3 short, contextually relevant, and natural reply suggestions based on the conversation.


Guidelines:
- Each reply should be 5-50 characters
- Make them casual, friendly, and conversational
- Match the tone of the conversation
- Use emojis sparingly and naturally
- Avoid generic responses
- Be authentic and human-like


Return ONLY a valid JSON array of 3 strings, nothing else. Example: ["That's awesome!", "Let's go!", "I'm down"]`

You can access the full code in this GitHub repository.

Next, in app/api/smart-replies/route.ts, create an API route to handle this logic:

import { type NextRequest, NextResponse } from "next/server"
import { generateSmartReplies } from "@/lib/synthetic-ai"

export async function POST(request: NextRequest) {
  try {
    const { messages } = await request.json()

    if (!messages || !Array.isArray(messages)) {
      return NextResponse.json({ error: "messages array is required" }, { status: 400 })
    }

    const result = await generateSmartReplies(messages)

    return NextResponse.json({
      replies: result.replies,
      isAI: result.isAI,
      model: result.model,
    })
  } catch (error) {
    console.error("Smart replies API error:", error)
    return NextResponse.json({ error: "Failed to generate smart replies" }, { status: 500 })
  }
}

This route receives messages from SmartReplyBar, calls generateSmartReplies, and returns the replies. The integration combines Stream’s real-time message data with Synthetic’s AI inference for dynamic suggestions.

Displaying the Smart Replies in the Chat

Next, we create a custom SmartReplyBar component and render the AI reply suggestions as clickable buttons under the message input.

In your /components directory, create a file named smart-reply-bar.tsx to display AI-generated reply suggestions, then add the following code:

"use client"

import { useState, useEffect } from "react"

interface Message {
  id: string
  userId: string
  userName: string
  text: string
  timestamp: Date
}

interface SmartReplyBarProps {
  onSelectReply: (reply: string) => void
  messages: Message[]
}

export function SmartReplyBar({ onSelectReply, messages }: SmartReplyBarProps) {
  const [replies, setReplies] = useState<string[]>([])
  const [loading, setLoading] = useState(false)
  const [isAI, setIsAI] = useState(false)

  useEffect(() => {
    if (messages.length === 0) return
    const t = setTimeout(() => {
      void generateReplies()
    }, 400)
    return () => clearTimeout(t)
  }, [messages])

  const generateReplies = async () => {
    setLoading(true)
    try {
      const formattedMessages = messages.slice(-5).map((msg) => ({
        user: msg.userName,
        text: msg.text,
      }))

      const response = await fetch("/api/smart-replies", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ messages: formattedMessages }),
      })

      if (response.ok) {
        const data = await response.json()
        setReplies(data.replies || [])
        setIsAI(data.isAI || false)
      } else {
        setReplies([])
        setIsAI(false)
      }
    } catch (error) {
      setReplies([])
      setIsAI(false)
    } finally {
      setLoading(false)
    }
  }
}

The SmartReplyBar component displays AI-generated replies as clickable Button components from the components/ui/button library.tsx below the message input. useEffect hook triggers generateReplies when new messages arrive from Stream’s messages via <SmartReplyBridge>.

generateReplies function sends the last five messages to the [api/smart-replies/route.ts](https://github.com/Tabintel/smart-chat/tree/master/app/api/smart-replies) endpoint, which calls Synthetic’s LLM to generate replies. AI replies are then stored in state and rendered as buttons with a dynamic style. The components/ui/button.tsx file defines reusable button styles:

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        // ... (Other variants)
      },
      size: {
        default: 'h-9 px-4 py-2 has-[>svg]:px-3',
        // ... (Other sizes)
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  },
)

This ensures consistent, accessible buttons for the AI smart replies from Synthetic’s Inference.

Sending Suggested Replies

We use sendMessage and the button click to call channel.sendMessage() with the chosen reply. The reply then gets added to the conversation instantly.
In components/stream-chat-container.tsx, the component handles sending selected replies like so:

const { useChatContext } = require("stream-chat-react") as typeof import("stream-chat-react")
const { channel } = useChatContext()

const handleSelect = async (reply: string) => {
  await channel?.sendMessage({ text: reply })
}

return <SmartReplyBar messages={simplified} onSelectReply={handleSelect} />

When you click a smart reply button in SmartReplyBar, the onSelectReply callback triggers handleSelect, which uses Stream’s channel.sendMessage method to send the selected reply to the channel. This integrates Stream’s Chat React SDK with Synthetic’s AI-generated replies, instantly adding the reply to the conversation. The useChatContext hook provides access to the channel object, ensuring that all messages in the chat are sent properly, along with smart AI-suggested replies.

Running the App

Now that we have set up the chat application and Synthetic API integration, let’s run the application.

To start the application, open your terminal (command prompt) and enter this command npm run dev like so:

Copy http://localhost:3000 and open it in your browser. The app then loads like so:

Enter a random user ID and Display Name, then click on Join Chat:

After you enter your ID and username, the app shows the “Connecting to Stream chat” loader:

The chat app then loads like so:

We used a Discord-like interface for the Frontend UI. Now, send a message in the chat space. When typing, you’ll notice some quick replies you can send, which are done with AI Inference using Synthetic.

As you send messages in the app, you can see the chat logs on your Stream dashboard.

Cloning the GitHub repository

To get up to speed, you can also clone the GitHub repository for the project directory, install the required dependencies, and run the chat application.

Open your command terminal and run this command:

git clone https://github.com/Tabintel/smart-chat.git

Then navigate to this directory.

cd smart-chat

After opening the directory, run this command to install all the dependencies needed for the project.

npm install --legacy-peer-deps

We use the “legacy-peer-deps” command to instruct npm to ignore peer dependency conflicts during package installation.

Once the dependencies are installed, run the npm run dev command to start the application. You can then open the 'http://localhost:3000' URL in your browser to test the chat app.

Next Steps

In this guide, we created a chat app using Stream and Synthetic, with AI-powered smart replies that save users time with one-tap responses, keep conversations active, and make your app feel more innovative and modern.

You can extend the features we’ve built to:

Include syncing responses across different channels.
Add multiple AI agents to handle diverse use cases, such as customer support, marketplaces, or workplace chat.

Happy coding! 🎉

Speed up your designs to functional web apps with Kombai

Ekemini Samuel — Wed, 03 Dec 2025 19:20:52 +0000

Ekemini Samuel

Oct 7 '25

From Figma to Production: How I Optimized Frontend Development Time by 70%

#webdev #programming #ai #kombai

Comments

11 min read

The Best AI Agent For Frontend - Kombai

Ekemini Samuel — Mon, 24 Nov 2025 09:31:33 +0000

AI Agents have evolved a lot from when I started using them in 2022 till now. If you pay close attention, you will notice that these agents are growing not just in capabilities, that is, the kind of task they can do, but in understanding, which in my opinion is far important than the type of tasks they do. I say this for two reasons:

An AI agent is as good as the person using it.
An AI agent with a deep understanding of a particular context or subject matter will outperform generalistic AI agents long-term.

If you look at this from a wide view, the same applies to humans. A person who has developed knowledge, understanding and expertise in one area, for example, Finance, has built not just skill but discipline over an extended period of time. Say that person wants to learn Product design in 6 months, it won’t be as difficult for someone who has not first focused on a particular skill.

Now to the main purpose of this article. In the coding space, there are lots of AI coding agents and assistants like v0, Cursor, Claude Code, Lovable, Bolt, and Anything. These AI agents can write code and build websites, web apps and mobile apps quite alright. However, if you examine the UI/UX and Frontend, you will notice that they are similar. Either in terms of colour gradients, fonts, typography, framework (mostly Next.js/Vue) and even more technical aspects like state management.

They get the job done, yes, but if you want an actual product you and other people will use, then you definitely have to be unique and quite technical (or you get a technical friend) to help you out.

I have been using the Kombai AI agent for some time now, specifically for the Frontend of my web application, and in this guide, I will show you why it’s the best AI Agent for frontend development while building the frontend of a bookstore application.

Let’s get started!

Prerequisites

To follow along, you need these:

Basic understanding of JavaScript.
NPM Installed.
An IDE like Windsurf, VS Code.
A Kombai account.

Kombai is an AI agent built specifically for frontend development. It converts Figma designs, images, or text into production-ready code with modern web frameworks like React, Next.js, and Tailwind. With Kombai, you have the flexibility to choose the tech stack or framework you want to work with.

Learn more about Kombai in this resource.

What Kombai Does (and Doesn’t Do)

Before we build, it is important to define the scope. To claim Kombai is the "best," we must clarify what it is best at.

Kombai is a specialised Frontend AI Agent.

What it does: It specialises in UI, layout, client-side logic, and component architecture. It is designed to work safely within production repositories, understanding your specific design system.
What it doesn’t do: It is not a backend or database agent. It won't configure your AWS servers or write complex SQL queries.

By focusing entirely on the frontend, Kombai achieves a level of fidelity in CSS, React state, and accessibility that generalist full-stack agents simply cannot match.

What makes Kombai the best AI coding agent for frontend

Many AI tools can generate code, but their underlying architectures differ. General-purpose models are trained on broad datasets, while some newer agents are highly specialised. This specialisation is key, as the agent's architecture is purpose-built for a specific domain, in this case, frontend development. This focused approach is evident in its core technology.

Let's break down the specific features that result from this specialisation. Here are some reasons why Kombai is different from other AI agents:

Specialised Context Engineering

Instead of generating a generic <button>, the agent can read a project's theme.js file and output a custom <StyledButton variant="primary">. This is the result of specialised context engineering.

Before generating code, the system scans the repository to learn its structure. It identifies the component library, ingests design system tokens (colours, fonts, spacing), and understands existing custom components. The goal is to produce code that is idiomatic to the specific project, helping it align with established patterns and reducing the need for manual refactoring.

Planning and Preview Workflow

The Kombai AI workflow is designed to be more transparent than a simple prompt-to-code process. It operates in stages. First, it generates a step-by-step plan in markdown, detailing how it will build the feature, for example:

Create UserProfileCard.jsx
Add props for userName and avatarUrl
Style using Tailwind CSS

The Frontend developer can then review and edit this plan before execution. Once approved, the system generates the code and presents it in a live preview within an isolated browser sandbox. This allows for a verification step to catch runtime issues or styling problems before committing the code to the local branch.

Figma Interpretation Engine

A common challenge for design-to-code tools is handling imperfect design files if layers aren't clearly grouped.

Kombia’s AI agent's interpretation engine is designed to be more resilient, directly interpreting and converting the Figma design files to code. This approach effectively converts design frames into responsive components with logical DOM structures, rather than relying on pixel-based or absolute positioning.

Built-in RAG for Frontend Libraries

Another key technology at play is (RAG) Retrieval-Augmented Generation. Many general-purpose models may "hallucinate" or use outdated syntax when trying to implement a specific library, as their knowledge is based on a static, broad training dataset.

A RAG-based system addresses this by connecting the language model to an external, up-to-date knowledge base. Here’s how it works:

Retrieval: When you ask the agent to build a component using, say, Chakra UI, it doesn't just rely on its general knowledge. It first retrieves relevant, up-to-date information and code patterns from its own curated and human-tested database of over 30 frontend libraries (like Tailwind, MUI, Shadcn/ui).
Generation: It then augments the prompt. It essentially tells its AI model:

“Here is the user's request, and here is the correct, best-practice pattern for doing this in Chakra UI. Now, generate the code."

This RAG-based approach improves the model's output in verified patterns. It's not remembering how to use a library; it's referencing a correct implementation in real-time. This method is designed to improve accuracy and ensure the generated code follows the best practices for that specific library.

Enterprise-Ready Security

For enterprise teams that use AI coding agents, security is non-negotiable. Kombai has these security features implemented from the beginning:

No Training on Your Code: Kombai does not train its base models on your private codebase.
SOC 2 Compliance: It adheres to strict security standards, making it safe for enterprise deployment.
Local Context: It builds context from your local repo to answer questions, keeping data boundaries respectful.

Pricing & Plans

Kombai offers a pricing tier for every stage of development:

Free Plan: Great for students and indie devs. Includes a set amount of credits/month to build small projects.
Pro Plan: Designed for solo founders and freelancers who need higher limits and faster processing.
Enterprise: For teams that need SSO, enhanced security, and custom context limits.

Building the Bookstore app with Kombai

We will be building a bookstore web app with authentication, book listings, a dashboard, and a checkout flow.

First, let’s set up Kombai in your IDE (Windsurf is the IDE used in this article)

Create your Kombai account, sign in and install the extension for your IDE, whether it’s VS Code, Cursor, Windsurf or Trae.

If you’re using Windsurf, when you click on the Kombai icon in the left sidebar, it opens like so:

On the right, you can read about the latest updates to the Kombai AI agent and learn how to use the features in your IDE.

Click Open Folder to open a folder or workspace and start using Kombai.

In your computer, create a folder and name it “bookstore”. Then open it in the Windsurf IDE with Kombai.

When you start the Kombai extension, it scans your workspace for context awareness. It loads and shows you this modal regarding the Plan Mode. This mode generates a detailed code plan for the task (from your prompts) before the AI agent starts generating the code.

Now that Kombai is set up, let’s proceed with building the bookstore app.

Planning before generating code

With most AI tools, the flow for building apps is mostly from text/prompt to action. When you prompt the AI tool, it immediately starts generating the code for the application. While that is faster, it does not give room to plan the task properly, which is helpful for making iterations during frontend development.

Kombai uses a more professional workflow: Plan, Code and Ask.

Plan: You describe the feature. Kombai generates a detailed markdown plan. This makes sure planning is done before any code generation.
Code: You review and approve the plan. Kombai then executes it, generating files and fixing its own errors.
Ask: You can ask questions about your repo without changing code.

In the Kombai chat, enter this prompt:

We will be building the frontend of a modern bookstore app. Let's plan the bookstore app and UI.
List all required screens, components, and user states for authentication, dashboard, checkout, and book browsing. 
Use React.js + Tailwind + TypeScript. Focus on clean visual hierarchy and modularity.

Note: You can also instruct Kombai to turn your designs into code by either entering a link to the Figma file or directly connecting Figma by clicking on the Connect Figma button in the image.

Before you send the prompt, click on the Code dropdown and select Plan. This will create a structured plan before coding.

When you have selected the Plan mode, send the prompt to Kombai. It then lists the tech stack that will be used. You can either let Kombai AI scan the workspace for any files, configure the tech stack to be used and then proceed.

Now click on Proceed. The AI agent then prepares a comprehensive plan, including all of these. Scroll down the plan.md document or click on the file icon at the top right to expand the view.

Design philosophy: For the design philosophy, the AI agent suggests the visual identity as a modern, clean, editorial-inspired design with a focus on book discovery.

Screen architecture: The screen architecture shows the screens for the bookstore app, the routes where authentication is required, and the purpose of each screen.

Component breakdown: The AI agent also lists all the components needed, like the layout, authentication, book components, shopping, dashboard, the shared UI, and other components needed in the bookstore app

User state management: Next is the state management, which includes the state domains, storage, key data and type definitions.

Authentication flow: The AI agent also creates a visual representation of the authentication flow, from when the user visits the bookstore app, authenticates, adds a book to the cart and checks out. It also includes the Auth States: idle, loading, authenticated, error.

Checkout user journey: Next, we have the checkout user journey, which includes the steps, screens, actions and validation. The AI agent also includes a progress indicator and a stepper component (1/6 → 6/6).

Browse page layout: There is also the browse page layout, like the header (search, cart, user), filters sidebar, the book genre, price for each book and ratings.

Reusable patterns: The AI agent also lists reusable patterns, their usage and props to be used.

Accessibility checklist: It also adds the accessibility checklist, like ARIA labels for icon buttons, Alt text for all book covers, and screen reader announcements for cart updates.

Performance optimisations: The AI Agent also lists the performance optimisations with the strategies and how they will be implemented in the bookstore application.

The above metrics are important when developing the frontend of a web application, and it’s necessary to consider them before building. Instead of going directly to generating code.

The Kombai AI agent also lists the Todos (10) needed for the bookstore web app.

When you’re okay with the plan the AI agent generated, click on Approve Plan.

The AI agent now begins creating the bookstore application with the plan we approved.

Setting up the bookstore project

The Kombai AI agent begins creating the application and installing the needed dependencies with the npm command. Click Run like so:

While installing the dependencies, the AI agent loads the terminal to the right side and continues generating the code for the bookstore app. It lists every file it’s creating and the purpose for each one.

When the AI agent is done setting up the bookstore app project and generating the code files, it then shows a prompt to run the app with the npm run dev command. Click on the Run button as shown in the image below:

After the AI agent runs the bookstore application, it provides a local URL: http://localhost:5173 you can open in your browser to test the application. Also, you can open the preview in the Kombai Browser by clicking on the Kombai Browser.

The bookstore app then loads in the browser.

You can view all the books displayed like so:

Now we have the frontend of the bookstore developed with the Kombai AI agent. Next, we will check the agent-controlled and user-controlled browser features of Kombai.

Agent-controlled and User-controlled Browsers

The Kombai team shipped an update recently called the Kombai browser, which transforms how AI-assisted Frontend development works. It involves an Agent-controlled and User-controlled browser.

Let’s go deeper into the capabilities and use cases of each browser.

Agent-controlled Browser

The idea for the Agent-controlled browser is simple: instead of you running your app and manually checking everything, the agent can open your app and use it like a real user.

Watch this video to see the Kombai Agent-controlled browser in action.

It can navigate, click, type, scroll, and perform actions on the web application.

For the bookstore app we’re building, I asked the Agent to:

Open the browser, sign up, log in, and add a book to your cart

With the Agent-controlled browser, it loaded the bookstore app, created an accreated a new account, then logged in and added a book to the cart.

After the AI agent adds the book to the cart, it displays like so:

The AI agent also provides a summary of all the actions it took on the browser.

Here is a video showing how the Agent-controlled browser works when we give it the prompt

User-controlled Browser

The Kombai User-controlled browser lets you preview your app’s local deployment in the browser (optimised for Google Chrome and Chromium-based browsers), with built-in listeners so you can iterate fast by sending elements and errors back to Kombai as context.

To open the preview, follow these steps:

Click the Start Preview button below the Kombai input box. Kombai will start the dev server.

Once the server is running, click the Kombai Browser button to open the browser preview. Alternatively, press the Kombai Browser button that appears after the code generation process is completed.

You can also prompt the AI agent to make changes to the web app in real-time using the chat window, as shown in the image below.

You can also use the select elements button highlighted below to select any section that needs an update. This makes implementing additional changes faster using the user-controlled browser.

You can also initialise a GitHub repository directly with the AI agent by giving it a prompt and clicking on the Run button.

Initialise a GitHub repository, git add. git commit, and git push

You can clone the GitHub repository, install the required dependencies and run the bookstore application.

git clone https://github.com/Tabintel/bookstore.git

cd bookstore
npm install
npm run dev

And that’s it! We have built the frontend of a bookstore application with Kombai and tested it out using the Agent and User-controlled browsers.

Next Steps

The major takeaway from developing the frontend of applications with Kombai is that the AI agent works as an AI coding “partner”, not a plugin for an IDE. You can make updates to the bookstore by adding a community feature where other users can post comments on books they buy.

Optimise your frontend development today, start building with Kombai!

Analysing European Soccer Data with Deepnote in Windsurf IDE

Ekemini Samuel — Tue, 11 Nov 2025 19:09:43 +0000

Word on the street? Deepnote is now open-source! Jakub Jurových, the Founder of Deepnote, announced on LinkedIn this week.

During my research, I found out that the European Soccer Database from Kaggle has 25K+ matches, 10K+ players, and 2008–2016 seasons across 11 leagues. In this guide will use Deepnote in Windsurf to analyse the European sports data from Kaggle for three use cases:

To find out which team improved most post-2012 from the data?
To predict "star players" and their value, with the Top 10 players by goal impact
To analyse win rates, goal differences, and home/away advantages over seasons for the teams

Let's get started!

Prerequisites

You will need the following to proceed

A Kaggle account
Windsurf account and IDE installed on your computer
A Deepnote account

What is Deepnote?

Deepnote is a cloud-based, collaborative data science notebook platform that enhances Jupyter notebooks with real-time co-editing, integrated data connections, and simplified sharing, acting as a central workspace for teams to develop and deploy data-driven products. It supports Python, R, and SQL

To get started, we will download the European soccer database from Kaggle. Click on the Download button like so

Then click on Download dataset as zip

When the dataset is downloaded on your computer, extract it to your preferred directory. For this project, I created a directory on my computer called windsurf_deepnote. You can do the same and extract the dataset to that specific folder.

After the dataset is extracted, you get a file named database.sqlite in the directory.

Now that we have the dataset, lets setup Windsurf.

Setting up Windsurf IDE

Windsurf is an integrated development environment (IDE) for coding. It is similar to VS Code, with AI-first features.

Go to the Windsurf website, and download the application suited for your operating system (OS).

After it has downloaded, sign up with your preferred method, and open the Windsurf IDE with the directory you want to work with.

You can also view your Windsurf account activity in the profile section like so

Using Deepnote in Windsurf

Now we have the dataset and Windsurf setup, let's proceed to working with Deepnote in Windsurf.

Sign up here to create your Deepnote account

In the Windsurf IDE, go to the extensions tab at the left sidebar, search for Deepnote and click on the Install button like so

After it has installed, this tab loads. It has information on how to get started using Deepnote in Windsurf

Next, use the Ctrl+Shift+P command to create a new Deepnote project, and name it soccer.

It then creates a new project called soccer and loads a new Deepnote block, just as in the Deepnote web app UI

We are using Kaggle to get the football/soccer data that we will be analysing.

You can enter python code in blocks and run like so

If you want to convert a notebook to a deepnote notebook, open your terminal and run this command:

npx @deepnote/convert notebook.ipynb # This will convert the notebook and create notebook.deepnote

Enter yes (y) for the prompts that come up during installation

After it has been installed, Then open your .deepnote file in Windsurf IDE.

Implementing the data analysis of the three use Cases

From the soccer dataset, we will run each of this Python codes to analyse the data.

Find Teams That Improved Most Post-2012

We will find which teams improved most after 2012, by comparing average team performance (win rate, goals) before and after 2012

Enter this code:

import sqlite3
import pandas as pd
import matplotlib.pyplot as plt

# Connect to the SQLite database
conn = sqlite3.connect("database.sqlite")

# Load match data
matches = pd.read_sql_query("""
SELECT
    m.id, m.season, m.home_team_api_id, m.away_team_api_id,
    m.home_team_goal, m.away_team_goal,
    t.team_long_name AS home_team
FROM Match m
JOIN Team t ON m.home_team_api_id = t.team_api_id
""", conn)

# Compute win rate per team per season
matches["result"] = matches.apply(
    lambda x: "win" if x["home_team_goal"] > x["away_team_goal"] else 
              ("loss" if x["home_team_goal"] < x["away_team_goal"] else "draw"), axis=1)

team_stats = matches.groupby(["home_team", "season"])["result"].value_counts().unstack().fillna(0)
team_stats["win_rate"] = team_stats["win"] / (team_stats["win"] + team_stats["loss"] + team_stats["draw"])

# Split pre- and post-2012 averages
pre_2012 = team_stats[team_stats.index.get_level_values("season") < "2012/2013"].groupby("home_team")["win_rate"].mean()
post_2012 = team_stats[team_stats.index.get_level_values("season") >= "2012/2013"].groupby("home_team")["win_rate"].mean()

improvement = (post_2012 - pre_2012).dropna().sort_values(ascending=False).head(10)

# Visualize
plt.figure(figsize=(10,5))
improvement.plot(kind="bar", color="green")
plt.title("Top 10 Most Improved Teams Post-2012")
plt.ylabel("Win Rate Improvement")
plt.tight_layout()
plt.show()

After we run the code block above, we get this visualization:

From the data, we confirm that Juventus showed the biggest leap after 2012, improving their win rate by +30%.

Borussia Mönchengladbach and AS Saint-Étienne followed closely, both gaining around 25%, proving that the post-2012 era rewarded better management, new ownership money, and tactics.

Predict Star Players by Goal Impact

Next we predict star players and rank the Top 10 by goal impact score, by combining player attributes and match stats, then using regression to find impact.

Enter this python code block and run it:

import sqlite3
import pandas as pd
from sklearn.linear_model import LinearRegression
import matplotlib.pyplot as plt

conn = sqlite3.connect("database.sqlite")

# Load player data with names
players = pd.read_sql_query("""
    SELECT p.player_api_id, p.player_name, 
           pa.overall_rating, pa.potential 
    FROM Player p
    JOIN Player_Attributes pa ON p.player_api_id = pa.player_api_id
""", conn)

# Load match data
goals = pd.read_sql_query("""
    SELECT home_player_1, home_player_2, home_player_3, home_team_goal 
    FROM Match
""", conn)

# Aggregate goals by player
player_goals = goals.melt(
    value_vars=['home_player_1', 'home_player_2', 'home_player_3'],
    var_name='position', 
    value_name='player_api_id'
)
player_goals = player_goals.groupby('player_api_id').size().reset_index(name='goal_count')

# Merge with player data and calculate impact score
merged = players.groupby(['player_api_id', 'player_name']).mean().reset_index()
merged = merged.merge(player_goals, on='player_api_id', how='inner').dropna()

# Model goal impact
X = merged[['overall_rating', 'potential']]
y = merged['goal_count']
model = LinearRegression().fit(X, y)
merged['impact_score'] = model.predict(X)

# Get top 10 players
top_players = merged.sort_values('impact_score', ascending=False).head(10)

# Plot with player names
plt.figure(figsize=(12, 6))
plt.barh(top_players['player_name'], top_players['impact_score'], color='orange')
plt.title("Top 10 Star Players by Goal Impact Score", pad=20)
plt.xlabel("Predicted Impact Score")
plt.ylabel("Player Name")
plt.gca().invert_yaxis()
plt.tight_layout()
plt.show()

After running the code, we get this visualisation:

From the data, we confirm that Iker Casillas tops the list as the star player with the highest predicted goal-impact score (~41), followed closely by Sergio Ramos, Manuel Neuer, and Petr Čech. John Terry also rounds out the top spot.

Win Rate & Home Advantage Analysis

Then we analyse win rates, goal differences, and home/away advantages across seasons. We do this by comparing home vs away wins by season and visualize trends.

Run this python code block:

import sqlite3
import pandas as pd
import matplotlib.pyplot as plt

# Connect to the database
conn = sqlite3.connect("database.sqlite")

# Load match data with team names
matches = pd.read_sql_query("""
    SELECT 
        m.season,
        t1.team_long_name as home_team,
        t2.team_long_name as away_team,
        m.home_team_goal,
        m.away_team_goal
    FROM Match m
    JOIN Team t1 ON m.home_team_api_id = t1.team_api_id
    JOIN Team t2 ON m.away_team_api_id = t2.team_api_id
    WHERE m.season IS NOT NULL
""", conn)

# Calculate match results
matches['home_win'] = matches['home_team_goal'] > matches['away_team_goal']
matches['draw'] = matches['home_team_goal'] == matches['away_team_goal']
matches['away_win'] = matches['home_team_goal'] < matches['away_team_goal']

# Calculate win rates per team
home_stats = matches.groupby('home_team').agg({
    'home_win': 'sum',
    'home_team_goal': 'sum',
    'away_team_goal': 'sum'
}).rename(columns={
    'home_win': 'wins',
    'home_team_goal': 'goals_for',
    'away_team_goal': 'goals_against'
})

away_stats = matches.groupby('away_team').agg({
    'away_win': 'sum',
    'away_team_goal': 'sum',
    'home_team_goal': 'sum'
}).rename(columns={
    'away_win': 'wins',
    'away_team_goal': 'goals_for',
    'home_team_goal': 'goals_against'
})

# Combine home and away stats
team_stats = home_stats.add(away_stats, fill_value=0)
team_stats['total_matches'] = matches['home_team'].value_counts().add(
    matches['away_team'].value_counts(), fill_value=0)
team_stats['win_rate'] = (team_stats['wins'] / team_stats['total_matches']) * 100
team_stats['goal_difference'] = team_stats['goals_for'] - team_stats['goals_against']

# Get top 10 teams by win rate
top_teams = team_stats.nlargest(10, 'win_rate').sort_values('win_rate')

# Plotting
plt.figure(figsize=(12, 8))

# Create bar plot
bars = plt.barh(top_teams.index, top_teams['win_rate'], color='skyblue')
plt.title('Top 10 Teams by Win Rate', fontsize=16, pad=20)
plt.xlabel('Win Rate (%)', fontsize=12)
plt.ylabel('Team', fontsize=12)

# Add value labels
for bar in bars:
    width = bar.get_width()
    plt.text(width + 0.5, 
             bar.get_y() + bar.get_height()/2, 
             f'{width:.1f}%',
             va='center',
             fontsize=10)

plt.grid(True, linestyle='--', alpha=0.6)
plt.tight_layout()

# Save the plot
plt.savefig('team_win_rates.png', bbox_inches='tight', dpi=100)
plt.close()

print("Top 10 Teams by Win Rate:")
print(top_teams[['win_rate', 'total_matches', 'goal_difference']].sort_values('win_rate', ascending=False).to_string())

print("\nPlot saved as 'team_win_rates.png'")

After running the code, we get the visualization of the dataset like so:

We confirm that FC Barcelona dominates with a 77% overall win rate across the entire period, followed by Real Madrid (75%) and SL Benfica (74.6%). The data shows the classic home advantage of roughly 55–60% win rate for home teams throughout 2008–2016.

And that's it! We have a great analysis of the soccer data!

Next steps

Show the Deepnote some support and star the GitHub repository !😎

Thank you for reading!

This is the time to build AI apps, get started with this open-source repositories

Ekemini Samuel — Wed, 29 Oct 2025 14:06:24 +0000

Ankur Tyagi

Oct 29 '25

5 must know open-source repositories to build cool AI apps

#ai #opensource #agents #vision

Comments 19

4 min read

From Figma to Production: How I Optimized Frontend Development Time by 70%

Ekemini Samuel — Tue, 07 Oct 2025 15:37:04 +0000

Look, AI is getting lots of traction, we all know it! Unless you’re living in the woods or on a far island. Almost every product now digital and physical has a touch of AI added to it. Yes, that’s fun, but one way to get ahead it not by just being a “consumer” of this AI application. It’s good for you and future you to also be a producer.

Now, when building apps, it’s nice (and also industry standard) to have a UI design/mockup of your visionary application., which can be done with Figma. After designing with Figma, the next step is converting the designs to code and adding functionalities. Now you can do this by developing it yourself, or hiring a team of Frontend developers.

However with Kombai, the AI Agent built for Frontend development, you can get that done fast with AI. That’s what we will look at in this article by building an e-commerce website for buying and selling products like dresses, hoodies, shirts. Instead of spending time manually converting the UI design to code, we will plug in the Figma URL and let Kombai do the magic!

Ready? Let’s begin!

Prerequisites

To follow along, make sure you have all of this setup

Node and NPM/yarn are installed on your computer
A Figma UI design URL
An IDE like VS Code/Windsurf
React/Next.js knowledge
Knowledge of Express.js and Node.js
A Kombai account, sign up here

Note: Kombai is an AI agent built specifically for frontend developers. It works with your IDE; VS Code, Cursor, Windsurf, so you never leave your workflow. Kombai builds beautiful, functional frontends directly from Figma designs, plain text prompts, or your existing code. To know more, read this post.

What we are building

We’re building an e-commerce website for buying and selling products like dresses, hoodies, with authentication, cart functionalities, and checking out.

This is what the Figma design that we will convert with Kombai look like:

The landing and sign up page
The shopping cart

The e-commerce product will have:

The frontend

A landing page with all the products in it.
An authentication form for signing up and signing in

The backend

API endpoints for authentication, products, categories, cart, orders
A database to store the users, carts.

Next we will connect the Figma URL for the above design for Kombai to generate the code.

Moving from Figma to code with Kombai in record time

If you’re new to Kombai, follow the installation steps in this guide. For those that have a Kombai account and have set up their IDE, let’s proceed!

Got to your IDE (Windsurf is used in this tutorial but other IDEs have a similar view), and the left sidebar, you will see the Kombai icon as highlighted with the checkmark below.

It then asks you to Log in or Sign up, click on the Log in button, which then loads your browser, and shows a successful login page. Click on Go back to editor to proceed.

After signing in to Kombai through your browser, this modal shows in your IDE, click on the Open button (don’t worry, it’s all good 😊)

Now we are ready to proceed!

Creating the Frontend from Figma with Kombai

There are two ways to connect Figma designs to Kombai so it converts and generated the code for the designs:

Adding the Figma design link/URL
Connecting your Figma account and importing the designs

In this article, we will be using option 1, which is adding the Figma design URL to Kombai. To do this, open your Figma design file and copy the share link to the specific screen or frame you want to code. Kombai uses this link to interpret the design, extract components, and generate accurate frontend code

Open your terminal and run this command to create a Next.js application for the frontend.

npx create-next-app@latest
cd project_name

Open the Kombai panel in your IDE and paste the Figma link

In the Kombai panel, paste the Figma link to your Authentication screen in the Figma file. Kombai will fetch the design and start analyzing it.

Once the Figma link is pasted, Kombai will begin indexing the design and will prepare it for the next steps. You’ll see a preview of the design you're working with.

With Kombai connected to your design, you can see a live preview of your Figma file. It’s now ready to generate production-ready code for the frontend.

Add a prompt tells Kombai what to do. This guides Kombai to handle both UI and API integration.

You are to build the fully functional frontend for the e-commerce design as shown in the Figma file from the URL I shared with you. We have a backend for the e-commerce that you will integrate to the Frontend you are building

Let Kombai scan your workspace

Kombai will scan your Next.js project to understand the folder structure, installed libraries, and configurations. This ensures that the code it generates aligns perfectly with your project setup.

Once Kombai starts scanning your project, it analyzes your codebase to detect libraries, configurations, and folder structure.

Kombai then identifies the framework, component libraries, and router being used in the project. Here, Kombai detected NextJS 15, Tailwind v4, and the App Router.

Now that Kombai is connected to the Figma file and your codebase is indexed, let’s generates the code for all the pages/screens in the Figma design. You can follow the exact same process for any other page in your design (product listing, cart, checkout)

Review and approve the plan

Before writing any code, Kombai presents a step-by-step plan showing what components will be created, how the layout will be structured, and where files will be placed. Review this plan carefully,you can edit or fine-tune it if needed, then hit Approve.

Run it in the local sandbox

Instead of writing directly into your repo, Kombai generates the page inside a sandbox. You can preview the Authentication page, test the UI states (login form, error handling), and check that the design matches the Figma file.

Save to your project

Once satisfied, save the generated code into your repo. Kombai will create the files under your project structure.

At this point we have successfully generated the UI for the Authentication page with Kombai. You can repeat this exact workflow for the other pages.

Integrating the backend API endpoints with Kombai

Now that we have generated the UI with Kombai, the next step is to connect it with the backend APIs. Kombai is not limited to only building UI components, it can also help you generate API interaction code directly inside your frontend components.

In this scenario, we will integrate the Authentication endpoints (/api/signup and /api/signin). Once you understand the workflow, you can repeat the same process for products, cart, and other features.

With the e-commerce signup page UI generated, we will then instruct Kombai to connect the sign up form with our backend API.

Open the Komabi chat in the left side bar as shown below

Providing the prompt for Kombai

The way you prompt AI agents matter a lot, you got to make sure the instructions are clear and direct, so you get exactly the result you want. To connect the sign up form to the backend API, enter this prompt:

Generate code to connect this signup form to the backend API.
    - Use fetch() to make POST requests to `/api/signup`.
    - Send email and password from the form.
    - Show error messages if the API fails.
    - Show success message and redirect to the signin page on success.

Kombai will read your existing page.signup.tsx file, and generate the the form submission logic without breaking your styling or layout.

Review the Plan

Kombai will show you a plan of what files and functions it wants to update. Review this carefully and make changes where you want to make the changes, after that approve the plan and save it.

To make it more fun, you can extend the same workflown above as it applies to other parts of the e-commerce application. From the signin, to products, cart, and checkout. You will need to tweak the prompt slightly depending on the endpoint you want to hit and the page you are working on.

Running the frontend project

After you have integrated the whole endpoints with using Kombai, open your command terminal and run the npm run dev command, which the starts the frontend application like so:

Copy the local app URL http://localhost:3000, and enter it in your preferred browser to load the e-commerce website.

When the application is running, it displays like so:

Setting up the backend for the frontend we have built with Kombai

Now that we have the Frontend setup, converting the Figma design to code, let’s quickly set up the backend.

In your computer, create a new folder, and open it in your command terminal, then run these commands to create and navigate to the backend directory.

mkdir ecom-backend && cd ecom-backend
npm init -y

Install the needed dependencies for the project with these commands

npm i express mongoose cors dotenv bcrypt jsonwebtoken express-validator axios
npm i -D nodemon

After the dependencies have been installed, create a .env file in the root of your project’s directory to securely store the environment variables:

PORT=5050
MONGO_URI=mongodb://127.0.0.1:27017/ecommerce
JWT_SECRET=super_secret_change_me
JWT_EXPIRES_IN=1h

This is the project tree for how the backend for the e-commerce would be


├─ .env
├─ package-lock.json
├─ package.json
└─ src
   ├─ config
   │  └─ db.js
   ├─ controllers
   │  ├─ auth.controller.js
   │  ├─ cart.controller.js
   │  ├─ category.controller.js
   │  └─ product.controller.js
   ├─ index.js
   ├─ middleware
   │  ├─ auth.js
   │  └─ error.js
   ├─ models
   │  ├─ Cart.js
   │  ├─ Product.js
   │  └─ User.js
   ├─ routes
   │  ├─ auth.routes.js
   │  ├─ cart.routes.js
   │  ├─ category.routes.js
   │  └─ product.routes.js
   └─ utils
      └─ validate.js

Next, configure package.json file:

"scripts": {
  "dev": "nodemon src/index.js",
  "start": "node src/index.js"
}

This script allows you to run your application in development mode with nodemon, using npm run dev and start the application in production mode using npm start.

Now that the backend start script is set up, create a User model file src/models/User.js with the following code:


const mongoose = require("mongoose");
const bcrypt = require("bcrypt");

const UserSchema = new mongoose.Schema(
  {
    name: { type: String, trim: true, required: true },
    email: { type: String, trim: true, required: true, lowercase: true, unique: true },
    passwordHash: { type: String, required: true },
    role: { type: String, enum: ["customer", "admin"], default: "customer" }
  },
  { timestamps: true }
);

// Virtual setter to hash on create/update when using user.setPassword(plain)
UserSchema.methods.setPassword = async function (plain) {
  const salt = await bcrypt.genSalt(10);
  this.passwordHash = await bcrypt.hash(plain, salt);
};

UserSchema.methods.comparePassword = async function (plain) {
  return bcrypt.compare(plain, this.passwordHash);
};

// Hide sensitive fields in JSON
UserSchema.methods.toJSONSafe = function () {
  const obj = this.toObject();
  delete obj.passwordHash;
  return obj;
};

module.exports = mongoose.model("User", UserSchema);

This defines a User model with password hashing, comparison, and secure JSON output.

Validation Helpers

After the user models are setup, create validation helpers in the src/utils/validate.js directory with the following code:

const { body, validationResult } = require("express-validator");

const registerRules = [
  body("name").isString().trim().isLength({ min: 2 }).withMessage("Name is required"),
  body("email").isEmail().withMessage("Valid email is required"),
  body("password").isLength({ min: 6 }).withMessage("Password must be at least 6 chars")
];

const loginRules = [
  body("email").isEmail().withMessage("Valid email is required"),
  body("password").isLength({ min: 6 }).withMessage("Password must be at least 6 chars")
];

function validate(req, res, next) {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(400).json({ ok: false, errors: errors.array() });
  }
  next();
}

module.exports = { registerRules, loginRules, validate };

This utility provides validation rules for user registration and login, along with a validate function to check for errors.

Adding the authentication middleware

Create an authentication middleware file src/middleware/auth.js with this code:

const jwt = require("jsonwebtoken");

function auth(requiredRole = null) {
  return (req, res, next) => {
    try {
      const header = req.headers.authorization || "";
      const [scheme, token] = header.split(" ");
      if (scheme !== "Bearer" || !token) {
        return res.status(401).json({ ok: false, message: "Unauthorized" });
      }
      const payload = jwt.verify(token, process.env.JWT_SECRET);
      req.user = payload; // { id, role, iat, exp }
      if (requiredRole && payload.role !== requiredRole) {
        return res.status(403).json({ ok: false, message: "Forbidden" });
      }
      next();
    } catch (err) {
      return res.status(401).json({ ok: false, message: "Unauthorized" });
    }
  };
}

module.exports = { auth };

This middleware above authenticates requests made to the backend server using JSON Web Token (JWT)

To connect it all together, create the main application file src/index.js with the following code:


require("dotenv").config();
const express = require("express");
const cors = require("cors");
const { connectDB } = require("./config/db");
const { errorHandler } = require("./middleware/error");

const authRoutes = require("./routes/auth.routes");
const productRoutes = require("./routes/product.routes");
const categoryRoutes = require("./routes/category.routes");
const cartRoutes = require("./routes/cart.routes");

async function main() {
  await connectDB(process.env.MONGO_URI);

  const app = express();

  app.use(cors());           // Lock this down to your frontend origin in prod
  app.use(express.json());   // Parse JSON bodies

  app.get("/", (_req, res) => res.send("Ecommerce API is up"));

  // Routes
  app.use("/auth", authRoutes);
  app.use(productRoutes);
  app.use(categoryRoutes);
  app.use(cartRoutes);

  // Error handler
  app.use(errorHandler);

  const port = process.env.PORT || 5050;
  app.listen(port, () => console.log(`🚀 API listening on http://localhost:${port}`));
}

main().catch((e) => {
  console.error("Fatal startup error:", e);
  process.exit(1);
});

This sets up the Express server, connects to the database, applies middleware, routes requests, and starts listening on the specified port.

Running the backend

To run the backend, ensure MongoDB is installed and running locally. Navigate to the ecom-backend directory and run this command:

npm install
npm run dev

This starts the server on http://localhost:5050. It will automatically restart if you make changes to the code. Note that it relies on the .env file for configuration, so ensure it’s set up correctly.

And that’s it! From a Figma design to a full stack e-commerce website, we have our frontend and backend all connected!

To load the frontend as we mentioned in the frontend section above, open this URL http://localhost:3000, in your browser, and the frontend loads like so

The Sign in page
The products page

How We Actually Optimized Frontend Development Time by 70%

Kombai reduced my frontend development time for building this full-stack e-commerce website by 70%, bringing it down from hours of manual work to just minutes. Here’s how it worked for this project:

Figma Parsing: Kombai automatically processed the Figma design, saving time on manual asset extraction.
In-IDE Chat Prompting: I used the chat panel to quickly request changes, avoiding extra steps.
Repo Indexing: Kombai understood my project setup, saving time on manual adjustments.
Auto-Fixing & Preview: Errors were fixed instantly, and previews helped catch issues early.
Efficient Code Generation: Kombai created clean, usable code right away, speeding up the process.

This time save came from Kombai’s ability to handle the entire workflow smoothly.

Check out more examples of how to build great frontends with Kombai here

Next steps

Turning Figma designs into production-ready frontends has always been one of the most time-consuming parts of my workflow, but using Kombai changed that. Instead of spending hours translating layouts, adjusting components, and fixing TypeScript errors, I was shipping pixel-perfect UIs in a very short time.

Learn more from the Kombai documentation

Got Figma designs from your UI/UX designer? Add the designs to Kombai, let it generate the Frontend code in record time!

I Tried Kombai in My IDE: Here’s Why It Outperforms Cursor, Claude, and Copilot for Frontend

Ekemini Samuel — Tue, 30 Sep 2025 16:59:13 +0000

Frontend development can be a grind if you don’t play it smart, from TypeScript errors that break your flow, and general-purpose AI agents. After trying out Cursor, Claude Code, and GitHub Copilot, I decided to test Kombai, a frontend-specialized AI agent, to build the Frontend for my projects as I mostly build APIs, servers with my backend development skills.

Every new product launch needs a way to capture early interest, that’s where a waitlist website comes in. Instead of building the full product right away, you create a simple landing page where people can sign up, and stay informed for the product launch.

In this guide, we’ll build a waitlist website for a tech product,Futturee, the waitlist will have a landing page, a signup form, and a backend to store signups, all with Kombai.

Ready? Let’s get started!

Prerequisites

To follow along, make sure you have all of this

Node and NPM/yarn installed on your computer
An IDE like VS Code/Windsurf
React/Next.js knowledge
Knowledge of Express.js and Node.js
A Kombai account, sign up here

The waitlist we are building will have these:

Frontend (Landing page)

A clean landing page with a product headline and short description.
A signup form where users can enter their email and a confirmation message after a successful signup

Backend (API & Storage)

An API endpoint to handle form submissions.
A database to store the email signups.

Project Setup

Now let’s get into building the project, we’ll start building the backend

Backend

Create a new folder, and open it in your command terminal. Then run these commands to create and navigate to the backend directory

mkdir waitlist-backend && cd waitlist-backend
npm init -y

Then install the needed dependencies for the project

npm install express cors mongoose dotenv

After the dependencies have been installed, create an .env file to securely store the environment variables:

PORT=5000
MONGO_URI=mongodb://127.0.0.1:27017/waitlist  # local example
ADMIN_TOKEN=your-secret-token

Next, add the start script in package.json file like so:

"scripts": {
  "start": "node index.js"
}

When building the backend for a project, the index.js file contains the main server code for the project, so in the root directory, create the file and enter this code below:

require("dotenv").config();
const express = require("express");
const mongoose = require("mongoose");
const cors = require("cors");

// --------------------------------------------
// Config
// --------------------------------------------
const PORT = process.env.PORT || 5000;
const MONGO_URI = process.env.MONGO_URI;
const ADMIN_TOKEN = process.env.ADMIN_TOKEN || null;

// --------------------------------------------
// Mongoose Setup
// --------------------------------------------
mongoose
  .connect(MONGO_URI, { useNewUrlParser: true, useUnifiedTopology: true })
  .then(() => console.log("✅ Connected to MongoDB"))
  .catch((err) => {
    console.error("❌ MongoDB connection failed:", err);
    process.exit(1);
  });

// Define schema & model
const waitlistSchema = new mongoose.Schema({
  email: { type: String, required: true, unique: true, lowercase: true, trim: true },
  joinedAt: { type: Date, default: Date.now },
});

const WaitlistEntry = mongoose.model("Waitlist", waitlistSchema);

// --------------------------------------------
// Express Setup
// --------------------------------------------
const app = express();
app.use(cors());
app.use(express.json());

// --------------------------------------------
// Routes
// --------------------------------------------

// Health check
app.get("/", (_req, res) => {
  res.send("Waitlist API is running with MongoDB.");
});

app.post("/api/join", async (req, res) => {
  try {
    const { email } = req.body;

    // Basic validation
    if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
      return res.status(400).json({ ok: false, message: "Invalid email address." });
    }

    // Normalize
    const normalized = email.toLowerCase().trim();

    // Try to save
    const existing = await WaitlistEntry.findOne({ email: normalized });
    if (existing) {
      return res.status(200).json({ ok: true, message: "Already on the waitlist." });
    }

    await WaitlistEntry.create({ email: normalized });
    return res.status(201).json({ ok: true, message: "Added to waitlist." });
  } catch (err) {
    console.error("Error adding to waitlist:", err);
    return res.status(500).json({ ok: false, message: "Server error." });
  }
});

app.get("/api/stats", async (_req, res) => {
  try {
    const count = await WaitlistEntry.countDocuments();
    res.json({ ok: true, count });
  } catch (err) {
    console.error("Error fetching stats:", err);
    res.status(500).json({ ok: false, message: "Server error." });
  }
});

app.get("/api/waitlist", async (req, res) => {
  if (!ADMIN_TOKEN) {
    return res.status(404).json({ ok: false, message: "Admin route disabled." });
  }

  const token = req.header("x-admin-token");
  if (token !== ADMIN_TOKEN) {
    return res.status(401).json({ ok: false, message: "Unauthorized." });
  }

  try {
    const entries = await WaitlistEntry.find().sort({ joinedAt: -1 });
    res.json({ ok: true, data: entries });
  } catch (err) {
    console.error("Error fetching waitlist:", err);
    res.status(500).json({ ok: false, message: "Server error." });
  }
});

// --------------------------------------------
// Start Server
// --------------------------------------------
app.listen(PORT, () => {
  console.log(`🚀 Server running on http://localhost:${PORT}`);
});

The script connects to MongoDB using Mongoose, stores waitlist signups in the "waitlist" collection, provides public endpoints for POST /api/join and GET /api/stats, and includes a protected admin endpoint for GET /api/waitlist

Frontend Setup With Kombai

Now that we have the backend for the waitlist application, let’s start building the Frontend waitlist with Kombai.

Again, are you ready? 😎

What is Kombai?

Kombai is an AI agent built specifically for frontend developers. Kombai works with your IDE, such as VS Code, Cursor, Windsurf, or Trae, so you never leave your workflow.
Kombai builds beautiful, functional frontends directly from Figma designs, plain text prompts or your existing code.

Learn more about Kombai: https://kombai.com/why

It understands your codebase and follows the best practices of 30+ libraries.
Kombai is backend-agnostic, ensuring a safe and seamless integration for full-stack developers. It doesn't interact with your database or server logic, allowing you to maintain control over your APIs while Kombai focuses on crafting the frontend layer.

Follow these steps below to get started with the frontend.

Install Kombai as an extension in your preferred IDE and sign in from the Kombai side panel

Choose your preferred IDE to install Kombai

Depending on the IDE you’re using, when you sign up with your preferred method (Google, GitHub), it connects Kombai to your IDE and shows like so:

You can also install Kombai directly from the Extension marketplace of your IDE, if you’re using VS Code, go to the extensions tab, search for Kombai and install it:

Create the frontend project (Next.js and Tailwind)

In your project’s root directory, run this command to create a Next.js app for the Frontend of the waitlist project.

npx create-next-app@latest
cd project_name

Note: With Kombai, you can choose the tech stack and framework you want to use for your Frontend
This means you get to decide if you want to use NextJS v15, as the framework, or GraphQL for the API framework or state management, App router as the Router, the Component library like Chakra UI, the Styles, Icon pack, giving you more flexibility

Open the Kombai panel in your IDE and let it index the codebase

If you have an existing codebase, you got to first index the codebase with Kombai. Index in this context means Kombai reads through the files to understand their structure and context, such as; components, Tailwind configurations, and TypeScript types before implementing the tasks, ensuring accurate and codebase aligned code generation.

As shown here, Kombai is indexing the codebase

Then you input the first prompt to create the landing page for the waitlist, here is a prompt you can use, copy and paste it directly in your Kombai chat:

Goal: Create a minimal, production-ready waitlist landing page in my Next.js + TypeScript + Tailwind project.

Constraints:
- Detect whether this project uses the App Router (/app) or Pages Router (/pages) and place files accordingly.
- Create a responsive hero: product title, 1–2 line value prop, and primary CTA “Join the waitlist”.
- Keep styles clean and accessible (semantic tags, labels, aria-live for form messages).
- Use Tailwind classes; avoid third-party UI libraries.
- No placeholder lorem ipsum—write concise copy.
- Add a centered container with max-w-screen-md and generous spacing on mobile.

Deliverables:
- A top-level page component (app/page.tsx or pages/index.tsx).
- A simple Header and Footer as internal components for clarity.
- No external fonts or analytics yet.

Then Kombai shows you the Planning Phase; the plan it intends to follow to build the waitlist application, you can edit and refine the plan to meet your standards

It also shows you the artifacts (code files) that will be created for the Frontend it’s building

When you’re good with it, click on the Approve Plan & Start Coding button as shown above.

After Kombai is done generating the code files, and project requirements for the Futturee (let’s call the product we’re building the waitlist for Futturee) waitlist we are building, it shows a success message describing the features of the waitlist it built

To view each code file, click on the name of the file shown. As shown above, the files include the: Hero.tsx, Features.tsx, Testimonials.tsx, Footer.tsx, and the page.waitlist.tsx

Kombai also shows this modal for you to View and Save the code.

Here you can review the code, tell Kombai to make any adjustments or improvements

Kombai also shows you the Build & Config files used for the waitlist project like so:

Then you click on the Save button to proceed.

Run and previewing the waitlist frontend built with Kombai

Now that we have the waitlist ready, next is to run the application and preview it. If you’re conversant with Frontend technologies like Next/React, you should know how to run Next apps, if not you could simply ask Kombai, and it will list out the steps to run the app like so:

Basically, you open your terminal, navigate to the app directory with this command:

 cd Futturee

Next you initialize the project:

npm init -y

After initializing the project it shows this output

![Futturee(https://paper-attachments.dropboxusercontent.com/s_007B3CDC93D1CDCD28F50240403B0A0A65C22EA86112CEE8C31F078B607D9897_1759149306612_image.png)

Then you install the dependencies for the project:

npm install next@latest react@latest react-dom@latest typescript@latest @types/node@latest @types/react@latest @types/react-dom@latest tailwindcss@latest lucide-react@latest

After installation, next is to run the application, which is done with this command:

npm run dev

However, when we ran this, this error showed, which mention there is script not added to the package.json needed to run the app.

With Kombai, you can fix this error by copying the error message from the terminal, pasting it in the chat and prompting Kombai to fix it like so:

Kombai then proceeds to fix the errors

When it’s done fixing the errors, it shows a success message with a summary of what has been fixed and next steps to run the waitlist application

Now, we run the npm run dev command, and the app starts like so:

Copy the Local app URL: http://localhost:3000, and enter it in your browser to load the waitlist. When the application is running, the Waitlist we built with Kombai displays like so:

The waitlist frontend we built for Futturee is actually stunning and has an appealing UI, from the font to the typography and colour style!

Also with nice footer, including the waitlist CTA (Call to action)

Why Kombai Outperforms Cursor, Claude, and Copilot

Kombai shines where generic AI agents stumble, thanks to its frontend focus. Here’s why:

Flexible Tech Stack, (That’s my favourite feature)

You can freely choose the stack you want to work with for your Fronted, like I mentioned here:

> With Kombai, you can choose the tech stack and framework you want to use for your Frontend. This means you get to decide if you want to use NextJS v15, as the framework, or GraphQL for the API framework or state management, App router as the Router, the Component library like Chakra UI, the Styles, Icon pack, giving you more flexibility. This beats the rigidity of generic tools, letting you tailor the vibe to your project.

Clean, Maintainable Code

Trained on 30+ libraries’ best practices, Kombai separates UI from logic and reuses components, unlike Claude’s cluttered outputs.

Specialized Tooling and High Compilation Success

Kombai had editable plans, which it shows you before starting a task with live previews, and error fixing ensure quality. Also, with a 100% compilation rate vs. Copilot’s 60%, Kombai’s code runs out of the box, thanks to auto-fixing TS/lint errors

Repo Understanding

Kombai indexes your current codebase, reading, understanding and and matching the existing context, before building on it.

Human-Like Context

Using human-tested RAGs, Kombai onboards you like a developer, reusing props and UI, unlike generic agents’ shallow grasp. Benchmark tests also show this: 72% code review pass rate on 200+ tasks, far ahead of SOTA models.

Best Figma Interpretation

With Kombai’s engine you can extracts assets, UI’s directly from a Figam URL, and even connect your Figma directly with Kombai. This fixes messy layers (e.g., ungrouped nav), outperforming Cursor’s 75% fidelity and Claude’s 80% with 95% fidelity.

Here is a full preview of the Waitlist we built with Kombai:

And that’s it! We have built a Waitlist application with Kombai! Building a waitlist website may seem simple, but it touches the pain points that gives most coding agents issues: handling layouts, managing states, integrating forms/backends without having typescript errors, that’s where Kombai outperforms Cursor, Claude and Copilot for frontend development.

To learn more about Kombai and how it works under the hood, read the documentation.

While Cursor, Claude, and Copilot are solid all-rounders, Kombai’s frontend specialization approach delivered a cleaner UI, very few corrections and a smoother developer experience in building the frontend part in a full-stack application.

As software developers, we often have ideas for tech projects we want to ship, and these projects all need a Frontend and a Backend, not just any Frontend, one that is customizable to what we want. So instead of having generic UIs, try Kombai today, and build your next application!

Why Technical Writing is a Superpower in 2025

Ekemini Samuel — Sat, 27 Sep 2025 08:52:24 +0000

The rise of AI, blockchain, and decentralized technologies has made clear communication more important than ever. It’s not enough to build great tools, someone has to explain them in a way that’s accessible, accurate, and compelling.

That’s where technical writing comes in.

Whether you’re a developer, designer, or someone transitioning into tech, learning how to write tutorials, documentation, and explainers is a skill that can open doors to:

Better job opportunities in tech
Freelance and consulting work
Building your personal brand as a thought leader
Contributing to open-source projects more effectively

And here’s the truth: you don’t need to be a programmer to succeed in technical writing. You just need a technical skill, curiosity, and the ability to break down complex ideas for others.

That’s exactly why I created the Technical Writing Mentorship Program

https://bit.ly/learntechnicalwriting

It’s a 4-week guided program where I’ll help you:

Learn the foundations of technical writing
Create content that resonates with both developers and non-developers
Build a portfolio you can use to land jobs or freelance gigs
Develop the confidence to write clearly about fast-growing fields like AI and blockchain

Clear communication is a career superpower. The best time to start learning it is now.

👉 Apply here to join the mentorship program.

Learn and start writing, one day at a time

How nexos.ai is redefining AI integration for enterprises

Ekemini Samuel — Tue, 19 Aug 2025 12:40:23 +0000

Nexos is an AI orchestration platform that puts your business in control, and helps you join the AI revolution without security compromises. With Nexos, organizations gain centralized access to all major Large Language Models LLMs, with visibility into usage, control over access, and guardrails that keep your data where it belongs.

AI is powerful, mostly when one user interacts with it, but deploying it across teams? Most companies are trying to figure that out, and also where Nexos.ai comes in. We'll learn more about the Nexos solution in this article.

you can learn more about Nexos in this video

Products and features

There are two main products from Nexos.ai, which are; the AI workspace, and AI gateway.

Let's look at each of them!

1. AI workspace

The Nexos AI workspace is a secure, centralized interface where teams can chat with, test, and compare large language models (LLMs) from one place.

From a single browser tab, your employees can access models from OpenAI, Anthropic, Google, Meta, and other leading AI providers. No extra apps, no hidden tools, and everything runs within your organization’s security and usage policies.
You decide which models are available, and your teams can choose which one to use, all from one prompt window.

2. AI gateway

An AI gateway is a service that transforms how businesses access, manage, and use large language models (LLMs). It works as a centralized hub for enterprise AI operations, handling everything from smart model routing to ensuring secure and compliant use.
With Nexos, the gateway becomes more than just a connector.

It helps you:

Connect multiple LLMs through a single, secure endpoint
Control costs and optimize your AI traffic
Gain visibility, manage access, and track usage

With these solutions, Nexos gives a platform designed to help enterprises orchestrate, govern, and scale AI across every team, while solving three big pain points:

Fragmentation: AI teams often work in silos. Nexos connects them.
Security and Compliance: You can’t scale AI without governance. Nexos integrates enterprise-level controls.
Tool Chaos: Most teams use different tools for models, workflows, and LLMs. Nexos brings everything into one ecosystem.

In 2025, AI adoption is mentioned almost everyday, but most companies are stuck with too many choices of LLMs and when/how to use each of them across board.

They have access to different models and AI environments, but they lack:

A central place to deploy and manage them
Access controls and permissions
Governance logs
Collaboration between product and data teams

Nexos.ai gives you all of that, out of the box.

Who Should Use Nexos?

Whether you’re a:

Startup trying to scale your LLM product safely
Enterprise with 50+ AI use cases
Research lab testing multiple models at once

Nexos helps you go from chaos to control without slowing down innovation.

Use Cases for Nexos in your teams

Team	What They Get from Nexos
Product	Build AI into apps with ease
Engineering	Manage models and APIs in one place
Security	Enforce data governance policies
Leadership	Get visibility on AI usage company-wide

In the Superagency in the workplace: Empowering people to unlock AI’s full potential research by McKinsey & Company, this quote highlights how leaders drive the adoption of AI in companies:

Almost all companies invest in AI, but just 1 percent believe they are at maturity. Our research finds the biggest barrier to scaling is not employees—who are ready—but leaders, who are not steering fast enough.

With AI solutions like Nexos company leaders can efficiently drive the adoption of AI.

Next steps

Nexos is the all-in-one AI orchestration platform for enterprises. What are your thoughts about Nexos, and use cases for your business?
Share in the comments below : - )

P.S: read about the launch on Nexos and the funding from Index Ventures funding: https://nexos.ai/blog/nexos-launch/

Thank you for reading, I’m Ekemini Samuel, a Developer relations advocate and educator helping the next generation of developers grow. You can also subscribe to my newsletter, and say hi on Twitter/X.

Why Decentralized Compute Is the Future: My Developer POV on CUDOS Intercloud

Ekemini Samuel — Fri, 25 Jul 2025 20:30:39 +0000

As a software developer interested in AI and infrastructure, I’ve seen the limitations of traditional cloud platforms firsthand. Hosting AI models, especially large language models (LLMs) on centralized providers like AWS or GCP, often comes with high costs, complex onboarding, and limited scalability unless you’re part of a big tech company. For most indie developers and early-stage teams, it’s simply not sustainable.

That’s when I discovered CUDOS Intercloud, a distributed, performant, and developer-first alternative that changes the game.

This is my point of view (POV), and here’s the use case I’m building on it.

Ekemini is a Developer Advocate and Technical Writer, building software and educating in tech. He loves drums, music production, and is learning more about the AI industry.

Understanding CUDOS Intercloud: What Makes It Different?

CUDOS Intercloud is a distributed compute platform powered by data center-grade resources from around the world. It’s not just “someone’s unused laptop” plugged into a network, like in some decentralized compute systems. These are secure, high-quality, and sustainably powered resources from professional-grade data centers.

Here’s what stands out:

Performance and Affordability: Access GPUs and compute with hourly billings and not having to sign up for long-term contracts.
Smart Contract Integration: Perfect for Web3-native developers who need programmable infrastructure.
Security & Sustainability: Unlike platforms where you don’t know who’s running your compute, CUDOS relies on vetted data centers with a clear chain of trust.

This makes the CUDOS Intercloud not only distributed, but dependable.

My POV: CUDOS Unlocks the Future of AI Compute

Artificial Intelligence (AI) is evolving rapidly, but hosting large language models (LLMs) is still a big deal, especially for solo developers, researchers, and early-stage founders. It’s costly to train, fine-tune, and serve LLMs, vision models (VLMs), or any GPU-heavy workload.

I believe CUDOS Intercloud is the missing link. It offers compute accessibility without compromising performance or decentralization.

My vision is simple: Developers should be able to deploy and run inference workloads affordably, securely, and at scale, without being locked into Big Tech.

Use Case: AI Inference on CUDOS Intercloud

Using CUDOS, I’m working on a system to host large AI models for real-time AI inference directly on CUDOS-powered VMs.

How it works:

Developers can send requests to an AI model hosted on CUDOS (via API).
The model processes the input (prompt, image) and returns a response.
No need for the developer to rent an expensive GPU or manage infrastructure.

Workflow:

Log in, fund your wallet on the CUDOS Intercloud, and set up a Virtual machine according to your requirements
Then deploy the LLM you want to use, it could be: Llama, Mistral, on the VM you set up on CUDOS intercloud.
Expose an endpoint for inference
Developers or your users can interact with the LLM via a REST API
Inference happens on a decentralized infrastructure, which leads to efficiency and scalability.

This could power AI Chatbots and assistants, Edtech, research and productivity tools.

AI Developer Assistant Trained on CUDOS Docs

To support onboarding and developer adoption, I’ve also started building a chat-based AI assistant trained on CUDOS documentation and technical materials.

This assistant can:

Answer questions about CUDOS Intercloud
Recommend VM setup or compute configuration
Guide users through common tasks like launching nodes
Eventually act as a command line interface (CLI) co-pilot or low-code guide

Think of it as Docs-as-a-Bot, making learning and building with CUDOS faster and easier.

The Bigger Picture: Why This Matters

Decentralized doesn’t mean slow or unstable anymore. With CUDOS, you get real-world grade infrastructure with Web3 principles.
AI is becoming more fragmented. Developers need flexible compute that doesn’t require giving 100% of your stack to AWS or Google.
Cost, control, and community are all better with decentralized platforms like CUDOS. And for regions like Africa (where I’m based at the moment), this opens the door for more builders to access GPU resources to now deploy cutting-edge AI tools.

CUDOS isn’t just a tool I want to use. It’s a movement I want to contribute to.

From hosting AI workloads to onboarding new developers with custom assistants, I see real-world impact in what CUDOS offers, and I’m excited to help tell that story, build real use cases, and grow the ecosystem.

Let’s shape the future of distributed cloud together!

Building an AI Vacation Planner Chatbot with Facial Authentication using FACEIO & Next.js

Ekemini Samuel — Tue, 17 Jun 2025 15:53:19 +0000

Sites de viagem (alguns, pelo menos) têm muitos anúncios e, às vezes, poucas avaliações. E se você pudesse criar seu próprio agente de viagens que reconhece você, verifica sua idade e responde perguntas de viagem instantaneamente?

Neste tutorial, você construirá um chatbot de planejamento de férias alimentado por IA, seguro, que autentica usuários via reconhecimento facial usando FACEIO. Você integrará o Groq AI para conversas rápidas com IA e usará Next.js para criar uma interface moderna.

O FACEIO oferece um SDK JavaScript robusto de reconhecimento facial para permitir login sem senha em sites, autenticação biométrica e muito mais.

Pronto? Vamos começar!

Autenticação Facial com FACEIO antes de acessar o aplicativo Vacation AI

O Que Você Vai Aprender

Você aprenderá como integrar o SDK de reconhecimento facial FACEIO em um aplicativo Next.js, conectar e transmitir respostas de chat do Groq AI API, proteger seu aplicativo de IA com detecção de vivacidade e estruturar aplicativos full-stack com autenticação facial.

GitHub repository

Pré-requisitos

Make sure you have:

Certifique-se de ter:

Conhecimento básico de React e Next.js.
Node.js (v18+) e npm instalados no seu computador.
Uma conta FACEIO para obter sua chave de API.
Chave de API do Groq em console.groq.com.
Um IDE ou editor de código (como VS Code), Chrome ou Safari e uma webcam no seu computador.

What is FACEIO?

FACEIO é uma API de autenticação facial de ponta que permite que sites implementem login facial online usando tecnologia avançada de reconhecimento facial. Com recursos como API de detecção de vivacidade e SDK de detecção de deepfake, o FACEIO garante autenticação segura e resistente a fraudes. É ideal para casos de uso como::

Login sem senha para sites.
Autenticação facial para sites.
Verificação de idade.
Rastreamento de presença de funcionários.
Reconhecimento facial local.

FACEIO’s JavaScript SDK (@faceio/fiojs) é fácil de integrar, funciona em qualquer site e suporta navegadores modernos com acesso à webcam. Saiba mais na página de introdução do FACEIO.

Criando a Interface para a Página de Cadastro/Login do Vacation AI

Esta é a estrutura do projeto que estamos construindo:

vacation-ai/
├─ app/                 # Next.js app directory
├─ components/          # Shared UI and functional components
├─ hooks/               # Custom React hooks
├─ lib/                 # Utility functions and libraries
├─ public/              # Static assets (images, icons)
├─ styles/              # Global styles
├─ types/               # TypeScript type definitions
├─ config + build files # Tailwind, tsconfig, next.config, etc.

Antes de começar o design da interface para a página de cadastro/login do Vacation AI, vamos configurar um novo projeto Next.js usando o comando create-next-app. Isso nos dará uma base sólida para o aplicativo.

CCriar um Aplicativo Next.js para o Projeto

Abra seu terminal, navegue até a pasta do seu espaço de trabalho e execute o comando abaixo

npx create-next-app@latest vacation-ai

Esse comando cria um diretório vacation-ai com a estrutura padrão do projeto Next.js. Quando solicitado, selecione Sim para todas as opções (exceto a última — mantenha o alias de importação padrão). Isso instalará TypeScript, Tailwind CSS e todas as dependências necessárias para o seu projeto Vacation AI.

Agora, navegue até a pasta do seu novo projeto:

cd vacation-ai

Update your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./app/**/*.{js,ts,jsx,tsx}", "./pages/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {},
  },
  plugins: [],
};

In ./styles/globals.css, add Tailwind’s base styles:

@tailwind base;
@tailwind components;
@tailwind utilities;

Install the FACEIO library for facial authentication. Read the docs to learn more.

In the vacation-ai directory, run this command to install fio.js

npm i @faceio/fiojs

After installation, open the project in VS Code:

code .

To ensure TypeScript recognizes the FACEIO module, create a type declaration file.
Inside src/app, create a new file named faceio_fiojs.d.ts and add:

declare module "@faceio/fiojs"

This step allows you to import and use the SDK throughout the app without TypeScript errors.

Criando Componentes de Interface Reutilizáveis

Com a base pronta, podemos começar a construir os componentes de interface para o painel do Vacation AI.

Inside the src/app directory, create a components folder:

mkdir src/app/components

Now, create a file Sidebar.tsx and define your sidebar component:

// src/app/components/Sidebar.tsx
export default function Sidebar() {
  return (
    <aside className="w-64 h-screen bg-gray-900 text-white p-4">
      <h2 className="text-2xl font-bold mb-6">Vacation AI</h2>
      <nav>
        <ul className="space-y-4">
          <li><a href="/dashboard">Dashboard</a></li>
          <li><a href="/history">Booking History</a></li>
          <li><a href="/settings">Settings</a></li>
        </ul>
      </nav>
    </aside>
  );
}

Este componente Sidebar será usado em todas as páginas autenticadas do painel do Vacation AI.

Página inicial do aplicativo

Página de chat com IA do aplicativo

Configurando a Autenticação Facial

Now let’s add a “Login with Face” button. This button will:

Open the FACEIO camera UI
Capture the user’s face
Verify their identity
(Optionally) gate access based on age

In the app/auth directory, create a page.tsx file, and enter the code below. This is the code that integrates the authentication for the Vacation AI app with FACEIO.

'use client';

import { useState, useEffect } from 'react';
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import {
  Camera,
  CheckCircle,
  AlertCircle,
  ArrowLeft,
  UserPlus,
} from 'lucide-react';
import Link from 'next/link';
import { useRouter } from 'next/navigation';
import faceIO from '@faceio/fiojs';

export default function AuthPage() {
  const [authState, setAuthState] = useState<
    'idle' | 'scanning' | 'success' | 'error'
  >('idle');
  const [errorMessage, setErrorMessage] = useState<string>('');
  const [faceioInstance, setFaceioInstance] = useState<any>(null);
  const router = useRouter();

  // Initialize FACEIO
  useEffect(() => {
    if (typeof window === 'undefined') return;

    try {
      const fio = new faceIO(process.env.NEXT_PUBLIC_FACEIO_PUBLIC_ID);
      setFaceioInstance(fio);
      console.log('FACEIO initialized successfully');
    } catch (error) {
      console.error('Failed to initialize FACEIO:', error);
      setAuthState('error');
      setErrorMessage(
        'Failed to initialize facial recognition. Please refresh the page.'
      );
    }
  }, []);

  const handleError = (errCode: any) => {
    const fioErrs = faceioInstance?.fetchAllErrorCodes() || {};
    switch (errCode) {
      case fioErrs.PERMISSION_REFUSED:
        return 'Please allow camera access to proceed.';
      case fioErrs.NO_FACES_DETECTED:
        return 'No face detected. Please position your face in the frame.';
      case fioErrs.UNRECOGNIZED_FACE:
        return 'Unrecognized face. Please try again or register.';
      case fioErrs.MANY_FACES:
        return 'Multiple faces detected. Ensure only one face is visible.';
      case fioErrs.FACE_DUPLICATION:
        return 'User already enrolled. Please sign in instead.';
      case fioErrs.FORBIDDEN_ORIGIN:
      case fioErrs.EMPTY_ORIGIN:
        return 'Access restricted. Ensure your domain is whitelisted in the FACEIO console.';
      case fioErrs.TIMEOUT:
        return 'Operation timed out. Please try again.';
      default:
        return 'An error occurred. Please try again.';
    }
  };

  // Handle authentication 
  const handleAuthentication = async () => {
    if (!faceioInstance) {
      setAuthState('error');
      setErrorMessage('Facial recognition not initialized.');
      setTimeout(() => setAuthState('idle'), 3000);
      return;
    }

    try {
      await navigator.mediaDevices.getUserMedia({ video: true });
    } catch {
      setAuthState('error');
      setErrorMessage('Camera access denied. Please allow camera access.');
      setTimeout(() => setAuthState('idle'), 3000);
      return;
    }

This uses faceio.authenticate() to recognize registered faces.

You can also use faceio.enroll() to register new users with their facial biometrics.

Next up: we’ll plug in Groq’s LLaMA 3 API to build the AI-powered travel assistant — and connect it all.

Configurando a API do Chatbot Vacation AI com Groq LLaMA 3

Para alimentar nosso chatbot com o LLaMA 3 do Groq e dar a ele uma personalidade única para planejamento de viagens, precisamos criar uma rota de API backend no Next.js.

No seu projeto Next.js, navegue até o diretório app/api/chat e crie um novo arquivo chamado route.ts. Em seguida, cole o seguinte código

import { createOpenAI } from '@ai-sdk/openai';
import { streamText } from 'ai';
import type { NextRequest } from 'next/server';

export const maxDuration = 30;

const groq = createOpenAI({
  baseURL: 'https://api.groq.com/openai/v1',
  apiKey: process.env.GROQ_API_KEY,
});

export async function POST(req: NextRequest) {
  try {
    const { messages } = await req.json();

    const result = streamText({
      model: groq('llama3-8b-8192'),
      messages,
      system: `You are VacaPlan AI, an expert vacation planning assistant. You help users plan amazing trips by:

      1. Understanding their preferences (budget, duration, interests, travel style)
      2. Suggesting destinations that match their criteria
      3. Creating detailed day-by-day itineraries
      4. Recommending accommodations, activities, and restaurants
      5. Providing practical travel tips and budget breakdowns

      Always be enthusiastic, helpful, and provide specific, actionable recommendations. Format your responses clearly with headings, bullet points, and organized sections when providing itineraries.

      When creating itineraries, include:
      - Daily activities with time estimates
      - Approximate costs for each activity
      - Transportation recommendations
      - Restaurant suggestions for meals
      - Cultural tips and local customs
      - Weather considerations
      - Packing suggestions`,
      temperature: 0.7,
      maxTokens: 2000,
    });

    return result.toDataStreamResponse();
  } catch (error) {
    console.error('Chat API Error:', error);
    return new Response('Internal Server Error', { status: 500 });
  }
}

What This Code Does:

Imports AI SDKs: It uses the @ai-sdk/openai package to interface with Groq's OpenAI-compatible API.
Initializes Groq API: We set up a custom baseURL and authenticate using your GROQ_API_KEY environment variable.
Handles POST requests: When the frontend sends a list of messages (user chats), this API:
- Feeds the messages into the LLaMA 3 model.
- Sets a "system prompt" that trains the assistant to behave like a vacation planning expert (called VacaPlan AI).
- Returns a streamed AI response in real-time.

This route enables seamless backend communication for the chatbot. Now, whenever the frontend sends a chat message, the AI chatbot responds as if you hired your own expert travel planner ✈️🌍.

Integrando o FACEIO ao Aplicativo Web Next.js

At this point, we have the AI vacation planner and components. Next, we will integrate FACEIO to authenticate users when they sign up/log in, before accessing the AI chatbot.

Create a FACEIO account and sign in to your FACEIO Console to get the credentials needed to add Facial authentication.

On the FACEIO dashboard, click on New Application to create a FACEIO application, and follow the steps in the application wizard.

When asked to select a Facial Recognition Engine for the application, choose PixLab Insight. The engine will be used to map each enrolled user’s face in real-time into a mathematical feature vector, known as a biometric hash, which is stored in a sand-boxed binary index. This is used to protect the data of users when they are authenticated with FACEIO.

Your new FACEIO app will have an ID number; take note of it as we'll be using it to integrate FACEIO into the web application.

Go to the SignupForm.tsx file and declare a variable; faceio that will initialise the FACEIO SDK with your specific FACEIO application ID. The FACEIO app ID will be retrieved from an environment configuration env file.

In the root directory of your Next.js project, create a new file named .env.local and enter this to define the environment variable:

NEXT_PUBLIC_FACE_IO_ID=your_faceio_app_id_here

Replace "your_faceio_app_id_here" with your actual FACEIO application ID, and add .env.local to your .gitignore file

Running the Vacation AI application

Create an .env.local file in your root directory and add these details:


NEXT_PUBLIC_FACEIO_PUBLIC_ID=your-faceio-public-id
GROQ_API_KEY=your-groq-api-key

npm install
npm run dev

Go to: http://localhost:3000

The landing page shows in your browser like so:

Click on "Start Planning", it will redirect you to the Facial authentication page with FACEIO.

Authenticate → Chat → Get AI vacation plans!

There is also a setting where you access your user profile and update your travel preferences.

Facial Authentication with FACEIO before accessing the Vacation AI application

Chatting with the Vacation AI chatbot after Facial Authentication'

Próximos Passos

E é isso! Você acabou de construir o Vacation AI — um assistente de viagem seguro alimentado por um sistema de login facial usando o SDK de reconhecimento facial FACEIO e o chatbot LLaMA 3 do Groq. Essa arquitetura pode ser adaptada para outros casos de uso. Seja criativo. Você pode adicionar voz para texto para prompts de usuário para atualizar os recursos.

To learn more:

Explore the FACEIO Integration Guide for advanced features.
Join the FACEIO Community Forum for support and discussions.
Check the NPM page for SDK updates.
Visit the FACEIO website to learn more about biometric authentication API and passwordless login for websites.
Learn more in the FACEIO documentation.

Para explorar o código ou executar o projeto localmente, siga estes passos::

git clone https://github.com/Tabintel/vacation-ai.git
cd vacation-ai-app
npm install
npm run dev

🚀 Get the complete source code on GitHub.

Comece a construir aplicativos web seguros e amigáveis com autenticação facial para sites hoje!