Building My First RAG System in One Week with Kiro IDE 🎃

Syed Shahnizam — Tue, 02 Dec 2025 18:26:05 +0000

Submitted for Kiroween Hackathon 2025 - Skeleton Crew Category

🎃 The Challenge

As a junior apps developer, I'd never built a RAG (Retrieval Augmented Generation) system before. The concept seemed intimidating: vector embeddings, semantic search, chunking strategies—all foreign territory. But the Kiroween hackathon's "Skeleton Crew" category sparked an idea: what if I could build ONE reusable skeleton that transforms into ANY AI personality?

Seven days later, I had Project Corpus: a production-ready RAG chatbot that can become a professional legal assistant, a mystical spirit, or anything else—just by swapping a config file.

🔗 Live Demo | GitHub Repo

🔮 What is Project Corpus?

Project Corpus is a document chat application with a twist: the same core logic powers radically different AI personalities.

Two Personalities, One Skeleton:

⚖️ Legal Eagle

Professional legal document analysis
Formal responses with precise citations
Blue corporate styling with typewriter sounds
Perfect for contract analysis and legal research

👻 Ouija Board

Mystical document exploration "from beyond the veil"
Cryptic, atmospheric responses with spooky emojis
Dark gothic theme with blood drip animations
Ambient drone audio with static glitch effects

Both apps share the same skeleton_core module—only the config changes.

🛠️ The Tech Stack

Backend:

Python 3.13 + Flask 3.1.0
ChromaDB 0.5.20 (vector database)
Google Gemini API 0.8.3 (embeddings + generation)
pypdf 5.1.0 (PDF processing)

Frontend:

Vanilla JavaScript (no frameworks!)
Custom CSS with theme variables
Server-Sent Events for real-time progress

Testing:

pytest 7.4.3
Hypothesis 6.92.1 (property-based testing)

Development:

Kiro IDE (the secret weapon 🚀)

🤖 How Kiro Transformed My Development

1. 🎨 Vibe Coding: Learning While Building

As a junior developer, I didn't just need code—I needed to understand RAG. Kiro's conversational approach let me learn and build simultaneously.

Example conversation:

Me: "How do I chunk PDFs by page and preserve page numbers?"

Kiro: *Explains chunking strategies, then generates code that:*
- Extracts PDF pages individually
- Chunks each page with 500 char/50 overlap
- Stores metadata with source, page, chunk_index
- Retrieves page numbers in search results

Most Impressive Generation:
The entire Server-Sent Events upload pipeline in one conversation. I asked for real-time progress tracking, and Kiro generated:

Flask SSE streaming with Response(stream_with_context())
4-stage progress calculation (reading, parsing, vectorizing, finalizing)
Client-side EventSource listener with progress bars
Graceful error handling

I'd never used SSE before. Kiro didn't just write the code—it taught me why SSE beats polling for this use case.

2. 📋 Specs: Systematic UI Polish

After building core features with vibe coding, I created .kiro/spec.md describing the desired user experience:

## 4. Implemented Features
1. **Document Upload (`/upload`):** 
   - Real-time progress tracking via SSE
   - Page-aware chunking with metadata
   - File validation (type, size, content)

2. **Chat Interface (`/chat`):**
   - Semantic search with relevance filtering
   - Source citations with page numbers
   - Typewriter effect for responses

With the spec in place, I could say "implement section 4.1" and Kiro would systematically add all features—no back-and-forth needed.

Vibe Coding vs. Specs:

Vibe Coding: Exploratory, great for learning and core features
Specs: Systematic, perfect for polish and completeness

3. 📚 Steering Docs: Teaching Kiro My Architecture

I created four steering documents that taught Kiro the project's DNA:

structure.md - The game-changer:

### Skeleton + Config Pattern

The `skeleton_core` module contains all shared RAG functionality. 
Individual app folders provide configuration objects that customize behavior.

Each `app_*/config.py` must define:
- APP_NAME: String for branding
- THEME_CSS: CSS theme identifier
- SYSTEM_PROMPT: AI personality instructions
- CHUNK_SIZE, CHUNK_OVERLAP, TOP_K_RESULTS, RELEVANCE_THRESHOLD

Before steering docs:

Me: "Add a delete document feature"
Kiro: Modifies app_legal/main.py directly ❌ (breaks reusability)

After steering docs:

Me: "Add a delete document feature"
Kiro: Adds delete_document() to skeleton_core/vector_store.py, creates /documents/<source> DELETE route, updates frontend ✅ (maintains skeleton pattern)

Steering docs reduced "wrong suggestions" by ~80%. Kiro became a partner who understood the project's philosophy, not just its syntax.

4. 🪝 Agent Hooks: Automated Quality Assurance

I built 5 hooks that caught bugs before I could deploy them:

