DEV Community: Racharla Gunasekhar

From API Responses to a Useful Dashboard: Connecting JavaScript with FastAPI

Racharla Gunasekhar — Thu, 29 Oct 2026 17:23:24 +0000

Introduction

A backend API can process data correctly, but users still need a simple way to submit information, understand the results, and take action.

While building my personal Lead Qualification & Scoring Engine, I worked on connecting a browser-based dashboard to a FastAPI backend. The application allows users to enter lead information, submit it for qualification, review scoring results, and revisit previously processed leads.

In this article, I’ll explain the architecture, frontend-to-backend communication, API response handling, and how structured qualification results can be presented in a useful dashboard.

Understanding the Application Architecture

The application combines frontend technologies with a Python backend.

HTML: Structures the lead form, dashboard, and result sections.
CSS: Styles the interface, score indicators, and result cards.
JavaScript: Handles form submissions, API requests, and dynamic updates.
FastAPI: Processes requests and exposes backend endpoints.
Pydantic: Validates incoming data.
SQLAlchemy: Stores and retrieves lead records.

The application follows this general flow:

The frontend focuses on collecting information and presenting results. The backend handles validation, qualification logic, and persistence.

Keeping these responsibilities separate makes the application easier to maintain and extend.

Collecting Lead Information

The workflow begins with a form that collects information about a potential customer.

Depending on the fields provided, the application can capture details such as:

Name and company
Job title and industry
Company size and country
Pain points and buying signals
Recent activity and other qualification-related information

When a user submits the form, JavaScript reads the values and prepares a structured request payload.

For example:

const payload = {
name: nameInput.value.trim(),
company: companyInput.value.trim(),
industry: industryInput.value,
pain_point: painPointInput.value,
buying_signal: buyingSignalInput.value
};

This is a simplified example showing how form values can be converted into an object. The actual payload should match the fields expected by the backend.

Preparing a consistent payload helps avoid mismatches between the frontend and API.

Sending Requests to FastAPI

The frontend communicates with the backend through HTTP requests.

JavaScript’s fetch() API provides a straightforward way to submit JSON data:

async function submitLead(payload) {
const response = await fetch("/qualify-lead", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
if (!response.ok) {
throw new Error("Unable to qualify the lead.");
}
return await response.json();
}

The request includes three important elements:

The POST method submits the lead information for processing.
The Content-Type header identifies the request body as JSON.
JSON.stringify() converts the JavaScript object into a JSON string.

The backend receives the request, validates the data, and executes the qualification workflow.

Checking response.ok is important because an HTTP request can complete while the server returns an error status. The frontend should handle that case instead of treating every response as successful.

Note: This code illustrates the request pattern. The endpoint path and payload must match the actual application implementation.

Handling Loading and Error States

A good dashboard should communicate what is happening when a request takes time.

For example, an AI-assisted qualification workflow may take longer than a simple database lookup.

Without feedback, users may submit the form repeatedly because they are unsure whether the first request worked.

A loading state can improve the experience:

function setLoading(isLoading) {
submitButton.disabled = isLoading;
submitButton.textContent = isLoading
? "Analyzing Lead..."
: "Analyze Lead";
}

The submission handler can enable the loading state before the request and restore the button afterward.

It should also catch errors and show a clear message when qualification fails.

Client-side validation is useful for immediate feedback, but the backend must validate the incoming data independently. Browser-side checks alone are not sufficient to protect an API.

Turning API Responses into Useful Insights

Returning JSON is only one part of building a useful application. Users need to understand the information without reading raw API responses.

The qualification dashboard presents information such as:

Overall lead score and classification
Ideal Customer Profile (ICP) fit
Scoring breakdown
Qualification explanation
Recommended offer and next action
Sales action plan

Instead of displaying a large JSON object, the frontend can organize the response into cards, labels, progress bars, and action sections.

For example, a simplified response might look like this:

{
"score": 85,
"classification": "HOT",
"icp_fit": true,
"cached": false
}

This is an illustrative example, not a guaranteed response for a particular lead. The actual response structure depends on the backend schema.

The frontend should display the score and classification returned by the backend rather than independently calculating them. This keeps the scoring rules in one place and avoids inconsistent results between the UI and server.

Displaying a Scoring Breakdown

A total score explains how strong a lead appears, but it does not necessarily explain why.

A scoring breakdown gives users more context by showing how individual criteria contribute to the result.

For example, a dashboard may use progress bars to display the points awarded for industry relevance, decision-maker status, company size, pain points, buying signals, automation opportunities, and recent activity.

Each bar can show both the awarded points and the maximum points available for that criterion.

This improves transparency because users can see which factors contributed to the final score.

The frontend is responsible for visual presentation, while the backend remains responsible for applying the configured scoring rules and returning the results.

Displaying Cached Results

The application also supports reusing existing qualification results when the relevant lead information has not changed.

The backend can indicate whether a result was reused through a field such as cached.

The frontend can use that information to display an appropriate status message:

function updateCachedBanner(isCached) {
cachedBanner.hidden = !isCached;
}

When the result is cached, the interface can tell the user that an existing qualification was reused. When a fresh qualification runs, the dashboard can present the new result.

This small detail connects the backend’s caching behavior to the user experience.

It also illustrates a broader principle: backend behavior becomes easier to understand when the API communicates useful status information to the frontend.

Managing Previously Qualified Leads

A dashboard becomes more useful when users can revisit previous work.

The application stores lead records so users can review previously processed leads instead of entering the same information every time.

A recent-leads section can display summaries and allow users to open individual records for more details.

For example, the list might show the lead’s company, score, classification, and last update.

The backend is responsible for retrieving the saved records, while the frontend presents them in a readable format.

Separating these responsibilities means the same backend functionality can potentially support other interfaces in the future.

Design Decisions and Lessons Learned

Building the frontend-to-backend workflow highlighted several important engineering practices.

Keep request and response structures consistent. The frontend and backend need to agree on field names, data types, and response formats.

Handle errors explicitly. A useful interface should explain when a request fails instead of leaving the user uncertain.

Keep business logic in the backend. The UI should display the qualification results rather than independently implementing the scoring rules.

Make processing status visible. Loading indicators and cached-result messages help users understand what the application is doing.

Separate presentation from persistence. The frontend handles interaction and display, while the backend manages data validation, qualification, and database operations.

These practices are useful beyond lead scoring. They apply to dashboards, internal business tools, reporting applications, and other systems that connect a web interface to an API.

Conclusion

My personal Lead Qualification & Scoring Engine gave me an opportunity to work across the frontend and backend of a practical application.

The frontend collects lead information and presents qualification results. FastAPI processes requests, the qualification services evaluate the submitted data, and SQLAlchemy supports persistent lead management.

The main lesson is that a useful dashboard is not just a collection of UI components. It depends on reliable communication, consistent data structures, clear error handling, and a well-defined separation of responsibilities.

I am continuing to improve the project and explore how backend APIs can power useful internal tools and workflows.

This article describes the frontend and backend concepts used in my personal Lead Qualification & Scoring Engine.

Avoiding Duplicate AI Work: SQLAlchemy Persistence and Fingerprint-Based Caching in FastAPI

Racharla Gunasekhar — Thu, 29 Oct 2026 17:15:07 +0000

When building an AI-powered application, sending every request to an AI provider can create unnecessary work. Users may submit the same information more than once, refresh a page, or update a record without changing the data that affects the result.

During the development of my personal Lead Qualification & Scoring Engine, I worked on this problem by combining SQLAlchemy persistence with a fingerprint-based caching strategy.

The goal was simple:

Avoid creating duplicate records for the same lead.
Reuse an existing qualification when the relevant input has not changed.
Re-run qualification when meaningful lead information changes.
Keep the same Lead ID when updating an existing lead.

In this article, I’ll explain the design and the implementation behind it.

The Problem: Repeated Requests

Imagine a sales representative submits the following lead:

Name: John Smith
Company: Example SaaS
Industry: Software
Pain point: Manual lead qualification

The application qualifies the lead and saves the result.

If the representative submits the same lead again, creating another database record and repeating the AI analysis is unnecessary.

However, there is an important distinction: if the lead’s buying signal or pain point changes, the application may need to run the qualification process again.

I needed a way to distinguish between these two situations.

The Approach: Identity and Fingerprint

I used two separate hashes because they answer two different questions.

Identity key: Is this the same lead?

The identity key is calculated from the lead’s name and company.

It helps the application find an existing record for the same person at the same company.

Fingerprint: Has the qualification input changed?

The fingerprint is calculated from fields that meaningfully affect qualification, such as the industry, company size, pain point, buying signal, and recent activity.

The application compares this fingerprint with the one stored in the database.

This distinction is important: lead identity determines which record to look up, while the fingerprint determines whether the stored qualification can be reused.

Creating a Stable Fingerprint with Python

I implemented the fingerprint logic using Python’s hashlib and json modules.

Here is a simplified version of the approach:

import hashlib
import json
def normalize(value):
if isinstance(value, str):
value = value.strip().lower()
return value or None
return value
def create_fingerprint(lead_data, fields):
payload = {
field: normalize(lead_data.get(field))
for field in fields
}
stable_json = json.dumps(
payload,
sort_keys=True,
ensure_ascii=False
)
return hashlib.sha256(
stable_json.encode("utf-8")
).hexdigest()

This example illustrates the core technique. In my project, the implementation reads the selected fields from the lead object.

There are three important details here:

Normalization: Trimming whitespace and normalizing string casing means values such as " Software " and "software" produce the same normalized input.

Stable serialization: Using sort_keys=True ensures that dictionary key order does not affect the serialized representation.

SHA-256 hashing: The normalized JSON is converted into a SHA-256 hash. Identical normalized input produces the same fingerprint.

A hash is useful here as a compact comparison value. It does not replace the original lead data, which is stored separately in the database.

Choosing the Fields Carefully

Not every field should necessarily invalidate a cached qualification.

For example, my implementation includes fields such as:

Name and company
Job title and country
Industry and company size
Website and LinkedIn URL
Pain point and buying signal
Recent activity

The implementation deliberately excludes custom_offer, which is treated as a display override rather than a qualification input.

This choice depends on the application’s business rules. If a field starts influencing the qualification result, it should be included in the fingerprint.

Otherwise, the application could incorrectly reuse a result calculated from older information.

Persisting Lead Data with SQLAlchemy

I used SQLAlchemy to store lead information and qualification results in a database.

The lead model includes fields for:

The identity key and fingerprint
Original lead information
Qualification score and classification
Scoring breakdown and AI assessment
Recommended offer and next action
Sales action plan
Creation and update timestamps

The model stores structured information in database columns. Some result fields, such as scoring breakdowns and sales action plans, use JSON-compatible columns.

I also created repository functions to keep database operations separate from the API route logic.

For example, the update operation modifies an existing SQLAlchemy model instance:

def update_lead_record(db, record, data):
for key, value in data.items():
setattr(record, key, value)
db.commit()
db.refresh(record)
return record

The important behavior is that this updates the existing record rather than inserting a new one. The existing database ID is therefore preserved.

In the actual project, the repository functions also handle creating records, retrieving a lead by ID, looking up a lead by identity, and listing recent leads.

Applying the Cache in the FastAPI Endpoint

The main qualification endpoint follows a straightforward decision process.

Calculate the lead’s identity key.
Calculate the fingerprint of the qualification-relevant fields.
Find an existing record using the identity key.
Compare the stored fingerprint with the newly calculated fingerprint.
Reuse the stored qualification or run the qualification process, depending on the comparison.

The core decision looks like this:

existing = get_lead_by_identity(
db,
identity_key
)
if existing is not None:
if existing.fingerprint == fingerprint:
# Reuse the stored qualification.
return {
"cached": True,
"lead": _lead_dict(existing),
"qualification": _qualification_dict(existing),
}
# The lead exists, but relevant input changed.
result = analyze_lead(lead)
# Update the existing record with the new result.
else:
# New lead: qualify and create a record.
result = analyze_lead(lead)

This is a simplified illustration of the decision flow; the complete endpoint also builds the response and persists the new qualification results.

The actual implementation returns a cached flag and a qualification_source value. This makes it easier to distinguish between a result reused from the database and one generated through a new qualification run.

What Happens in Each Scenario?

Scenario Application behavior
New person and company Run qualification and create a record
Same identity and same fingerprint Reuse the stored qualification
Same identity but changed fingerprint Re-run qualification and update the existing record
Display-only offer override changes Do not invalidate the fingerprint solely for that change

This approach keeps the behavior predictable while avoiding unnecessary repeat work.

Engineering Considerations

Implementing a fingerprint-based cache requires more than generating a hash.

Keep the fingerprint definition aligned with business logic

If qualification starts depending on a new field, update the fingerprint field list as well. Otherwise, stale results may be reused.

Handle normalization deliberately

Normalization should reflect the meaning of the data. Lowercasing text is reasonable for many names and descriptive fields, but it should not be applied indiscriminately to every type of value.

Consider changes to the scoring rules

The fingerprint in this implementation represents the lead input. If scoring rules or model behavior change, the same input may produce a different result.

For a production system, consider including a scoring-rule version or qualification version in the cache key, or invalidating cached results when those dependencies change.

Think about concurrent requests

Two requests for the same new lead can arrive at nearly the same time. A production implementation should consider database uniqueness constraints, transaction handling, and concurrency so that simultaneous requests do not create duplicate records.

Measure the benefit

Caching can reduce repeated AI calls, but its actual impact depends on how frequently duplicate requests occur. Logging cache hits, cache misses, and qualification duration can help evaluate whether the approach is effective.

What I Learned

This implementation helped me understand that caching is not simply storing a response and returning it later.

The difficult part is deciding when a stored result is still valid.

Separating lead identity from qualification fingerprints made the behavior easier to reason about. SQLAlchemy persistence gave the application a consistent place to store both the input data and its qualification results, while FastAPI provided the endpoint through which the workflow runs.

The same ideas can be useful in other applications that process repeated inputs, including document analysis, product recommendations, reporting tools, and AI-assisted workflows.

Conclusion

Building the Lead Qualification & Scoring Engine gave me an opportunity to apply hashing, database persistence, and caching to a practical backend problem.

The main lesson is that a useful cache needs a clear definition of identity and a reliable way to determine whether the underlying input has changed.

By combining a stable fingerprint with SQLAlchemy persistence, the application can reuse unchanged qualification results and update existing lead records when relevant information changes.

I’m continuing to improve the project and explore ways to make AI-powered applications more reliable, explainable, and efficient.

This article describes the implementation in my personal Lead Qualification & Scoring Engine

Building an Explainable AI-Powered Lead Scoring Engine with FastAPI

Racharla Gunasekhar — Thu, 29 Oct 2026 17:05:52 +0000

Building an Explainable AI-Powered Lead Scoring Engine with FastAPI

Introduction

Sales teams often receive many leads, but not every prospect is equally likely to become a customer. Manually reviewing every lead takes time and makes it difficult to identify the most promising opportunities.

I built a personal project called the Lead Qualification and Scoring Engine to explore how AI and rule-based business logic can work together to solve this problem.

The application evaluates lead information, checks Ideal Customer Profile (ICP) fit, calculates a score from 0 to 100, and generates a lead classification and recommended next action.

In this article, I’ll explain the architecture, scoring approach, API design, and engineering lessons behind the project.

Technology stack

The project uses:

Python for business logic.
FastAPI for REST API endpoints.
Pydantic for request and response validation.
SQLAlchemy for database operations.
SQLite for data persistence.
AI integration for interpreting lead information.
HTML, CSS, and JavaScript for the frontend.
Pytest for automated testing.

Understanding the architecture

The application follows a sequence of steps:

Receive lead information.
Check for an existing lead and reusable results.
Gather available company research.
Use AI to interpret relevant business signals.
Evaluate ICP fit using configured rules.
Calculate a deterministic score in Python.
Generate the classification and recommendations.
Store the results and return a structured response.

One important design decision is separating AI interpretation from numerical scoring.

AI can help interpret unstructured information, while deterministic application code applies the configured business rules. This makes the final score easier to explain and test.

Implementing configurable lead scoring

A scoring engine should not be a mysterious black box. Sales teams need to understand why a lead received a particular score.

My project stores scoring configuration in a JSON rules file. The configured criteria cover industry relevance, decision-maker relevance, company size, pain points, buying signals, automation opportunities, and recent activity.

Each criterion contributes its configured weight when the relevant condition is satisfied.

For example, consider a hypothetical lead:

Criterion Points
Target industry 20
Decision-maker relevance 15
Company size 10
Clear pain point 20
Buying signal 0
Automation opportunity 10
Recent activity 5
Total 80

This example demonstrates how a score can be explained through individual criteria rather than returned as a single unexplained number.

The actual scoring rules and thresholds should remain consistent with the application’s configuration.

Why use rules alongside AI?

AI is useful for interpreting descriptions that do not follow a fixed format. For example, a prospect might describe manual workflows or operational challenges without explicitly labelling them as an automation opportunity.

However, asking an AI model to invent a final score can make results difficult to reproduce.

A hybrid approach separates responsibilities:

AI interprets available information.
Business rules evaluate qualification requirements.
Python calculates the score.
The API returns the result in a structured format.

This separation makes it easier to test the scoring logic independently of the AI provider.

Building REST APIs with FastAPI

FastAPI provides endpoints that allow the frontend and other applications to interact with the qualification engine.

The project includes operations for qualifying leads, retrieving stored leads, viewing an individual lead, and checking service health.

Pydantic schemas help validate incoming request data before it reaches the business logic.

A structured API response can expose the score, classification, qualification status, scoring breakdown, matched criteria, and recommended next action.

This structure also makes the engine suitable for integration with a CRM or an internal business dashboard.

Storing results with SQLAlchemy and SQLite

The application uses SQLAlchemy models and SQLite to persist lead information and qualification results.

Persistence allows the system to retrieve previous results without depending on temporary in-memory data.

Keeping database operations in a separate repository layer also helps separate data access from scoring and analysis.

SQLite is convenient for local development because it requires minimal setup. SQLAlchemy provides a familiar abstraction for working with relational data.

Reducing repeated work with fingerprint-based caching

Repeatedly analyzing unchanged lead information can increase processing time and AI API usage.

The project uses a lead identity and a fingerprint of qualification-relevant information to determine whether an existing result can be reused.

When the same lead is submitted with unchanged relevant information, the application can reuse its stored result. When relevant information changes, the qualification process can run again.

This approach helps avoid unnecessary work while preserving the ability to refresh results when the underlying information changes.

Testing the application

Automated tests are important because a correct HTTP response does not necessarily mean the qualification result is correct.

The project includes tests for areas such as scoring, API behaviour, ICP validation, AI services, research, sales action plans, and fingerprint-based caching.

Useful test cases include:

Verifying the expected score for known assessment inputs.
Checking that an ICP mismatch is handled correctly.
Confirming that invalid requests are rejected.
Ensuring unchanged lead data can reuse an existing result.
Checking how the application handles failures in external services.

Deterministic business logic is particularly valuable because it can be tested without depending on an AI model producing exactly the same interpretation every time.

Engineering lessons

Building this project reinforced several useful principles.

Make business rules explicit. Configurable scoring criteria make changes easier to understand and maintain.

Separate AI from deterministic decisions. AI interpretation and numerical calculations have different responsibilities.

Design for failure. External services can become unavailable or return unusable output, so fallback behaviour needs to be tested.

Avoid unnecessary processing. Reusing stored results can reduce repeated analysis for unchanged information.

Test the business logic. Tests should validate qualification outcomes, not just successful API responses.

Conclusion

The Lead Qualification and Scoring Engine combines AI-assisted interpretation, configurable business rules, REST APIs, database persistence, and automated testing.

The goal is not simply to assign a number to a prospect. It is to produce an understandable qualification result that other applications can consume.

This project gave me practical experience with API development, AI integration, data persistence, caching, and testable business logic.

Future improvements could include stronger monitoring, more extensive evaluation of AI-generated assessments, and integration with an internal dashboard for reviewing and managing qualified leads.

Technologies: Python, FastAPI, Pydantic, SQLAlchemy, SQLite, AI integration, JavaScript, HTML, CSS, and Pytest.