Recently, I built a small proof-of-concept to explore agentic workflows using LangGraph.

The goal was simple: take partially complete product information, combine it with user-provided context, and use an LLM-powered workflow to generate enriched, structured product data.

Rather than building a monolithic prompt, I wanted to experiment with a multi-agent architecture and understand how orchestration frameworks like LangGraph fit into real applications.

The Problem

Many product datasets contain incomplete information:

• Missing descriptions
• Sparse specifications
• Inconsistent metadata
• Additional context scattered across documents

This POC accepts a product, optional supporting context, and uploaded documents, then generates an enriched product profile using an AI workflow.

Architecture

The application consists of three main layers:

Streamlit Frontend
        │
        ▼
FastAPI Backend
        │
        ▼
LangGraph Workflow
        │
        ├── Retrieval Agent
        └── Enrichment Agent
        │
        ▼
Structured Product Output

Frontend

The Streamlit UI provides:

• Product selection
• Context input
• Document upload support
• Enrichment results display

Backend

The FastAPI service exposes a single /enrich endpoint and keeps route handlers intentionally thin. Business logic lives inside service and workflow layers.

Agent Workflow

The enrichment process is orchestrated using LangGraph:

1. Retrieve relevant context
2. Aggregate user inputs
3. Generate enriched product information
4. Return structured output using Pydantic schemas

This separation made it easier to reason about responsibilities and experiment with agent behavior.

Technology Choices

The project uses:

• Python 3.11
• FastAPI
• Streamlit
• LangGraph
• LangChain
• Pydantic v2
• OpenRouter
• DeepSeek V4 Flash

For observability, I also integrated OpenTelemetry tracing with Jaeger, which made it much easier to understand workflow execution and LLM interactions.

What I Learned

A few takeaways from building this project:

• LangGraph provides a clean way to model multi-step AI workflows.
• Keeping API handlers thin improves maintainability.
• Structured outputs with Pydantic significantly reduce parsing headaches.
• Tracing becomes extremely valuable once workflows involve multiple agents and LLM calls.
• For small POCs, simple architectures often beat over-engineered solutions.

Current Limitations

This project intentionally remains lightweight and does not include:

• Authentication
• Persistent storage
• Human-in-the-loop workflows
• Vector databases
• Batch processing
• Multi-user support

The objective was to learn agent orchestration patterns rather than build a production-ready platform.

What’s Next

Some areas I’d like to explore next:

• Evaluation frameworks for enrichment quality
• Human-in-the-loop approval workflows
• Persistence and workflow state management
• Retrieval-augmented enrichment using vector databases

Building this project was a useful exercise in combining modern Python APIs, agent orchestration, structured outputs, and observability into a single workflow.

The complete source code is available on GitHub.

That’s backwards.

Your schema isn’t just storage—it’s the contract that defines performance, cost, and evolvability. A thoughtful design compounds value for years; a rushed one becomes technical debt no amount of application optimization can fully undo.

Here’s what that looks like in practice: designing the schema for a product similarity microservice serving real-time “customers also viewed” recommendations.

The Hidden Tradeoffs in Every Schema Decision

When designing a schema, you’re making explicit tradeoffs:

These aren’t academic. They manifest as 3 a.m. pages when your recommendation API spikes to 800ms during Black Friday.

Relational vs. Document: It’s Not Binary

Modern workloads often demand hybrid approaches:

• Pure relational excels for dynamic relationship traversal but joins kill latency in high-throughput reads.
• Pure document shines for self-contained aggregates but struggles with cross-document queries and referential integrity.

The sweet spot? Use relational structure for identity and relationships; embed denormalized data where access patterns are predictable. You get SQL’s query power where you need flexibility and document-style reads where latency is non-negotiable.

Case Study: Product Similarity Schema

For our service—sub-100ms recommendations, <100k products, weekly batch updates—we chose a hybrid PostgreSQL schema that deliberately denormalizes:

CREATE TABLE product_similarities (
    product_id VARCHAR(50) NOT NULL,
    recommendations JSONB NOT NULL,  -- Denormalized similarity list
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT TRUE,
    batch_id VARCHAR(50) NOT NULL,
    PRIMARY KEY (product_id, created_at)
);

Why this works:

