DEV Community: Sohail

Integrating an AI Assistant into an Existing Application

Sohail — Mon, 26 Oct 2026 13:38:48 +0000

Adding an AI assistant to an existing application is not primarily a chat-interface problem. It is an application architecture problem.

The interface may be a small panel or a conversational screen, but the assistant still needs to authenticate users, retrieve the right information, respect existing permissions, call approved tools and fail safely when it cannot complete a task.

This tutorial walks through a practical architecture for integrating a large language model (LLM) into an existing web application. It covers authentication, retrieval-augmented generation (RAG), tool permissions, logging, evaluation, privacy and human handoff.

The examples are architectural illustrations, not a complete, production-ready implementation. Adapt them to your framework, identity provider, data model and chosen model API.

Start with the application boundary

Consider a hypothetical business application that lets staff search internal procedures and ask questions about customer-support workflows.

The assistant needs to answer questions using approved documents. Later, the product team may want it to retrieve a customer's order or initiate a support action.

These are different levels of capability. Reading a document is not the same as changing a record.

A useful starting architecture is:
User interface | v Existing application backend | +--> Authentication and authorisation | +--> Input validation and request limits | +--> Retrieval from approved data | +--> LLM API adapter | +--> Permission-checked tool execution | +--> Logging, evaluation and monitoring
Keep the model behind your application backend rather than exposing a privileged API credential in browser code. The backend should be responsible for deciding what context the model receives and which operations the current user may perform.

This boundary also gives you a place to enforce rate limits, redact sensitive fields, handle provider errors and apply application-specific policies.

Design principle: the model can propose an action; trusted application code must decide whether that action is permitted.

Reuse authentication, but enforce authorisation separately

An existing application usually already has a user identity system. Reuse it rather than inventing a parallel login mechanism for the assistant.

However, a logged-in user is not automatically entitled to access every record the model could retrieve.

For each request:

Authenticate the user using the application's established mechanism.

Resolve their current roles, organisation and relevant access scope.

Apply authorisation checks to every requested resource or operation.

Pass only the permitted context to the model.

Recheck permissions when executing any consequential action.

For example, suppose a staff member asks, “Summarise the latest support case for customer X.”

The backend should first determine whether that staff member may access the relevant case. It should not retrieve every matching case and rely on the model to select an appropriate one.

The same rule applies to retrieval-augmented generation. Filtering search results by tenant or access scope must happen before those results become model context.

Do not treat a system prompt such as “Never reveal confidential information” as an access-control mechanism. Instructions can guide model behaviour, but they cannot replace server-side authorisation.

Add retrieval-augmented generation where it solves a real problem

RAG is useful when answers need information from an organisation's documents or data that is not reliably available in the model's built-in knowledge.

A typical retrieval flow looks like this:
Question | v Validate request and resolve user scope | v Retrieve authorised, relevant content | v Apply relevance and context limits | v Build model input with source references | v Generate answer | v Return answer with appropriate citations
The retrieval layer might use keyword search, vector similarity or a combination of both. Choose based on the nature of the content, query patterns, latency requirements and the quality of the results—not simply because vector databases are fashionable.

A few implementation details matter:

Preserve access boundaries. Indexing documents does not remove the need to enforce access rules at query time.

Keep source metadata. Store identifiers and other metadata needed to trace a retrieved passage back to its source.

Control context size. More retrieved text is not necessarily better. Irrelevant passages can distract the model and increase processing cost.

Handle missing evidence. If retrieval produces no suitable material, the assistant should say it cannot find enough information rather than inventing an answer.

Plan for document changes. Define how updates, deletions and permission changes propagate to the index.

A useful test is whether the assistant can distinguish between “the source says this”, “the source does not cover this” and “the sources disagree”.

If those cases are indistinguishable in your interface, users may place more confidence in the answer than the evidence supports.

Treat tools as privileged application operations

An assistant becomes more consequential when it can call tools: for example, fetching an order, creating a support ticket or updating a customer record.

Do not give the model unrestricted access to your database or a general-purpose execution environment. Expose narrow, explicitly defined operations through your backend.

For instance, a tool definition might describe an operation like this:
{ "name": "get_order_status", "description": "Retrieve the status of an order the current user may access", "parameters": { "order_id": "string" } }
This is an illustrative schema, not a complete provider-specific tool definition.

When the model requests this operation, the backend should:

Validate the tool name and argument structure.

Reject unexpected fields and malformed identifiers.

Resolve the current user's permissions independently of the model.

Execute a narrowly scoped query.

Return only the fields required for the task.

Record the outcome using an appropriate audit policy.

Never assume that a tool call is authorised because the model requested it.

For a read-only operation, a successful permission check may be sufficient. For an action that changes data, sends a message or triggers a financial or operational commitment, you may need explicit user confirmation, idempotency controls and a way to reconcile uncertain outcomes.

An important distinction: validating an order ID confirms that the input has the expected shape. It does not establish that the user is allowed to access that order.

Make failure handling part of the design

LLM APIs and surrounding services can fail in different ways. The application should distinguish between at least these cases:
Failure Handling Guidelines

Authentication Failure:
Reject the request before retrieving any data.
No Useful Retrieval Evidence:
Explain the limitation or ask the user for clarification.
Model API Timeout:
Retry within a defined limit when appropriate, then return a clear error message.
Malformed Model Output:
Validate the output before use. Reject invalid responses or safely recover without executing them blindly.
Tool Permission Denied:
Do not execute the operation. Return an appropriate error message.
Uncertain Write Operation:
Verify the operation's outcome before attempting another write to avoid duplicate or unintended changes.
Avoid retry loops that multiply cost or repeat side effects. Use request timeouts, bounded retries and idempotency keys where the underlying operation supports them.

Streaming responses introduce another design choice. Partial text can improve perceived responsiveness, but it does not mean the complete answer has been validated. Do not stream privileged actions into execution before the relevant checks have passed.

Log enough to investigate, not everything by default

When an assistant gives an incorrect answer or attempts an unexpected tool call, developers need to understand what happened.

Useful operational fields can include:

A request or correlation ID.

Model and application versions.

Retrieval source identifiers and relevance information.

Tool names, validation outcomes and execution status.

Latency, token usage and provider error categories.

Evaluation results or user feedback, where available.

Avoid automatically storing every full prompt, document passage and response indefinitely. Conversation data may contain personal, confidential or commercially sensitive information.

Define retention periods, access controls and redaction rules. Restrict access to diagnostic logs, and document which data is sent to external model providers. Where the risk warrants it, test whether sensitive data can be excluded or masked before model submission.

Logs should help you reproduce a failure without becoming another uncontrolled repository of customer information.

Evaluate the assistant as a software feature

A successful API response does not prove that an assistant is useful, accurate or safe.

Build an evaluation set from representative tasks and known edge cases before expanding the rollout. Include examples such as:

Questions directly answered by approved documentation.

Questions with incomplete or conflicting evidence.

Requests for records outside the user's permissions.

Prompt-injection attempts embedded in retrieved content.

Invalid tool arguments and repeated tool calls.

Requests that should be escalated to a person.

Measure separate outcomes rather than relying on one overall score. Useful dimensions include answer correctness, evidence support, retrieval relevance, permission enforcement, tool-call accuracy, latency and cost.

For consequential actions, test the full workflow—not just the model's proposed tool call. A correct-looking proposal can still become an unsafe operation if the backend validates it incorrectly.

Keep a regression set and rerun it when changing the model, prompts, retrieval pipeline, tools or permission logic. Human review remains important for ambiguous cases and high-impact workflows.

Design the human handoff deliberately

A production assistant needs a clear path for questions it cannot answer or tasks it should not complete.

A handoff can be triggered when evidence is insufficient, a tool fails repeatedly, a request falls outside the assistant's scope or a user explicitly asks for a person.

A useful handoff should preserve the minimum context needed to continue the task: the user's original request, relevant authorised sources, actions already attempted and the reason for escalation.

Do not tell the user that an action has completed unless the application has confirmed it. If the outcome is uncertain, say so and provide a route to check the status.

This is especially important when integrating with existing ticketing, ordering or account-management workflows. The assistant should complement the application's existing operational controls rather than quietly bypassing them.

Introduce the capability in stages

A practical rollout can follow four stages:

Stage 1 — Read-only answers. Retrieve approved content and provide source references. Measure answer quality and failure patterns.

Stage 2 — Controlled tools. Add a small number of narrowly scoped operations with server-side permission checks and audit records.

Stage 3 — Confirmed actions. Introduce explicit confirmation for consequential changes, alongside idempotency and recovery handling where appropriate.

