Building a Real AI App: What the Pieces Do
A real AI app is not "one prompt and a button." It is a small software system wrapped around a model.
The model generates text. The app handles everything else: users, inputs, permissions, files, tools, cost, errors, and display.
The mental model
browser UI
-> app server
-> prompt/context builder
-> model provider
-> validator
-> response UI
-> logs/evals
This lesson focuses on the pieces and decisions. If you understand the architecture, the code becomes much easier to write later.
Piece 1: user interface
The UI should help users give the model the right information.
Instead of one vague textbox, give structure:
| Field | Why it helps |
|---|---|
| task | tells the model what to do |
| audience | controls tone and depth |
| source text | grounds the answer |
| output style | prevents generic responses |
| constraints | avoids unwanted behavior |
Piece 2: API route
The API route protects your model key. The browser should never contain private API keys.
The route's job:
- receive user input
- validate it
- build messages
- call the provider
- stream or return the answer
- log safe metadata
Piece 3: prompt and context builder
This is where quality lives.
Bad:
Answer this: {userInput}
Better:
You are a concise product-writing assistant.
Use the user's notes only.
If information is missing, ask one clarifying question.
Return: headline, summary, next steps.
Piece 4: model provider
Your app should not be glued forever to one model name.
Use a model setting like:
fast model -> simple tasks
balanced model -> normal chat
reasoning model -> hard planning or debugging
long-context model -> large files
That way you can update providers later without rewriting the whole app.
Piece 5: output validation
If output goes into code, database, email, or tools, validate it.
Examples:
- check JSON schema
- limit length
- require citations
- block unsafe actions
- ask for human approval
Piece 6: streaming
Streaming improves perceived speed. Users see the answer appear while the model is still generating.
Use streaming when:
- answers are long
- the user is waiting interactively
- partial output is useful
Do not stream when:
- you must validate the whole JSON object first
- output triggers an action
- moderation must happen before display
Piece 7: cost and logging
Track:
- model
- prompt version
- input tokens
- output tokens
- latency
- error type
- user feedback
Do not log secrets or full private documents unless your product policy allows it.
A clean first version
Build this first:
- Textarea for user input.
- Dropdown for task type.
- Server API route.
- One good prompt per task.
- Streaming text response.
- Error message if provider fails.
- Token/cost estimate.
Everything else can come later.
Knowledge check
Q1: Why should model API keys stay on the server?
Because browser code is visible to users and keys can be stolen.
Q2: What is the biggest quality lever in a simple AI app?
How you structure the task, prompt, context, and output format.