• Single-row reads: Entire similarity list in one JSONB field. One index lookup (product_id + is_active)—no joins, no aggregation.

• Versioned updates: Weekly batches insert new versions instead of overwriting. Old versions stay active until new batch loads—zero downtime, instant rollbacks.

• Operational simplicity: PostgreSQL gives strong consistency and familiar tooling. No need for DynamoDB or Cassandra when writes are weekly and reads are point lookups.

• Controlled flexibility: JSONB lets us index nested fields later (e.g., by score) without schema migrations today.

We accepted tradeoffs: higher storage from versioning and periodic cleanup needs. But these are manageable compared to unpredictable join latency or fragile batch updates.

The Takeaway

Schema design forces you to confront reality: How will this actually be used? It’s where data models meet production constraints—latency budgets, cost ceilings, inevitable change.

Don’t treat your schema as plumbing. Treat it as architecture. The hour spent modeling access patterns today saves weeks of firefighting tomorrow. When your API serves millions of requests per second, the database won’t lie about the decisions you made—or deferred—when no one was watching.

We learned this the hard way.

We had a GenAI-powered bot that returned structured JSON responses to a microservice. Even with temperature=0, about 10% of responses were malformed, triggering 4xx errors in our Grafana dashboards. We’d implemented retries, but they were costly—in latency, tokens, and unpredictability.

We couldn’t switch to a more capable (or expensive) model due to constraints. We tried prompt engineering, schema validation with Pydantic, and deterministic settings—but the LLM kept tripping over JSON formatting. The content was often correct, but a missing quote, an unescaped newline, or a trailing comma would break parsing.

So instead of fighting the model’s inherent non-determinism, we built a safety net.

We added a lightweight post-processing layer:

• When Pydantic raised an InvalidJSONError,
• We applied a targeted regex-based cleanup to extract and restructure the JSON,
• Then re-validated the result.

The outcome? 4xx errors dropped from 10% to just 2%.

The Takeaway

Reliability in GenAI systems isn’t about eliminating randomness—it’s about containing it.

You can’t always control what the LLM outputs, but you can design resilient wrappers around its known failure modes. Sometimes, the most “unsexy” code—regex, fallback parsers, strict validation—is what makes your AI system production-ready.

If you’re shipping GenAI, ask yourself:
Where is your system brittle? And what’s your Plan B when the LLM inevitably glitches?

“I didn’t want to just use AI — I wanted to understand it.”

That’s why I built my own RAG (Retrieval-Augmented Generation) microservice from scratch using FastAPI and entirely open-source tools — no Bedrock, no OpenAI API, no managed services. Just raw, hands-on learning.

This project was born out of curiosity and a desire to peel back the layers of modern LLM-powered applications. I wanted to know: What’s really happening under the hood? And more importantly — how can I keep my data private while still leveraging powerful models?

🧰 The Tech Stack

Here’s what I wired together:

• MinIO → Self-hosted S3-compatible storage for document uploads
• Chroma → Lightweight, open-source vector database for storing embeddings
• vLLM → High-throughput LLM inference engine (for future chat integration)
• Hugging Face Text Embeddings Inference → Fast, scalable embedding generation
• FastAPI → The glue holding it all together with clean, async endpoints

All containerized via Docker and orchestrated with docker-compose.yml — because if it’s not reproducible, did it even happen?

🚀 Endpoints I Built

POST   /upload      → Upload file → stores in MinIO
DELETE /delete/{filename} → Delete file from MinIO
POST   /embed       → Generate embeddings for ALL files in MinIO
POST   /embed/{filename} → Embed a specific file
POST   /retrieve    → Retrieve top-k relevant chunks for a query

Simple? Yes.
Powerful? Absolutely.

Each endpoint is designed to be modular, testable, and — most importantly — understandable. No black boxes.

🧠 What I Learned (The Hard Way)

Building RAG from scratch revealed surprising complexities:

1. File-Embedding Synchronization

What happens when you rename or delete a file? Do you delete its embeddings? How do you track which embeddings belong to which file version? I learned the hard way that random hashes don’t cut it — you need deterministic hashing (e.g., based on filename + content hash) to maintain consistency.

2. The Need for an Embedding Registry

I didn’t realize how crucial it is to maintain a metadata registry mapping files → embedding IDs → chunk IDs. Without it, you’re flying blind when files change or models get updated.

