Bengaluru, India · Global delivery
Back to home
Architecture decision records

Why, not just what

The judgment behind each system: what we chose, what we rejected, and why.

LangGraph and CrewAI together in QAIP, not just one

Context
QAIP needed a deterministic pipeline and a collaborative review step where five specialist roles check each other's work.
Alternatives considered
Hand-roll the multi-role review logic as more LangGraph nodes, or run the entire pipeline as a CrewAI crew.
Decision
LangGraph owns the outer pipeline's sequencing; CrewAI runs nested inside the test-generation stage specifically for the agent crew.
Why
LangGraph's explicit state graph gives control and observability over the overall flow. CrewAI's role-based pattern fits "specialists reviewing each other" better than raw graph nodes.
Tradeoff accepted
Two frameworks to maintain instead of one — more moving parts, more surface area to keep in sync.
Jira Story Find Gaps CrewAI Tests Execute Report

Java and Python split in SCIP, not a single-language build

Context
SCIP needed both enterprise-grade REST API robustness and real ML capability.
Alternatives considered
Pure Java with a Java ML library, or pure Python carrying the entire API layer.
Decision
Spring Boot for the core API and business logic; a separate Python FastAPI microservice for the AI layer.
Why
Java's ecosystem is stronger for enterprise API concerns. Python's ecosystem is dramatically stronger for the specific ML tools this needed.
Tradeoff accepted
Two services to deploy and monitor instead of one, and a network hop between them instead of an in-process call.
Spring Boot API PostgreSQL Python AI Service

ARIA never gives a direct answer, even when asked to

Context
Early testing showed direct answers scored higher on short-term "helpfulness" ratings than Socratic guidance did.
Alternatives considered
A hybrid mode — direct answers for simple factual questions, Socratic only for problem-solving.
Decision
Strict Socratic-only, no exceptions — enforced by a rule eliminating the "refuse-then-answer" antipattern.
Why
Any exception becomes the path of least resistance under pressure — quietly eroding the entire pedagogical premise from the inside.
Tradeoff accepted
Some students and parents find it less helpful in the moment, in exchange for a guarantee that holds under pressure.
Student Asks Socratic Engine Guiding Question Never Direct Answer

Merging three systems into one RAG layer for ZENTRAVIX

Context
SCIP, ARIA, and QAIP each held valuable data in isolation, with no way to see all three at once.
Alternatives considered
A fourth dashboard that just links out to the other three, or separate reporting UIs per system.
Decision
A RAG layer that ingests real data from all three and answers natural-language questions across them.
Why
"Why is SCIP delayed" needs QAIP's coverage and SCIP's cost data cross-referenced — separate dashboards can't do that.
Tradeoff accepted
Real integration complexity — three different data shapes normalized into one retrievable format, not just linked.
SCIP ARIA QAIP Unified RAG Layer

AIMO watches itself, not just the systems it monitors

Context
AIMO catches AI-specific failures across QAIP, SCIP, and ARIA — but a monitor that can't see its own failures is a blind spot by definition.
Alternatives considered
Treat AIMO as infrastructure assumed reliable, same as most monitoring tools do.
Decision
Include AIMO's own alerting logic inside its own five-incident-type monitoring scope.
Why
During testing, this design choice caught a real bug in AIMO's own alerting — proving the point immediately, not just in theory.
Tradeoff accepted
More complexity in the monitoring logic itself, and an uncomfortable question most monitoring tools never ask: who monitors the monitor?
Watch QAIP Watch SCIP Watch ARIA Watch Itself

BCT as a standalone package, not embedded per-project

Context
Adversarial testing logic was first built specifically inside SCIP.
Alternatives considered
Keep the logic embedded per-project, duplicating it into ARIA and QAIP as each needed similar testing.
Decision
Extract it into a standalone, installable framework — used identically across all three systems.
Why
Three near-identical copies of adversarial-testing logic is itself a quality risk — a bug fixed in one copy silently persists in the other two.
Tradeoff accepted
More upfront work to generalize the API cleanly, and real discipline required to keep it project-agnostic.
Low Pressure Medium Pressure High Pressure Breaking Point

AIPQ auto-reverts, it doesn't just alert

Context
Prompt quality can regress silently between versions — a well-intentioned edit for one behavior can quietly break another.
Alternatives considered
Alert a human when quality drops and wait for manual rollback.
Decision
Automatic reversion to the last passing version the moment a new one scores below threshold — no human step in between.
Why
A silent regression sitting in production for even a day is worse than a slightly-delayed feature. Default to safety, not to someone noticing.
Tradeoff accepted
A better v2 could occasionally get rolled back on a noisy evaluation run — accepted, since false-negative caution beats false-positive damage.
New Prompt v2 Score Check PASSFAIL Deploy v2 Revert to v1

Locator Framework logs the fallback, doesn't hide it

Context
A resilient test framework could just quietly try each fallback strategy until one works, and report all green.
Alternatives considered
Silent fallback — tests keep passing, nobody notices the primary locator is slowly going stale.
Decision
Every time a fallback strategy — not the primary — finds the element, log exactly which one succeeded.
Why
A test suite quietly relying on fallback after fallback is accumulating technical debt invisibly. Visibility into what's degrading is the actual value.
Tradeoff accepted
Noisier logs, in exchange for early warning before a locator fully breaks, not after.
Primary Locator Try Locate PASSFAIL Element Found Fallback Strategy

Modified Z-score over IsolationForest for outlier detection

Context
MTS needs to flag when a handful of extreme values are quietly skewing a reported metric average.
Alternatives considered
IsolationForest — already used elsewhere in the portfolio (SCIP), a natural first choice.
Decision
Modified Z-score (MAD-based), cross-checked against the IQR method — a point only counts as a confirmed outlier if both agree.
Why
NIST-recommended for skewed production data, needs no training step, and produces an explainable number ("4.8 vs threshold 3.5") instead of a black-box flag.
Tradeoff accepted
Less flexible than a trained model for very complex multivariate patterns — the right tradeoff for a tool whose whole point is showing its work, not just a verdict.
Completeness Sample Size Outlier Influence Trust Score
Next step

Stop guessing whether your AI is safe to ship.

Tell us about one AI system. In 30 minutes we will show you where it can fail silently, and what it would take to prove it does not.