~/decisions — architecture is mostly what you refuse to build
Decision log
Real calls from real systems, with the costs I accepted on purpose. This is the part of engineering that never fits in a skills list.
DECISION 01One LLM contract over four providers → provider-agnostic tool-calling layer
Jagriq orchestrates OpenAI, Anthropic, Google and Bedrock. Each has its own tool-calling dialect, failure modes and pricing.
WHAT IT COST
An abstraction tax — every new provider feature lands behind the adapter, never before it.
Lowest-common-denominator pressure: exotic per-provider features need escape hatches.
WHAT IT BOUGHT
Zero vendor lock. Models are a config change, not a rewrite.
One place for cost accounting, caching, idempotency and OTel tracing — instead of four.
Citations are verified, not trusted → hard verification gate against an external corpus API
LLMs cite confidently and wrongly. In a legal-adjacent corpus, one invented reference costs more than a thousand slow answers.
WHAT IT COST
Latency on every single answer — the gate is synchronous and non-negotiable.
Engineering a resolver for every citation format the corpus emits.
WHAT IT BOUGHT
Unverifiable attributions: zero. Not 'rare' — zero, by construction.
Failures surface as visible rejections instead of silent lies.
Rebuild ingestion instead of patching it → async rewrite of the OCR pipeline
A race condition was corrupting ~22% of ingested documents across 22 languages. The old pipeline could be patched to hide it.
WHAT IT COST
Weeks of rebuild while the corpus kept growing.
Migration risk on live data mid-flight.
WHAT IT BOUGHT
The corruption class is gone, not suppressed — async parsing removed the shared state entirely.
Throughput headroom that the patch would never have bought.
A dedicated vector store over pgvector → Qdrant beside the existing databases
329K structured units with heavy metadata filtering. Postgres was already in the stack; pgvector would have been the comfortable call.
WHAT IT COST
One more stateful service to operate, back up and monitor.
Data now lives in two places; sync becomes a real job.
WHAT IT BOUGHT
Filtered HNSW search stays fast as the corpus grows — filtering happens inside the index, not after it.
Collection-level isolation for experiments without touching production tables.
Off-policy RL for a drone that can't afford practice → Soft Actor-Critic over PPO
Simulator hours were the scarce resource on the drone program. On-policy methods throw experience away after one gradient step.
WHAT IT COST
Trickier convergence — entropy tuning became a daily argument.
A replay buffer full of stale transitions to reason about.
WHAT IT BOUGHT
Every simulated flight got reused many times — sample efficiency paid for the complexity.
Smooth continuous-control outputs that a real airframe could actually fly.
Microfrontends for a product that didn't exist yet → plugin architecture for Memoir
IGIT needed to ship voice, chat and client-specific features without knowing which would survive contact with users.
WHAT IT COST
Build tooling complexity a monolith never has.
Version skew between fragments becomes a testable surface.
WHAT IT BOUGHT
Features load dynamically — a client integration ships without redeploying the shell.
Dead experiments unplug cleanly instead of fossilizing in the bundle.