3. Pipeline Rebuilds Are Inevitable

Switching embedding models? Updating chunking strategies? You need a full re-embedding pipeline — with evaluation metrics to measure drift or performance loss. RAG isn’t “set and forget.” It’s a living system.

🔐 Why Privacy Matters (And Why I Built This)

Let’s be honest: most LLM services keep your data. Whether it’s for training, telemetry, or “improving the product,” your documents, queries, and context are rarely truly private.

I built this so I — and you — can:

✅ Use local files
✅ Avoid sending data to third parties
✅ Swap models freely (Llama, Mistral, Phi, etc.)
✅ Own the entire stack — from ingestion to response

This isn’t just a toy project. It’s a blueprint for private, auditable, enterprise-ready RAG.

🗺️ What’s Next?

I’m now integrating vLLM for chat endpoints — letting users query their documents and get LLM-generated responses — all locally.

Future plans:

• Experiment with different RAG architectures (HyDE, sub-queries, re-ranking)
• Add evaluation metrics (hit rate, MRR, faithfulness)
• Support multiple file types (PDF, DOCX, PPTX, images via OCR)
• Build a simple frontend (maybe with Streamlit or React)

📁 Sneak Peek: Project Structure

For the curious (and fellow nerds), here’s how I organized the codebase:

.
├── Dockerfile
├── docker-compose.yml
├── backend/
│   └── app/
│       ├── routers/          # FastAPI route handlers
│       ├── services/         # Business logic
│       │   ├── embeddings/   # Document loading, chunking, embedding, vector storage
│       │   └── llm/          # Future LLM integration
│       ├── schemas/          # Pydantic models
│       ├── domain/           # Protocols
│       ├── core/             # Config
│       └── utils/            # Helpers (logging, ID generation)
└── uploads/                  # Local file storage (mounted to MinIO)

Clean separation of concerns. Testable components. Extensible design.

💬 Final Thoughts

This project taught me more than any tutorial or course ever could. There’s something deeply satisfying about wiring together open-source tools, debugging tokenizer mismatches, and finally seeing your RAG system return a relevant chunk from your own document.

If you’re thinking about dipping your toes into RAG — don’t reach for an API first. Build it yourself. Break it. Fix it. You’ll learn 10x more.

🔗 GitHub Repo: github.com/debabrot/intelligent-doc-assistant

You’d have no idea how fast you’re going. You wouldn’t know if the engine was overheating. You might run out of gas — and only realize it when the car sputters to a halt on the highway.

Now ask yourself:
Would you trust this car for a long journey?

Probably not.

Yet, every day, thousands of software systems run in production without any real-time visibility. No metrics. No alerts. No dashboard.
And when something goes wrong, teams scramble in the dark — reacting to angry users instead of preventing issues.

This is where monitoring comes in.
It’s not flashy. It won’t win design awards.
But it’s the dashboard of your software — and without it, you’re flying blind.

1. Your System Needs a Dashboard — Just Like Your Car

Think about what your car’s dashboard tells you:

• Speed: Am I going too fast or too slow?
• Fuel level: How much longer can I go?
• Engine temperature: Is something overheating?
• Warning lights: Is the brake system failing?

These aren’t just nice-to-have — they’re essential for safe, confident driving.

Now translate that to your software:

Without monitoring, you won’t know your API is slow until customers complain.
You won’t notice a memory leak until your app crashes.
You’re not just driving blind — you’re letting your users be the canaries in the coal mine.

Monitoring doesn’t prevent failures. But it ensures you’re never surprised by them.

2. Why Monitoring Matters — In Any System

You might think monitoring is only for massive platforms like Netflix or Amazon.

But the truth is:
Every system in production needs monitoring — even small apps.

Here’s why:

• Problems happen silently. A background job fails? A database connection times out? Without metrics, you won’t know.
• Performance degrades slowly. That API endpoint that used to respond in 100ms now takes 800ms — over weeks. Only monitoring catches that drift.
• You can’t improve what you can’t measure. Want to optimize performance? Scale your infrastructure? You need data.

Monitoring turns guesswork into insight.
It transforms “I think it’s slow” into “Error rate increased by 40% at 2:15 PM.”

And that changes everything.