Stage 4 — Broader rollout. Expand access only after reviewing evaluation results, operational failures, data-handling requirements and support capacity.

These are planning stages, not a guarantee that a particular schedule or implementation will work for every application. The appropriate sequence depends on the system's risks and existing architecture.

Final checklist

Before shipping an AI assistant integration, ask:

Does every request use the application's established identity and permission model?

Is retrieved content restricted to resources the current user may access?

Are tools narrowly scoped, validated and independently authorised?

Can the assistant acknowledge missing or conflicting evidence?

Are timeouts, retries and uncertain write outcomes handled safely?

Are logs useful for diagnosis without collecting unnecessary sensitive data?

Have evaluation tests covered normal use, adversarial inputs and permission failures?

Is there a clear human handoff and a way to verify consequential actions?

Integrating an AI assistant is less about adding a clever conversation layer and more about deciding what the application will allow that layer to know and do.

Start with one useful workflow, keep the authority in trusted application code, and expand only when the evidence shows that the integration is behaving as intended.

Discussion: If you are adding an LLM to an existing product, which boundary has required the most thought so far: retrieval permissions, tool execution, evaluation or data privacy?

When React Is Worth It, and When Simpler Is Better: A Practical Guide to Choosing Your Web Architecture

Sohail — Wed, 21 Oct 2026 16:06:52 +0000

When React Is Worth It — and When Simpler Is Better: A Practical Guide to Choosing Your Web Architecture

Choosing a web development stack is not simply about picking the most popular framework. It is about understanding what your product needs to do, how users interact with it, how its data changes, and what your team can maintain over time.

React is a powerful option for building interactive user interfaces, but not every website needs a client-side application. For some projects, static HTML or server-rendered pages provide a simpler and more maintainable solution.

The goal is not to avoid React. It is to use it when its capabilities solve a real problem.

In this guide, we will compare static sites, server-rendered applications, and React-based interfaces, then explore how to choose an architecture based on practical requirements rather than trends.

Start with the user journey

Before choosing a framework, identify what users need to accomplish.

Consider three examples:

A company website: Visitors browse service pages, read articles, and submit enquiries.

A customer portal: Users sign in, view account information, download documents, and update details.

A reporting dashboard: Users filter datasets, change date ranges, compare results, and interact with charts.

All three require a web interface, but their technical requirements are different.

A company website may prioritise content delivery, accessibility, navigation, and search engine discoverability. A customer portal needs secure authentication, permissions, and reliable data handling. A reporting dashboard may require substantial client-side interaction and coordinated state across components.

Using the same architecture for all three might simplify some development workflows, but it does not automatically make it the best technical decision.

Start by asking:

How much interaction does each page require?

Does the content change frequently or depend on the current user?

Where should application state live?

What are the performance and accessibility requirements?

What infrastructure can the team operate and maintain?

These questions provide a better starting point than selecting a framework first.

Static websites: when simplicity is an advantage

A static site serves pre-generated HTML pages alongside assets such as CSS, JavaScript, images, and fonts. Developers can create pages directly or generate them from templates and content files.

This approach is often suitable for content-led websites where the majority of information is public and does not need to be generated separately for every request.

When should you choose a static architecture?

Consider static delivery when:

Most content changes relatively infrequently.

Pages follow predictable layouts.

Visitors mainly read content and navigate between pages.

Interactions are limited to features such as menus, forms, or simple widgets.

The team wants to minimise runtime infrastructure.

For example, a service page containing an introduction, a list of capabilities, and a contact link does not necessarily need a full client-side application.

A basic HTML page might look like this:
`<!doctype html>

Website Development Services
<meta
name="description"
content="Explore website development options for your business."

Website Development Services

Choose a website architecture that fits your content,
users and operational requirements.

Discuss your requirements

`

This is a minimal illustration rather than a complete production website. A real implementation would also require appropriate styling, accessible navigation, content maintenance, error handling, and any necessary privacy or analytics controls.

Static delivery does not mean a website must look basic. CSS and JavaScript can provide interactive features without turning every page into a React application.

There are trade-offs, however. Content updates need a suitable publishing process, and personalised or request-specific information requires additional services or runtime logic.

The principle: Choose static delivery when the content and interaction model are simple enough that a runtime application would add more complexity than value.

Server-rendered applications: when the request matters

