# AI System Design

AI system design is not about memorizing diagrams.

It is about learning how to reason when a product uses models, retrieval, tools, memory, evals, and infrastructure together.

Most beginners jump straight to components:

```text
Frontend → API → Vector DB → LLM → Response
```

That is too shallow.

A stronger engineer asks:

- Who is using the system?
- What decision are they trying to make?
- What evidence is trusted?
- What can go wrong?
- What should the system refuse to do?
- How will we know if quality improved?
- What can we debug when the answer is wrong?

## Course map

| Module | What you should learn | Status |
| --- | --- | --- |
| [How to Think in Interviews](interview-framework.md) | How to frame AI system design answers without rambling | Draft |
| [RAG Fundamentals](rag-fundamentals.md) | How to design RAG as a trust pipeline | Strong first version |
| [Agentic Systems](agentic-systems.md) | How to design agents with boundaries and review points | Draft |

## The lesson standard

Every serious lesson should contain:

1. A concrete scenario
2. Why the problem is hard
3. Bad v1 design
4. Better v1 design
5. Architecture diagram
6. Evaluation signals
7. Mistakes to avoid
8. Practice exercise

!!! warning "Avoid summary-only lessons"
    A lesson that only explains definitions will not build your judgement. The goal is to think like an engineer designing a system under constraints.

## Recommended order

Start here:

1. [RAG Fundamentals](rag-fundamentals.md)
2. [Agentic Systems](agentic-systems.md)
3. [How to Think in Interviews](interview-framework.md)

Why this order? Because RAG teaches evidence, agents teach action, and interviews teach communication.

AI system design is not about memorizing diagrams.

AI System Design

# Agentic Systems

An agent is not a chatbot with tools.

An agentic system is a workflow where the system can decide the next step, call tools, observe results, and continue until a goal is reached or a boundary is hit.

The hard part is not making the agent act.

The hard part is making the action safe, observable, reversible, and useful.

## Scenario: support workflow assistant

Imagine an assistant for a SaaS support team.

A user says:

> A customer says they were charged twice. Check the account and prepare a refund if needed.

This is not a normal Q&A problem.

The assistant may need to:

- inspect customer account details
- check invoices
- compare payment events
- draft a support reply
- prepare refund action
- ask for approval before executing
- log every step

Now the system is not only answering. It is acting.

## Bad agent design

A weak design says:

```text
User request → LLM agent → tools → final answer
```

This is dangerous because the system has no clear boundary.

Common mistakes:

- giving the agent too many tools
- no risk classification
- no human approval for money movement
- no trace of why a tool was called
- no retry or rollback plan
- no timeout or stopping condition
- memory mixed with audit logs

!!! danger "Rule"
    The more power an agent has, the more boring and explicit the control layer should be.

## Better agent design

A better design separates reasoning from permission.

```mermaid
flowchart LR
  A[User goal] --> B[Intent and risk classifier]
  B --> C[Planner]
  C --> D[Tool policy check]
  D --> E{Risk level}
  E -->|Low| F[Execute read-only tool]
  E -->|High| G[Human approval]
  G --> H[Execute action]
  F --> I[Observe result]
  H --> I
  I --> J{Goal complete?}
  J -->|No| C
  J -->|Yes| K[Final response and trace]
```

## Action risk levels

| Action | Risk | Control |
| --- | --- | --- |
| Search docs | Low | Log only |
| Read account status | Medium | Permission check |
| Draft refund reply | Medium | Review suggested |
| Execute refund | High | Human approval required |
| Delete account | Critical | Usually block |

This table is more important than the model choice.

## Memory design

Do not put all memory in one bucket.

Use different memory types:

| Memory type | Example | Purpose |
| --- | --- | --- |
| Short-term context | Current ticket details | Solve current task |
| User preference | Customer prefers email | Personalize response |
| Tool state | Refund check completed | Avoid repeating steps |
| Audit history | Tool calls and approvals | Debug and compliance |
| Long-term learning | Common failure categories | Improve future workflow |

A common beginner mistake is to mix audit history and preference memory. That creates confusing and unsafe behavior.

## What to log

For every agent step, log:

- original goal
- planned next step
- selected tool
- input to tool
- output from tool
- risk level
- approval status
- model used
- cost and latency
- final result

If you cannot inspect a step, you cannot trust it.

## Evaluation signals