3. Meet Prometheus: Your Software’s Dashboard Tool

So how do you build this dashboard?

One of the best tools for the job is Prometheus — a powerful, open-source monitoring system used by companies of all sizes.

Here’s what makes it great:

• 📊 It collects metrics over time — like request counts, response times, or memory usage.

• 🔍 It lets you query with PromQL — a simple but powerful language to ask things like:

  rate(http_requests_total[5m])
  

  (That shows how many HTTP requests your app is handling per second.)

• 📈 It works with almost anything — web apps, APIs, databases, servers, even batch jobs.
• 💡 It’s free, lightweight, and easy to start with — no enterprise license required.

You don’t need Kubernetes or microservices to use Prometheus.
Even a simple Flask or Express app can expose metrics in minutes.

4. What to Monitor: The Vital Signs of Your App

You don’t need to track everything. Start with the four vital signs of any system:

1. Traffic

How many requests are hitting your app?
A sudden drop might mean a deployment broke your API. A spike could mean a DDoS or a viral feature.

2. Errors

What percentage of requests are failing?
Even 1% error rate can mean hundreds of frustrated users.

3. Latency

How fast are responses?
Users notice delays over 300ms. Monitoring helps you catch slowdowns early.

4. Saturation

Is your server running out of CPU, memory, or disk?
This is your “fuel gauge” — it tells you when you’re running on empty.

Track these four, and you’ll catch 90% of issues before they become outages.

5. From Data to Action: Alerts and Dashboards

Raw numbers aren’t enough. You need visibility and action.

That’s where tools like Grafana come in.

With Grafana, you can turn Prometheus data into beautiful, real-time dashboards — your software’s dashboard, just like in a car.

You can see:

• Live request rates.
• Error trends over time.
• CPU and memory usage across servers.

And with Alertmanager (part of the Prometheus ecosystem), you can set up alerts like:

“Notify me if error rate exceeds 1% for 5 minutes.”

Now, instead of waking up to a Slack message saying “The site is down,” you get a quiet alert at 2:03 AM — and fix the issue before anyone notices.

Start Small, But Start Now

You don’t need a perfect monitoring setup on day one.

Just start:

1. Add the Prometheus client library to your app (takes 10 minutes).
2. Expose one metric (e.g., HTTP request count).
3. Set up Prometheus to scrape it.
4. Build one dashboard in Grafana.
5. Create one alert.

That’s it.

Over time, you’ll add more metrics, refine alerts, and gain deep insight into your system.

But the hardest step is the first one.

So ask yourself again:
Are you driving blind? Or do you have a dashboard?

Your software deserves to be seen.

Give it the visibility it needs — before the next outage catches you by surprise.

“Ever wanted to build your own secure task manager from scratch? Meet TaskFlow — a lightweight, JWT-secured microservice that helps users manage tasks with confidence.”

🔐 What Is TaskFlow?

TaskFlow is a secure, containerized microservice that lets users:

✅ Register & log in
✅ Create, view, edit, and delete personal tasks
✅ Stay authenticated with JWT tokens
✅ Run everything locally with one command

It’s built with:

• FastAPI (backend)
• PostgreSQL (database)
• Streamlit (frontend)
• Docker & Makefile (dev experience)
• JWT + Argon2 (security)

And yes — it’s fully functional, tested, and ready to run.

But more than that — it’s a learning scaffold for concepts I once found intimidating:

• How do APIs actually work?
• What’s the difference between Pydantic schemas and SQLAlchemy models?
• How do you securely store passwords?
• What does “microservice” even mean in practice?

Spoiler: I now understand all of it — and you can too.

🎥 See It in Action

Here’s how TaskFlow works — in just a few seconds:

1. 🔹 User Registration

New users can sign up with a valid email and strong password.

2. 🔹 Login & Authentication

Users log in and receive a secure JWT access token. No sessions, no cookies — just stateless, verifiable tokens.

3. 🔹 Create & Manage Tasks

Once logged in, users can create, view, and manage their tasks in a clean, responsive Streamlit UI.

Note: These GIFs are part of the project repo — feel free to explore the real thing!

💡 Why This Matters

You might think: “Another task app? Really?”

But here’s the truth: CRUD + Authentication is the foundation of 90% of web apps.

