DEV Community

Cover image for Building My First RAG System in One Week with Kiro IDE 🎃
Syed Shahnizam
Syed Shahnizam

Posted on

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

#beginners #rag #ai #kiro

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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" }
}
Enter fullscreen mode Exit fullscreen mode

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! 🎉
Enter fullscreen mode Exit fullscreen mode

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

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

Top comments (0)