| Signal | Question | Failure example |
| --- | --- | --- |
| Task success | Did the agent complete the goal? | It found invoices but did not prepare reply |
| Tool correctness | Did it call the right tool? | It searched docs instead of checking billing |
| Boundary safety | Did it ask approval for high-risk action? | Refund executed without review |
| Drift control | Did it stay on task? | It started explaining billing policy instead |
| Trace quality | Can a human inspect the path? | Missing tool inputs or outputs |

## Practice exercise

Design an agent for one workflow:

- pharmacy order support
- college admission inquiry
- refund processing
- internal IT helpdesk

Write:

1. Goal
2. Allowed tools
3. Blocked actions
4. Actions requiring approval
5. Memory types
6. Logs and traces
7. Evaluation signals

## Summary

Agents are useful when a workflow needs reasoning plus action.

But autonomy without boundaries is not engineering.

A good agentic system defines what the system can do, what it cannot do, what needs approval, what gets logged, and how failures are evaluated.

Agentic Systems

# How to Think in AI System Design Interviews

Most candidates lose AI system design interviews before architecture starts.

They hear the prompt and immediately draw boxes:

```text
User → API → Vector DB → LLM → Response
```

That is not system design. That is component listing.

A stronger answer starts by making the problem smaller, clearer, and measurable.

## The interviewer's hidden question

When an interviewer asks:

> Design an AI assistant for customer support.

They are not only asking whether you know RAG or agents.

They are checking whether you can reason about:

- user workflow
- product scope
- data sources
- model behavior
- risk
- evaluation
- latency and cost
- failure handling
- rollout plan

Your answer should prove that you can design a system that survives real users.

## A simple framework

Use this sequence:

```mermaid
flowchart LR
  A[Scope] --> B[Users and workflow]
  B --> C[Success criteria]
  C --> D[Data and evidence]
  D --> E[Architecture]
  E --> F[Failure modes]
  F --> G[Evals and rollout]
```

I call this the **S-U-S-D-A-F-E** flow:

| Step | Meaning | What to say |
| --- | --- | --- |
| S | Scope | What are we building and not building? |
| U | Users | Who uses it and what task do they complete? |
| S | Success | What does good output mean? |
| D | Data | What knowledge or tools does the system need? |
| A | Architecture | What components are needed and why? |
| F | Failures | What can go wrong? |
| E | Evaluation | How do we measure and improve it? |

## Example prompt

> Design an internal data assistant for business analysts.

A weak answer starts with:

> We will use LangChain, vector DB, GPT-4, and a SQL agent.

A stronger answer starts with:

> I would first clarify what analysts need: finding datasets, understanding metric definitions, writing SQL, or debugging query results. These workflows have different risk levels, data permissions, and evaluation criteria.

That opening sounds senior because it separates the product problem from the tools.

## Step 1: scope the problem

Ask:

- Is this assistant for dataset discovery, SQL generation, dashboard explanation, or all of them?
- Is it read-only or can it execute queries?
- Who are the users: analysts, managers, engineers, or executives?
- What data systems are involved?
- What should the assistant refuse to do?

You do not need ten questions. Ask enough to define the first version.

## Step 2: define success

Bad success metric:

> The answer should be accurate.

Better success metrics:

- correct dataset suggested in top 3
- SQL passes syntax check
- answer cites metric definition
- user accepts answer without escalation
- no restricted table is exposed
- latency under five seconds for common questions

Specific metrics make the design easier.

## Step 3: choose architecture based on risk

Not every AI assistant needs the same architecture.

| Workflow | Risk | Better design |
| --- | --- | --- |
| Answer policy question | Medium | RAG with citations |
| Find dataset | Medium | Search plus metadata ranking |
| Write SQL | High | SQL generation with validation and review |
| Execute database update | Very high | Usually avoid or require approval |
| Summarize public docs | Low | Retrieval plus summarization |

This is where many candidates sound shallow. They pick tools before classifying risk.

## Step 4: explain failure modes

For an AI system, failure modes are not optional. They are part of the design.

For a data assistant:

- wrong metric definition
- restricted table leak
- hallucinated column
- expensive query
- stale dataset description
- answer without citation
- no fallback when confidence is low

A good design shows how these failures are detected or prevented.

## Step 5: evaluation plan

You need at least three layers of evaluation:

1. **Retrieval eval**: did we fetch the right source?
2. **Output eval**: did the model produce a correct and grounded answer?
3. **Workflow eval**: did the user complete the task?

For SQL generation, add:

- syntax validation
- dry run
- cost estimate
- table permission check
- human approval for risky queries

## A strong answer skeleton

Use this in interviews:

```text
I would start by narrowing the workflow.
For v1, I will focus on [specific task] for [specific user].
The success criteria are [metrics].
The system needs [data/tools].
The risky parts are [failure modes].
The architecture is [components].
I would evaluate it with [eval plan].
I would roll it out first to [small user group].
```

## Practice exercise

Pick one prompt:

1. Design a customer support AI assistant.
2. Design a campus admission chatbot.
3. Design a pharmacy Q&A assistant.
4. Design an AI assistant for internal company policies.

Write answers for:

- v1 scope
- users
- success metrics
- required data
- architecture
- failure modes
- evaluation
- rollout

## Summary

Do not start with tools.

Start with the workflow, risk, and evaluation bar.

A good AI system design answer shows that you can reason about users, evidence, model behavior, safety, and operations together.

Most candidates lose AI system design interviews before architecture starts.

How to Think in AI System Design Interviews

# RAG Fundamentals

RAG is not a vector database plus a prompt.

A useful RAG system is a **trust pipeline**. It decides which knowledge is allowed, which source is current, which evidence is relevant, whether the user can see it, and how the final answer should explain uncertainty.

If you remember only one line from this lesson, remember this:

> RAG quality is not only answer quality. It is evidence quality plus answer quality.

## Scenario: HR policy assistant

Imagine we are building an internal assistant for employees.

A user asks:

> Can I carry forward unused leaves into next year if I joined in October?

This sounds simple. It is not.

The answer may depend on:

- employee location
- joining date
- employment type
- current policy year
- old policy PDFs
- newer handbook pages
- manager-only clarifications
- leave category
- exceptions for probation or notice period

A demo system may retrieve a paragraph that looks similar and answer confidently. A production system must know whether the evidence is specific, current, allowed, and enough.

## Why naive RAG fails

The naive version looks like this:

```mermaid
flowchart LR
  A[Upload PDFs] --> B[Chunk text]
  B --> C[Create embeddings]
  C --> D[Vector search]
  D --> E[Top chunks to LLM]
  E --> F[Answer]
```

This is useful for a demo. It is dangerous as the whole design.

### What goes wrong

| Problem | What it looks like | Why it matters |
| --- | --- | --- |
| Stale source | Old policy PDF retrieved | User gets outdated answer |
| Bad chunking | Table split from heading | Model loses exception conditions |
| Weak ranking | Broad handbook chunk retrieved | Answer becomes generic |
| Missing permissions | Restricted note enters context | Data leakage risk |
| No citations | Answer sounds confident | User cannot verify |
| No abstention | Model answers anyway | Unsupported claim becomes product behavior |

## Bad v1 design

A bad v1 usually has these decisions:

1. Ingest everything quickly.
2. Split by fixed token size.
3. Store only text and embedding.
4. Retrieve top five chunks.
5. Ask the model to answer.
6. Add citations later.
7. Evaluate by reading a few outputs manually.

This is exactly how many demos start. The issue is not that it is useless. The issue is that it hides the real failure points.

!!! danger "Bad signal"
    If your team says, “The answer looks good,” but cannot show the exact source, source date, access rule, and retrieval trace, the system is not ready.

## Better v1 design

A better v1 is still simple, but it is designed for debugging.

```mermaid
flowchart LR
  A[User question] --> B[User context]
  B --> C[Question classifier]
  C --> D[Metadata filters]
  D --> E[Hybrid retrieval]
  E --> F[Rerank]
  F --> G[Evidence pack]
  G --> H[Answer with citations]
  H --> I[Grounding check]
  I --> J[Feedback and evals]
```

The important change is not just adding more components. The important change is that every step creates a signal we can inspect.

## Step 1: define trusted sources

Before embeddings, decide what sources are allowed.

For the HR assistant, a source inventory may look like this:

| Source | Owner | Update frequency | Access | Risk |
| --- | --- | --- | --- | --- |
| Employee handbook | HR policy team | Quarterly | All employees | Medium |
| Leave policy PDF | HR operations | Yearly | All employees | High if stale |
| Region-specific policy page | Regional HR | As needed | Region employees | High |
| Manager clarification note | HR leadership | As needed | Managers only | Very high |
| FAQ page | HR support | Monthly | All employees | Medium |

This table matters because retrieval quality starts before retrieval. If sources are messy, answers will be messy.

## Step 2: capture useful metadata

Embeddings do not know whether a document is current, restricted, official, or location-specific.

Add metadata like:

```json
{
  "source_type": "policy_page",
  "owner": "HR India",
  "region": "IN",
  "access_group": "all_employees",
  "effective_from": "2026-01-01",
  "last_reviewed": "2026-05-15",
  "policy_area": "leave",
  "document_status": "current"
}
```