Whether you’re building a note-taking app, a CRM, or a SaaS platform — you’ll need:

• User management
• Data persistence
• Secure access control
• API design

TaskFlow gives you all of that — in a simple, understandable, and extendable way.

And because it’s containerized with Docker and Makefile, you can spin it up in seconds — no dependency hell, no “it works on my machine” excuses.

🛠️ Try It Yourself (It’s Easy!)

Want to run TaskFlow locally? Here’s all it takes:

git clone https://github.com/debabrot/TaskFlow
cd TaskFlow

# Build and start backend (PostgreSQL + FastAPI)
make up-build

# In another terminal, launch the frontend
# Create virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate

# Install Streamlit
pip install streamlit

# Launch the frontend
streamlit run frontend/app/main.py

That’s it.

You’ll have:

• FastAPI running on http://localhost:8000 (with live docs at /docs)
• PostgreSQL database managed via Docker
• Streamlit frontend on http://localhost:8501

👉 GitHub Repo: github.com/debabrot/TaskFlow

🔮 What’s Next?

TaskFlow was just the beginning. Now that I’ve mastered the fundamentals, I’m extending it with:

• Multi-tenancy – So teams or organizations can have isolated workspaces
• Role-Based Access Control (RBAC) – Admin, editor, viewer roles
• HMAC request signing – For enhanced API security
• Better frontend – Maybe React, or keep Streamlit for prototyping?

This project proved something powerful:
You don’t need to be a backend expert to build like one.
You just need curiosity, a clear goal, and the willingness to break things — and fix them.

🌱 Final Thought

“Building TaskFlow wasn’t just about managing tasks — it was about mastering the fundamentals of modern backend development.”

If you’re coming from a data science or analytics background, you probably know Python well — for pandas, scikit-learn, maybe even Streamlit dashboards.

But when I first saw Pydantic models like this:

class UserCreate(BaseModel):
    email: EmailStr
    password: str

…I blinked. Twice.

“What is this alien syntax?” I thought. “Since when did Python get types?”

That moment sparked a journey — one that led me to dive deep into microservices, APIs, authentication, databases, and security. And the result? TaskFlow: a full-stack, production-style task management microservice built with FastAPI, PostgreSQL, JWT, and Streamlit.

This wasn’t just a side project. It was my crash course in modern backend development — and I’m excited to share it with you.

From Pydantic confusion to JWT clarity, from ORM uncertainty to SQLAlchemy confidence — this project transformed how I see software.

If you’re a data scientist, analyst, or junior dev looking to level up your full-stack skills, start small. Build something real. Break it. Fix it. Repeat.

And who knows? Your next side project might just teach you more than any tutorial ever could.

💬 Thoughts? Questions? Want to contribute or suggest features?
Let’s chat on GitHub or LinkedIn!
Star the repo if you found it helpful:
⭐ github.com/debabrot/TaskFlow

In the journey to build a Mood-Based Music Recommender chatbot, we’ve explored the frontend (React + Vite), the conversational engine (AWS Lex), and the serverless backend (FastAPI on Lambda with Mangum). Now, it’s time to talk about the invisible glue that holds it all together — Infrastructure as Code (IaC) using AWS Cloud Development Kit (CDK).

If you’ve been manually clicking through the AWS Console to deploy S3 buckets, Lambda functions, or API Gateways, this post will change how you think about infrastructure — forever.

1. 🛠️ What is Infrastructure as Code (IaC)?

Infrastructure as Code (IaC) is the practice of managing and provisioning infrastructure — servers, databases, networks, APIs — using code instead of manual processes.

Instead of navigating the AWS Console to:

• Create an S3 bucket
• Upload a Lambda function
• Set up API Gateway
• Configure IAM roles

You write declarative code that defines your entire stack. Then, with a single command, you deploy it — consistently, reliably, and repeatedly.

💡 Think of IaC like a blueprint for your cloud architecture. Just as you wouldn’t build a house without a plan, you shouldn’t deploy cloud apps without IaC.

Why IaC Matters?

• Reproducibility: Deploy identical environments (dev, staging, prod) every time.
• Version Control: Track infrastructure changes like code — with Git.
• Faster Deployments: Automate setup in minutes, not hours.
• Reduced Human Error: No more “I forgot to attach that policy” moments.
• Team Collaboration: Share, review, and test infrastructure changes via pull requests.

