Engineering Intelligence Hub
Inspiration
During a production incident, an engineer may need a very specific answer quickly:
How do I roll back this deployment? What is the documented rate limit? Which configuration controls this service?
The answer may already exist somewhere in a runbook, RFC, specification, or Markdown file but finding it can mean searching through multiple documents.
A general-purpose AI assistant creates a different problem. If the relevant documentation is not available in its context, the model may produce a technically plausible answer that is not actually supported by the team's documentation.
That led us to a simple idea:
What if an engineering AI system retrieved the relevant documentation first, then generated the answer from that evidence?
We built Engineering Intelligence Hub around that idea.
The goal was not simply to create another chatbot. We wanted the answer to remain connected to the documentation that supports it, so an engineer can inspect the retrieved source instead of taking the generated response on trust.
How We Built It
We separated retrieval from generation.
Instead of sending the entire document collection to the language model, the system first finds the most relevant passages and uses those passages as the context for generation.
The core pipeline is:
Technical Documents
↓
Parsing
↓
Chunking
↓
Embeddings
↓
Vector Index
↓
Semantic Retrieval
↓
Context Validation
↓
Grounded Generation
↓
Answer + Citations
Core Implementation
- Application: Built with TanStack Start, React 19, and Vite, with server-side functions handling application operations.
- Document ingestion: Supports
.pdf,.txt,.md, and.markdownfiles usingunpdfandpdfjs-dist. - Chunking: Documents are divided into approximately 1,000-character passages with 150-character overlap to preserve context between neighboring chunks.
- Embeddings: Uses
text-embedding-3-smallto create 1536-dimensional document and query vectors. - Vector search: Stores embeddings in Supabase PostgreSQL using
pgvectorwith HNSW indexing. - Retrieval: The system compares the query against document chunks using cosine similarity and retrieves the highest-scoring passages.
- Generation: Retrieved evidence is passed to
google/gemini-3.6-flashwith instructions to answer from the supplied context and cite supporting sources. - Validation: A minimum similarity threshold of
0.18acts as a retrieval gate before generation. - Fallback retrieval: When external database or AI configuration is unavailable, a local vector representation can be used to keep the core retrieval workflow available in a degraded mode.
- Validation of application data: Zod schemas are used to validate structured data across the application.
The retrieval stage uses cosine similarity to compare the question vector (Q) with a document chunk vector (C):
$$ \text{Similarity}(Q,C)=\frac{Q\cdot C}{\lVert Q\rVert\lVert C\rVert} $$
Only retrieved passages meeting the configured threshold are passed forward for answer generation.
Challenges We Faced
1. Deploying TanStack Start on Vercel
Challenge:
Our initial TanStack Start deployment returned 404: NOT_FOUND for application routes on Vercel.
Solution:
We introduced a dedicated serverless entry point in api/server.ts and configured vercel.json rewrites so dynamic requests were routed to the application server correctly.
This was a useful lesson in understanding how the framework's server-side routing maps onto a serverless deployment environment.
2. Handling Missing External Services
Challenge: The application could fail when database credentials or AI API configuration were unavailable.
For a retrieval application, allowing one missing external dependency to break the entire workflow creates a poor development experience.
Solution: We added graceful error handling and a dual retrieval path. When the primary database or AI configuration is unavailable, the application can fall back to local vector retrieval and expose diagnostic information during development.
The fallback does not attempt to replace the semantic quality of the primary embedding model. Its purpose is to keep the core workflow usable in degraded environments.
3. Vite/PostCSS Configuration Conflicts
Challenge: Vite's CSS processing was discovering conflicting PostCSS configuration from outside the project directory.
Solution:
We added a project-scoped postcss.config.js so the application uses the intended CSS processing configuration.
Although this was a smaller issue than the deployment problem, it reinforced the importance of keeping build configuration explicit and scoped to the project.
What We Learned
Retrieval quality matters as much as generation
One of the biggest lessons from building the project was that a RAG system is not simply an LLM connected to a vector database.
The quality of the retrieved context directly affects the quality of the final response.
We gained practical experience with:
- Embeddings
- Chunk size and overlap
- Cosine similarity
pgvector- HNSW indexing
- Similarity thresholds
- Context selection
- Retrieval failure cases
Small retrieval decisions can significantly change what evidence reaches the generation model.
Designing for degraded operation
We also learned that an external dependency failure should not automatically make an application unusable.
Adding a fallback retrieval path gave us a way to continue working with the system when external configuration was missing or unavailable.
This also made failure states more visible during development instead of hiding them behind generic application errors.
Building type-safe server boundaries
Using TanStack Start's server functions together with Zod validation helped us maintain clearer boundaries between client-side interactions and server-side operations.
It also made structured inputs and outputs easier to reason about as the application grew.
Making AI output inspectable
Another important lesson was that showing an AI-generated answer is not enough for technical use cases.
We wanted users to see:
Answer
↓
Citation
↓
Document
↓
Chunk
↓
Retrieved Text
↓
Similarity
This makes the result easier to inspect and compare against the underlying documentation.
What's Next
Git Repository Integration
The next step is to extend ingestion beyond standalone documents.
The system could index:
- GitHub README files
- Source-code documentation
- Code comments
- OpenAPI / Swagger specifications
This would allow the same retrieval workflow to work across both documentation and code-related knowledge.
Hybrid Search
Vector search is useful for semantic meaning, but engineering queries often contain exact identifiers such as:
API names
CLI commands
Configuration keys
Function names
Error codes
A hybrid retrieval system combining vector search with keyword-based retrieval such as BM25 could improve results for these exact-match cases.
Workspace Analytics
Future versions could provide shared query history, citation analytics, and retrieval metrics to help teams understand which parts of their documentation are being searched and where retrieval quality could be improved.
Closing
Engineering Intelligence Hub started with a simple question:
Can an AI system answer engineering questions while making the evidence behind those answers easy to inspect?
The current project focuses on that core workflow:
Retrieve → Validate → Generate → Cite
Building it taught us that reliable AI experiences are not only about the language model. They also depend on the quality of the information retrieved, the boundaries placed around generation, and how clearly the system exposes the evidence behind its output.
The next step is to take the same approach beyond technical documents and into codebases, APIs, and larger engineering knowledge bases.
Built With
- eslint
- html5
- lucide-react
- nitro
- node.js
- openai-api
- pdf.js
- pgvector
- postgresql
- prettier
- radix-ui
- rag
- react
- rest-api
- shadcn-ui
- supabase
- tailwindcss
- tanstack-query
- tanstack-router
- tanstack-start
- typescript
- vector-search
- vercel
- vite
- vitest
Log in or sign up for Devpost to join the conversation.