Metadata lets the system answer questions like:

- Is this source current?
- Does this user have access?
- Is this region-specific?
- Is this a policy, FAQ, or informal note?
- Should this source override an older document?

## Step 3: classify the question

Not every question should be handled the same way.

The question:

> Can I carry forward unused leaves into next year if I joined in October?

is not a simple keyword lookup. It is an exception case.

A useful classifier might label it as:

```text
intent: policy_exception_case
policy_area: leave
region_needed: true
date_needed: true
user_context_needed: joining_date
risk: medium
```

This classification decides retrieval filters and answer style.

## Step 4: retrieve evidence, not just text

The retrieval target should be an evidence pack.

An evidence pack contains:

- source title
- exact snippet
- section heading
- effective date
- access level
- why it was selected
- whether it conflicts with another source

Example:

```text
Evidence pack

1. Leave Carry Forward Policy, India, 2026
   Section: New joiner carry-forward rules
   Effective: Jan 2026
   Snippet: Employees joining after Sept 30 may carry forward...

2. Annual Leave FAQ, India, May 2026
   Section: Examples
   Snippet: If you joined in October...
```

Now the model has something structured to reason from.

## Step 5: answer with boundaries

A good answer should not just say yes or no.

It should say:

- what the policy says
- what assumptions were used
- where the answer came from
- what is uncertain
- what the user should do next

Example answer shape:

```text
Based on the current India leave policy, employees who joined after Sept 30 can carry forward unused leave under the new-joiner exception, but the exact number depends on leave type and employment status.

I used:
- Leave Carry Forward Policy, India, effective Jan 2026
- Annual Leave FAQ, India, reviewed May 2026

If you are on probation or notice period, HR confirmation is needed because the policy has a separate exception.
```

Notice the answer does not pretend to know everything. It gives a useful answer and marks the boundary.

## Evaluation signals

Do not evaluate only final answers.

Evaluate the full path.

| Signal | Question | Failure example |
| --- | --- | --- |
| Retrieval precision | Did the exact policy section appear in top results? | Broad handbook page retrieved |
| Freshness | Did the current policy outrank old PDFs? | 2023 PDF used for 2026 query |
| Permission safety | Were restricted sources excluded? | Manager-only note used |
| Groundedness | Can every claim be traced to evidence? | Model invents exception |
| Usefulness | Did the answer help the user act? | Answer gives policy but no next step |
| Abstention | Did the system refuse weak evidence? | Model answers despite conflict |

## Debugging playbook

When an answer is wrong, do not immediately change the prompt.

Ask where the failure happened:

1. **Source failure**: Was the right document ingested?
2. **Metadata failure**: Was the source date, region, or access rule missing?
3. **Retrieval failure**: Did the right source fail to appear?
4. **Ranking failure**: Did the right source appear but too low?
5. **Context failure**: Was the evidence pack too noisy?
6. **Generation failure**: Did the model ignore or distort evidence?
7. **UX failure**: Did the answer omit next steps or uncertainty?

This is how a RAG system becomes improvable.

## What I would ship first

For a first production version, I would not ingest the whole company knowledge base.

I would ship:

- one workflow
- one department
- 20 to 50 trusted documents
- 50 gold questions
- mandatory citations
- retrieval logs
- answer feedback
- review queue for low-confidence answers

That is enough to learn whether the architecture works.

## Practice exercise

Pick one domain:

- college notices
- pharmacy FAQs
- HR policies
- product documentation
- internal SOPs

Then answer these:

1. What are the trusted sources?
2. Who owns each source?
3. What metadata is required?
4. What are three common user questions?
5. Which question is simple lookup?
6. Which question is an exception case?
7. What should the system refuse to answer?
8. What five eval cases will catch bad retrieval?

## Summary

RAG is not just a retrieval pattern. It is a product-quality system.

A good RAG system does five things well:

1. Finds the right evidence.
2. Filters by user and source context.
3. Builds a compact evidence pack.
4. Answers with citations and uncertainty.
5. Produces debug signals when it fails.

If you design only for generation, you get demos.

If you design for evidence, evaluation, and debugging, you get a system people can trust.

RAG is not a vector database plus a prompt.

Module	What you should learn	Status
How to Think in Interviews	How to frame AI system design answers without rambling	Draft
RAG Fundamentals	How to design RAG as a trust pipeline	Strong first version
Agentic Systems	How to design agents with boundaries and review points	Draft