test-runner-on-save.kiro.hook

{
  "when": { "type": "fileEdited", "patterns": ["**/*.py"] },
  "then": { "type": "runCommand", "command": "pytest --tb=short -q" }
}

Runs tests automatically on every save. Caught breaking changes instantly—refactored vector_store.py and tests failed immediately, showing I'd broken the search function. Fixed in 2 minutes instead of hours later.

config-validator.kiro.hook
Validates config files have all 7 required fields. Caught 3 instances where I forgot RAG parameters, preventing runtime errors.

env-check-on-session.kiro.hook
Verifies GOOGLE_API_KEY exists on session start. Saved 10+ minutes of "API key not found" debugging.

Impact: Transformed my workflow from reactive debugging to proactive validation. Hooks acted as a safety net for a junior developer who makes mistakes.

🧟 The Biggest Challenges

1. RAG Learning Curve

Understanding vector embeddings, semantic search, and chunking was overwhelming. Kiro became my teacher—I could ask "why are my search results irrelevant?" and get explanations + solutions.

Solution: Implemented relevance filtering that only shows documents within 0.3 distance units of the best match. Now citations are accurate and trustworthy.

2. Page-Aware Chunking

Getting page numbers to persist through extraction → chunking → embedding → storage → retrieval required careful metadata management.

Solution: Kiro helped me trace the data flow and add page tracking at each stage with metadata={'source': filename, 'page': page_num, 'chunk_index': i}.

3. Theme Switching Architecture

Designing a system where one codebase supports radically different personalities (formal legal vs. mystical ghost) required careful abstraction.

Solution: The config-based approach emerged from iterating with Kiro on the architecture. Now adding a new personality takes ~10 minutes.

🏆 What I'm Proud Of

1. Learning RAG in One Week

Went from zero RAG knowledge to a production-ready system with vector search, embeddings, and semantic retrieval in 7 days. Kiro's vibe coding made this possible.

2. The Skeleton Pattern Works

The architecture is genuinely reusable. Adding a new personality:

mkdir app_detective
# Add config.py with Config class
# Add main.py entry point
# Done! 🎉

3. Production-Quality UI

Smooth animations (typewriter effect, blood drips)
Real-time upload progress with SSE
Document library with selective filtering
Accessibility (ARIA labels, keyboard navigation)
Theme-specific audio (typewriter, ambient drone)

4. Comprehensive Testing

14 test files using property-based testing with Hypothesis. First time using this approach—Kiro helped me understand how to test UI behavior systematically.

📚 Key Learnings

Technical:

How RAG systems work (chunking, embeddings, vector search)
ChromaDB operations and cosine similarity
Google Gemini API (generation + embeddings)
Server-Sent Events for real-time updates
Property-based testing with Hypothesis

Kiro-Specific:

Steering docs are game-changers: Once Kiro understood my architecture, every suggestion was contextually perfect
Specs accelerate polish: Vibe coding for core features, specs for systematic enhancement
Hooks catch mistakes early: Automated validation saved me from broken configs and missing env vars
Conversational learning: Being able to ask "why?" while building code is incredibly powerful for junior developers

🔮 What's Next?

New Personalities:

🔍 Detective: Investigative analysis with noir styling
🧪 Scientist: Technical document analysis with lab aesthetics
📜 Poet: Creative interpretation with literary flair
📚 Historian: Archival research with vintage styling

Advanced RAG:

Multi-query retrieval for better coverage
Re-ranking algorithms for improved relevance
Citation highlighting (show exact text snippets)
Cross-document synthesis

Platform:

Additional formats (DOCX, Markdown, HTML)
User authentication and document privacy
Collaborative document libraries
Docker containerization

🎯 The Verdict: Kiro for Junior Developers

As a junior developer tackling RAG for the first time, Kiro was transformative:

✅ Vibe coding let me learn concepts while building

✅ Specs systematized complex features

✅ Steering docs maintained architectural consistency

✅ Hooks caught bugs before deployment

Without Kiro: Weeks of reading docs, trial-and-error debugging, architectural mistakes

With Kiro: One week to a production-ready system while learning RAG fundamentals

The skeleton architecture is ready to support infinite personalities—limited only by imagination. 🎃👻

🔗 Links

Live Demo: [https://corpus-rag-skeleton.onrender.com/]
GitHub Repo: [https://github.com/Wafflez007/corpus-rag-skeleton]
Category: Skeleton Crew
Kiro Features: Vibe Coding, Specs, Steering Docs, Agent Hooks

Built for Kiroween 2025 🎃

From zero RAG knowledge to production in one week—powered by Kiro IDE

kiro #ai #rag #hackathon #python #flask #chromadb #gemini

DEV Community: Syed Shahnizam