Over the past few months, I've spent a lot of time building AI-powered applications.
Like many developers, I started with a simple question:
How can I make the model smarter?
But somewhere along the way, I realized I was asking the wrong question.
The question that really mattered was:
How do I build an AI that people can trust?
That shift completely changed how I think about AI systems.
Instead of obsessing over prompts and model performance, I started thinking about retrieval, evaluation, confidence, and something surprisingly difficult for AI:
Knowing when to say, "I don't know."
That led me to rethink the architecture behind an AI tutor I was building for the BossFx AI Platform.
This article walks through that journey—the design decisions, trade-offs, failures, and lessons that reshaped how I think about building AI systems.
I'd genuinely love to hear how other engineers approach reliability and trust when building with LLMs
![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/rum69mxfy9u2m5jz3u7f.png]
Figure 1. High-level architecture of the BossFx AI Learning Assistant.
The Problem
Retail forex education attracts exactly the people who can least afford a confidently wrong answer.
A beginner who receives incorrect guidance about leverage, stop-losses, or risk management can lose real money.
When I started building an AI learning assistant for BossFx students, I realized the hardest requirement wasn't:
"Answer questions."
It was:
"Never answer beyond what the curriculum actually teaches—and admit it when it doesn't know."
That completely reframed the engineering problem.
A chatbot optimizes for a good answer.
A trustworthy tutor optimizes for the right answer—or an honest:
"I don't have material on that yet. Please ask your mentor."
In this domain, hallucinations aren't just annoying.
They're liabilities.
Constraints That Shaped Every Decision
Every architecture reflects its constraints.
Mine were straightforward.
Solo Founder
I'm the only engineer maintaining the platform.
That meant choosing technologies that reduce operational overhead rather than maximize technical novelty.
Boring infrastructure wins.
Real-Money Domain
Nothing the assistant says should ever be interpreted as personalized financial advice.
The "I don't know" path became one of the most important parts of the system.
Honesty as a Feature
Rather than pretending the AI knows everything, the platform measures—and openly admits—what it cannot yet do.
Architecture
The platform is built around a TypeScript monorepo with a deliberately capability-agnostic core.
Its main components include:
Provider adapter supporting Anthropic and OpenAI
PostgreSQL + pgvector retrieval layer
Retrieval-Augmented Generation (RAG) pipeline
Evaluation harness
Editorial governance before knowledge becomes searchable
The Learning Assistant is simply the first capability running on this architecture.
Every future AI capability inherits the same retrieval, evaluation, and governance automatically.
One rule exists throughout the platform:
Knowledge is never retrievable until a human approves it.
.
ADR-001 — pgvector Instead of a Dedicated Vector Database
For hundreds or even a few thousand curriculum chunks, PostgreSQL with pgvector provided everything I needed.
Adding another infrastructure component simply wasn't worth the operational cost.
ADR-002 — Provider Abstraction
No application code talks directly to OpenAI or Anthropic.
Everything passes through a provider adapter.
That abstraction proved invaluable during later model migrations.
ADR-011 — Editorial Review Enforced Twice
Every knowledge document carries a reviewed_at timestamp.
Both SQL and the TypeScript retrieval layer independently enforce that requirement.
If content changes, approval is automatically revoked until a human reviews it again.
Defense in depth.
ADR-004 — Evaluation Before Deployment
Evaluation wasn't added after the assistant worked.
It was designed into the platform from the beginning.
Changes to prompts, retrieval logic, or model configuration are expected to pass evaluation before deployment.
ADR-007 — Version-Controlled Prompts
Prompts are production assets.
They're versioned, reviewed, tested, and rolled back exactly like application code.
Why the First Quality Score Was Only 35.7%
The platform's first official evaluation scored 35.7%.
I could have delayed publishing that number.
I didn't.
That score became one of the most valuable engineering artifacts in the project.
Here's why.
Every topic fully covered by the curriculum passed.
Most failures weren't engineering failures.
They were curriculum gaps.
The assistant correctly refused to answer questions it had never been taught.
That's exactly the behavior I wanted.
One remaining failure exposed a genuine retrieval tuning issue.
Instead of hiding weaknesses behind a higher percentage, the evaluation produced a roadmap.
The platform now knows exactly which content should be added next.
Supporting metrics included:
Grounding failure rate: 7.7%
Retrieval precision: 22.6%
Retrieval recall: 42.9%
p50 latency: 4.5s
p95 latency: 5.5s
Average query cost: $0.00225
The score wasn't the finish line.
It became the baseline.
A Bug That 86 Passing Tests Missed
One lesson surprised me.
The evaluation judge used Claude to score generated answers.
Everything passed locally.
Eighty-six automated tests stayed green.
Then the first real API call failed.
Claude's newer models rejected a temperature parameter that older integrations accepted.
Mocks never caught it.
A real API immediately did.
Fortunately, two design decisions paid off.
The evaluation failed closed instead of silently succeeding.
The provider adapter meant the fix required changing one file.
Since then, every new model family gets a real production smoke test before it's trusted.
Measure Before You Optimize
The retrieval layer originally used a similarity threshold of 0.25.
Evaluation showed exactly why that wasn't good enough.
Relevant content clustered around 0.56–0.65.
Irrelevant glossary content sometimes reached 0.47.
Instead of guessing a new threshold, I now have evidence to guide the decision.
The recommendation is to increase the threshold gradually as the curriculum expands—not before.
The lesson was simple:
Measure first. Optimize second.
Automation Prepares. Humans Approve.
Over time, one principle began shaping every part of the platform.
Automation prepares
Ingests
Chunks
Embeds
Retrieves
Evaluates
Reports
Humans approve
Curriculum
Editorial reviews
Evaluation baselines
Prompt releases
Milestones
That principle started as an ingestion rule.
It eventually became the governance model for the entire platform.
Outcomes
The project now includes:
✅ A production RAG platform tested against real providers—not mocks
✅ An 11-document curriculum containing 106 reviewed knowledge chunks
✅ Human approval before any document becomes retrievable
✅ Immutable Architecture Decision Records
✅ Five frozen engineering milestones
✅ 86 automated tests
✅ An archived quality baseline future versions must beat
What's Next
The encouraging part isn't the current score.
It's that every weakness is measurable, reproducible, and tied to a concrete engineering decision.
That makes the roadmap evidence-driven instead of intuition-driven.
Next milestones include:
Expanding curriculum coverage
Calibrating retrieval thresholds using collected evaluation data
Integrating evaluation into CI
Re-running the benchmark
The score only earns the right to improve after the engineering work has been done.
Final Thoughts
One thing this project taught me is that trust isn't something you add to an AI system later.
It's something you design for from the beginning.
Writing this article reminded me how valuable documentation is. Explaining the architecture, the failures, and the trade-offs forced me to understand the system more deeply than writing code alone ever could.
I'll continue documenting what I build, the engineering decisions behind it, and the lessons I learn along the way.
If you've built something similar, or you think there's a trade-off you would have made differently, I'd genuinely love to hear your perspective.
Thanks for reading.
About Me
I'm Timilehin, an AI Software Engineer from Nigeria who enjoys building AI systems that are useful, reliable, and grounded in real engineering.
Most of my work sits at the intersection of AI, software engineering, and automation. I enjoy documenting not just what I build, but the architectural decisions and trade-offs behind it.
🌐 Portfolio: https://timilehin-shobande.vercel.app
🐙 GitHub: https://github.com/Gabby-tech
Top comments (0)