2. 🚀 Why AWS CDK?

There are several IaC tools available — Terraform, CloudFormation, Serverless Framework — but for this project, I used AWS CDK.

What is AWS CDK?

The AWS Cloud Development Kit (CDK) is an open-source framework that lets you define cloud resources using familiar programming languages like Python, TypeScript, Java, or C#.

Unlike raw CloudFormation JSON/YAML templates, CDK uses high-level constructs that abstract away boilerplate, letting you focus on your application.

✅ You write Python → CDK generates CloudFormation → AWS deploys your stack.

Why AWS CDK was chosen This Project?

3. 🧱 How I used CDK in the Mood-Based Music Recommender

The entire architecture — from the React frontend to the Lex bot and backend API — is defined and deployed using AWS CDK in Python.

Here’s a breakdown of what CDK manages:

✅ Components Provisioned via CDK

This means:
➡️ One cdk deploy command = full stack up and running.
➡️ One cdk destroy = clean teardown, no orphaned resources.

4. 🌱 Benefits of Using CDK in This Project

5. 🛑 Challenges & How to Overcame Them

⚠️ Learning Curve

CDK requires understanding both AWS services and programming concepts.
✅ Solution: Start small — deploy a single Lambda, then expand.

⚠️ Lex Support in CDK

Lex V2 constructs are not fully high-level in CDK (yet).
✅ Solution: Use Cfn* (CloudFormation) constructs with well-documented templates.

⚠️ Local Testing

You can’t simulate Lex or API Gateway locally.
✅ Solution: Use cdk synth to preview CloudFormation and test in a sandbox AWS account.

6. 🎯 Conclusion: Why IaC is Non-Negotiable

Building a serverless chatbot is powerful — but doing it manually is unsustainable.

By using AWS CDK, the entire Mood-Based Music Recommender has been turned into a repeatable, version-controlled, and scalable system. Whether you’re deploying for the first time or rolling out updates, CDK ensures consistency, reduces risk, and accelerates development.

🔥 Infrastructure isn’t just “set and forget.” With IaC, it’s code, collaboration, and control.

In our mood-based music recommender journey, we’ve explored AWS Lex and the overall architecture. Now, let’s dive into the backend—an efficient API powered by FastAPI, deployed on AWS Lambda, and made serverless-compatible with Mangum.

1. ⚙️ What is AWS Lambda?

AWS Lambda is a serverless, event-driven compute service that runs code in response to events—without provisioning servers.

✅ Key Benefits:

• Serverless: No infrastructure to manage.
• Event-Driven: Triggered via API Gateway, S3, SQS, etc.
• Pay-per-use: Billed per invocation and execution time.
• Scalable: Automatically handles traffic spikes.
• Multi-language support: Python, Node.js, Java, Go, and more.

📌 In Our Project:

• Lex Fulfillment: Handle chatbot logic.
• API Backend: Serve React frontend, orchestrate services.

2. 🌐 Creating an API in Lambda (Raw vs Framework)

You can write raw Lambda functions for API Gateway, but it quickly becomes complex.

🧱 Basic Lambda API:

Handles event and returns a response dict.

⚠️ Drawbacks of Raw Lambda:

• Manual parsing/validation
• Difficult to scale with routes
• Error-prone for large apps

Using a framework like FastAPI improves developer experience and code structure.

3. 🧠 Why FastAPI + Mangum?

🚀 FastAPI Highlights:

• Async Support: Great for I/O-heavy tasks.
• Type-based Validation: Via Pydantic.
• Auto Docs: Swagger & ReDoc built-in.
• Performance: Among the fastest Python frameworks.
• Developer-Friendly: Intuitive syntax, great tooling.

🔌 What is Mangum?

AWS Lambda doesn’t run ASGI apps directly. Mangum bridges this gap:

• Converts API Gateway events → ASGI scope
• Converts ASGI responses → API Gateway format
• Lets FastAPI run seamlessly on Lambda

⚡ Synergy of FastAPI + Mangum:

• Build modern APIs using familiar tools
• Enjoy Lambda’s scalability and cost-efficiency
• Avoid raw Lambda boilerplate

4. ✅ Pros & ❌ Cons of FastAPI + Mangum on Lambda