In a server-rendered architecture, the server generates HTML for a request and sends it to the browser. Depending on the framework, it may retrieve data, apply templates, enforce access rules, and construct the response before delivery.

This can be useful when a page depends on current data or server-side business logic.

When does server rendering make sense?

Consider server rendering when:

Pages need request-time data.

Content depends on account or user context.

Authentication and authorisation are central to the application.

You want meaningful HTML to arrive before client-side JavaScript runs.

Forms, links, and server-handled requests can support the user journey.

For example, an Express-style route might render a product listing using a template:
`app.get("/products", async (req, res, next) => {
try {
const products = await getPublishedProducts();

res.render("products", {
  title: "Products",
  products
});

} catch (error) {
next(error);
}
});`

This example assumes that Express, the template engine, and getPublishedProducts() have been configured elsewhere. It illustrates a pattern, not a complete production application.

The server retrieves the data and supplies it to the template. The browser receives rendered HTML rather than needing to construct the entire initial interface from an empty page.

What are the trade-offs?

Server rendering introduces operational responsibilities. The application must handle incoming requests, manage data access, return appropriate errors, and scale according to its workload.

It is not automatically faster. Slow database queries, inefficient external API calls, excessive server work, or poor caching can all affect response times.

Caching also requires care. Personalised responses must not accidentally be shared between users, and cached data needs an appropriate freshness policy.

Importantly, server rendering and React are not mutually exclusive. React can render HTML on the server, while modern frameworks can combine server rendering, static generation, and client-side interactivity.

The principle: Choose server rendering when request-time data and server-side processing justify the additional runtime responsibilities.

React applications: when interaction becomes complex

React is a JavaScript library for building user interfaces from components. Its value becomes more apparent when an interface contains reusable UI patterns and state that changes in response to user actions or incoming data.

Instead of treating the interface as one large block, developers can divide it into smaller components with defined responsibilities.

When is React worth using?

React may be a good fit when:

Users interact with multiple parts of the interface without navigating to a new page for every action.

Several components depend on shared application state.

The product contains complex forms, filters, tables, charts, or multi-step workflows.

Reusable interactive components are important.

The team can maintain the associated development, testing, and deployment processes.

Imagine a reporting dashboard where users change a date range, select a business unit, filter a table, and open a detail panel. Several components may need to respond to the same selections.

A component-based approach can help organise this behaviour.

Here is a small React example:
`import { useState } from "react";

export function QuantitySelector() {
const [quantity, setQuantity] = useState(1);

function decreaseQuantity() {
setQuantity(current => Math.max(1, current - 1));
}

function increaseQuantity() {
setQuantity(current => current + 1);
}

return (

type="button"
onClick={decreaseQuantity}
disabled={quantity <= 1}
aria-label="Decrease quantity"
>
−

  <output aria-live="polite">{quantity}</output>

  <button
    type="button"
    onClick={increaseQuantity}
    aria-label="Increase quantity"
  >
    +
  </button>
</section>

);
}`

The component manages its own quantity state and updates the displayed value when users interact with the buttons.

This is a deliberately small example, not a complete shopping-cart implementation. A real checkout flow would also need server-side validation, stock and price checks, error handling, and reliable transaction processing.

What does React add to the project?

React also introduces concepts and tools that developers need to understand. Depending on the application, these may include routing, data fetching, state management, build tooling, testing, and rendering strategy.

These costs are justified when they help manage genuine interface complexity. They are less compelling when a website mainly displays content and provides a few simple interactions.

React does not automatically make an application fast, accessible, secure, or search-engine friendly. Those outcomes depend on the implementation and surrounding architecture.

The principle: Choose React when structured components and stateful interaction provide enough value to justify the additional development and maintenance work.

## Comparing the Three Web Architecture Approaches

Mostly informational content
- Static delivery: Often a strong fit.
- Server-rendered application: Suitable.
- React-based interface: Possible, but may be unnecessary.
Frequently changing server data
- Static delivery: Requires an integration or regeneration strategy.
- Server-rendered application: Often a strong fit.
- React-based interface: Suitable with an appropriate data architecture.
Rich, coordinated UI state
- Static delivery: Possible with JavaScript.
- Server-rendered application: Possible with client-side enhancements.
- React-based interface: Often a strong fit.
Personalised account pages
- Static delivery: Requires additional services or runtime logic.
- Server-rendered application: Often a strong fit.
- React-based interface: Suitable alongside secure backend services.
Minimal runtime complexity
- Static delivery: Often favourable.
- Server-rendered application: Depends on the server setup.
- React-based interface: Depends on the application and rendering model.
Interactive dashboards
- Static delivery: Possible, but complexity can grow.
- Server-rendered application: Possible with client-side enhancements.
- React-based interface: Often a strong fit.
Search engine discoverability
- Static delivery: Can work well with accessible HTML and sound technical SEO.
- Server-rendered application: Can work well with server-generated HTML.
- React-based interface: Depends on rendering, metadata, content access, and implementation.