✅ Pros:

1. High performance (FastAPI + Lambda improvements)
2. Easy development & built-in validation
3. Auto-scaling from zero
4. Cost-effective for low/variable traffic
5. No server maintenance
6. Rich AWS integration
7. Standard, maintainable code

❌ Cons:

1. Cold starts (though improving)
2. Package size can bloat deployment
3. Local testing can be tricky (use SAM or Serverless Framework)
4. Vendor lock-in with AWS deployment
5. Debugging is CloudWatch-heavy; needs tracing tools

🧩 Conclusion

FastAPI + Mangum + Lambda offers a modern, serverless API stack—perfect for our chatbot’s backend. It connects Lex and the React frontend with business logic that powers personalized music recommendations.

🛠️ In the next post, we’ll walk through inrastructure as a code using AWS CDK!

In this post, I will cover the core of the bot—building the Lex bot itself. I will define intents, create slots, configure prompts, and route the conversation using Lambda for fulfillment. I will also touch on slot validation and custom routing logic.

🧠 Recap: What the Bot Does

The chatbot helps users discover music recommendations based on their current mood. For example:

“I’m feeling energetic.”
“Suggest something chill.”
“I’m a bit down today.”

Based on this input, the bot suggests genres or playlists aligned with that mood.

🛠️ Step 1: Create the Lex Bot

1. Go to AWS Console → Amazon Lex
2. Click “Create bot”
3. Choose Lex V2

4. Fill in basic details:

   • Bot name: MoodMusicBot
   • Language: English (US)
   • IAM permissions: Create a new role or use an existing one with Lex permissions
   • Enable Children’s Privacy (COPPA) as per your need (probably “No”)
   • Hit “Next”

🗣️ Step 2: Define the Intent

We only need one primary intent: GetMusicRecommendationIntent

1. Create an intent and name it.

2. Add sample utterances:

   I'm feeling {mood}
   Suggest something {mood}
   I want {mood} music
   Music for when I'm {mood}
   

3. Add a slot named mood:

   • Slot type: Custom slot or use Amazon’s built-in AMAZON.Literal
   • Prompt: “How are you feeling today?”
   • Required: ✅

🧪 Step 3: Slot Validation (Optional but Recommended)

A Lambda function can be used to validate the mood slot.

💡 Example: Only accept moods from a predefined list (happy, sad, energetic, relaxed, etc.)

Inside Lambda:

def validate_mood(mood: str) -> bool:
    valid_moods = ["happy", "sad", "relaxed", "energetic", "angry"]
    return mood.lower() in valid_moods

Then, return a dialogAction response to re-ask the question if the slot is invalid.

🔄 Step 4: Add Fulfillment Lambda

To integrate custom logic like returning different genres based on mood, add a Lambda function:

1. In the Lex intent, scroll to Fulfillment
2. Choose “AWS Lambda function”
3. Select or create a function

Example response handler in Lambda:

def lambda_handler(event, context):
    mood = event['sessionState']['intent']['slots']['mood']['value']['interpretedValue']
    
    music_map = {
        "happy": "Pop or Dance",
        "sad": "Lo-fi or Acoustic",
        "relaxed": "Jazz or Chillhop",
        "energetic": "Rock or EDM",
        "angry": "Heavy Metal or Rap"
    }
    
    genre = music_map.get(mood.lower(), "something interesting")
    
    return {
        "sessionState": {
            "dialogAction": {
                "type": "Close"
            },
            "intent": {
                "name": event['sessionState']['intent']['name'],
                "state": "Fulfilled"
            }
        },
        "messages": [{
            "contentType": "PlainText",
            "content": f"Based on your mood, I recommend listening to {genre} music!"
        }]
    }

🧪 Test the Bot

1. Build and deploy the bot
2. Test utterances in the Lex console
3. Try incorrect moods to see if validation kicks in

4. Try phrases like:

   • “I want something chill”
   • “Suggest music for when I’m angry”
   • “Play music”

🔁 Bonus: Custom Routing Logic (Advanced)

Let’s say in the future you add more intents like GetPlaylist, SuggestArtist, or handle fallback queries using Bedrock.

You can route to different logic branches in the Lambda function like:

intent = event['sessionState']['intent']['name']

if intent == "GetMusicRecommendationIntent":
    return handle_music_recommendation(event)
elif intent == "FallbackIntent":
    return route_to_bedrock_llm(event)

🧩 Bonus: Custom Workflow Using Code Hooks (Advanced)

By default, Lex handles the entire dialog flow—from prompting for slots to fulfillment—using its built-in dialog manager.

However, if you want full control over the conversation flow, you can enable code hooks and define custom workflows entirely in your Lambda function.

🔧 What Are Code Hooks?

• Code hooks let you intercept the flow at two points:

  • Dialog code hook (for slot elicitation, validation, branching)
  • Fulfillment code hook (for final action/response)

💡 Example Use Case: Custom Routing

Let’s say you want to:

• Skip some slots conditionally
• Add logic like: “If mood is angry and it’s after 10 PM, suggest calm music”
• Or forward fallback requests to an LLM (e.g., Claude or Bedrock)

Enable the code hook in your Lex console:

1. Go to your intent
2. Under “Lambda code hooks”
3. Enable “Dialog code hook” and/or “Fulfillment code hook”

Your Lambda function now controls the routing logic:

def lambda_handler(event, context):
    invocation_source = event['invocationSource']
    
    if invocation_source == "DialogCodeHook":
        # Perform validation, conditional logic, etc.
        return handle_dialog_code_hook(event)
    
    elif invocation_source == "FulfillmentCodeHook":
        return handle_fulfillment(event)

This gives you complete flexibility to customize how the bot behaves, beyond what Lex’s native configuration allows.

🧠 Lex Bots vs LLM Bots: When to Use What?

You might wonder—why use Lex at all when we now have powerful LLMs?

Here’s a quick comparison:

🔹 TL;DR:

Use Lex for structured workflows. Use LLMs when you need open-ended understanding or fallback handling. A hybrid approach is often the best.

Before diving into individual components, let’s take a step back and look at the overall architecture powering the Mood-Based Music Recommender chatbot.

This project uses a modular, serverless architecture built on AWS, with a clear separation between the UI, conversational engine, and fulfillment logic. It showcases how to build scalable, event-driven applications using modern cloud-native tools.

🔧 Architecture Diagram

🧩 High-Level Overview

Here’s how the system is structured:

1. Frontend (React + Vite)

   • A responsive single-page application built with React and Vite.
   • Hosted on Amazon S3 and served via CloudFront for global availability and fast performance.
   • The frontend presents the chatbot UI and interacts with the backend API to communicate with the Lex bot.

2. Backend API (FastAPI + Lambda)

   • A FastAPI application wrapped using Mangum, deployed as an AWS Lambda function.
   • This API acts as the middle layer between the frontend and AWS Lex.
   • When a user sends a message, the API uses boto3 to invoke the Lex bot and retrieve a response. This approach allows custom logging, validation, and integration hooks around Lex interactions.

3. Conversational Engine (AWS Lex V2)

   • The core chatbot is built with AWS Lex V2.
   • It handles natural language understanding — detecting intents (like requesting a song) and extracting relevant slot values (e.g., user mood).
   • The Lex bot is intentionally kept simple with a single intent and slot for focused, effective interactions.

4. Fulfillment Logic (AWS Lambda)

   • Once Lex recognizes the intent and slot, it triggers a fulfillment Lambda function.
   • This function processes the user mood and returns a song recommendation.
   • In the future, this logic can be extended to include dynamic sources like music APIs or personalized recommendations.

5. Infrastructure as Code (AWS CDK)

   • The entire infrastructure — including Lex bot, Lambda functions, API Gateway, S3 bucket, and CloudFront — is provisioned using AWS CDK in Python.
   • This enables repeatable deployments and version-controlled infrastructure changes.

6. Version Control (GitHub)

   • All code and infrastructure definitions are maintained in GitHub, making collaboration and CI/CD integration easier.

🔄 Request Flow

Here’s how a typical request flows through the system:

User → React Frontend → FastAPI (Lambda) → AWS Lex (via boto3) → Fulfillment Lambda → Response → Frontend UI

This design ensures:

• Full control over the Lex interaction lifecycle via the API.
• Clean separation between the frontend and business logic.
• Serverless scalability and low cost for low-to-medium traffic workloads.