Do not interpret the React column as meaning that every React page must render entirely in the browser. React supports different rendering strategies, and modern frameworks can generate HTML ahead of time or on the server before adding client-side behaviour.

Likewise, static websites can include interactive JavaScript, while server-rendered applications can progressively enhance their pages without becoming single-page applications.

The categories describe architectural tendencies rather than rigid boundaries.

A practical framework for choosing your stack

Once you understand the options, use a structured decision process.

Step 1: Map the main user journeys

List the actions users need to complete.

For a company website, users might read service information, compare options, and send an enquiry. For an internal dashboard, they might filter records, update a status, and review changes.

If most journeys involve reading content and navigating between pages, a simpler architecture may be sufficient. If they involve many dependent controls and changing interface states, a component-driven approach deserves closer consideration.

Step 2: Identify where the data comes from

Ask whether a page can be generated ahead of time or requires current information at request time.

Public editorial content may suit static generation. Account information, permissions, or user-specific records need an appropriate server-side data and security model.

Adding React does not remove the need for a secure backend. Sensitive business rules and authorisation checks must not rely solely on client-side code.

Step 3: Decide where state belongs

Not all state needs a global store or complex client-side architecture.

A selected tab may only need local component state. Search filters may belong in the URL if users should be able to bookmark or share them. Persistent business records generally belong in a backend system.

Choosing the right location for each kind of state can prevent unnecessary complexity, regardless of framework.

Step 4: Assess the operational model

Consider who will deploy the application, monitor errors, update dependencies, manage content, and respond to incidents.

A technology choice that suits a team with established JavaScript tooling may be less suitable for a small team that wants to maintain a straightforward content-led website.

Include long-term maintenance in the decision, not just the initial build.

Step 5: Introduce complexity only when there is a reason

Before adopting a heavier architecture, identify the specific problem it solves.

That reason might be a complex interaction model, repeated UI patterns, request-time data requirements, or several distinct user journeys.

If the justification is simply that a framework is popular or familiar, revisit the requirements.

Common architectural mistakes

Using React for every page by default

A single framework across a website can simplify some team workflows, but it is not automatically the simplest overall solution. A small content page may gain little from an application-level setup.

Evaluate the full cost, including development, build tooling, runtime behaviour, testing, deployment, and future maintenance.

Assuming static sites cannot be interactive

Static HTML can work alongside JavaScript, APIs, forms, and embedded interactive components. The important question is whether those additions remain easy to understand and maintain.

Treating server rendering as a performance guarantee

Generating HTML on the server can help deliver useful content early, but it does not eliminate slow data access, inefficient rendering, or poor caching. Evaluate the complete request path.

Building a hybrid architecture without clear boundaries

Combining static generation, server rendering, and client-side React can be effective. It can also create confusing data flows and multiple rendering paths if the team has no clear rules.

Define which pages are generated ahead of time, which need request-time data, and which interactions require client-side behaviour.

Ignoring accessibility and real-user performance

Framework selection does not replace semantic HTML, keyboard testing, sensible loading states, or performance measurement.

Review the experience on slower devices and networks. Test actual user journeys instead of assuming that a successful build means the interface is ready.

Conclusion: Choose the simplest architecture that fits

There is no single web architecture that is right for every product.

Static delivery can be an excellent choice for content-led websites. Server rendering can suit applications that need request-time data and server-side processing. React can provide structure and maintainability for interfaces with substantial interaction and shared state.

The strongest decision comes from matching the architecture to the user journey, data requirements, operational constraints, and the team's ability to maintain it.

Start with the simplest viable approach. Introduce more machinery when a clear requirement justifies it, and review the decision as the product evolves.

That is a more reliable basis for choosing a web development stack than adopting a framework simply because it is widely used.