NorthBuilt RAG System Documentation
Production-ready serverless RAG system on AWS with S3 Vectors.
Quick Start by Role
New Engineers
- Project Overview - Understand the system
- Initial Setup - Configure your environment
- Testing Guide - Test components and APIs
- Contributing - Development workflow
DevOps / Infrastructure
- Pre-Deployment Checklist - Verify prerequisites
- Bootstrap Guide - Set up AWS foundation
- Deployment Guide - Deploy infrastructure
- Monitoring - CloudWatch dashboards and alarms
Operations
- Operations Runbook - Day-to-day procedures
- Data Ingestion - Add documents to the system
- Troubleshooting - Common issues and solutions
Documentation Categories
Setup
Get started with the system.
- Project Overview - What is this system?
- Initial Setup - Prerequisites and AWS configuration
- Pre-Deployment Checklist - Manual requirements before deployment
- Bootstrap Guide - Set up AWS OIDC and Terraform backend
Architecture
Understand how the system works.
- System Architecture - Complete technical architecture
- Cost Analysis - Monthly costs and optimization
- Security - Authentication, encryption, compliance
- Architecture Decision Records - Why we made key technical decisions
- RAG Changelog - History of implemented improvements
Operations Guides
Deploy and maintain the system.
- Deployment - GitHub Actions and manual deployment
- Monitoring - CloudWatch metrics, logs, and alarms
- Data Ingestion - Webhooks and manual document upload
- Operations Runbook - Daily tasks and procedures
- Troubleshooting - Common issues and fixes
Development
Contribute to the project.
- Testing Guide - Unit tests and AWS integration testing
- Contributing - Branch strategy, PR process, code standards
Infrastructure
Deep dive into Terraform and AWS.
- Terraform Modules - Detailed module documentation
Reference
API and configuration reference.
- API Reference - REST API endpoints and schemas
System Stats
| Metric | Value |
|---|---|
| Monthly Cost | ~$140/month (1K queries) |
| Time to First Token | <2s (streaming) |
| Vector Search | <25ms p95 (S3 Vectors) |
| Architecture | 100% serverless (Lambda, API Gateway) |
| LLM | Claude Sonnet 4.5 via Bedrock |
| Vector DB | S3 Vectors (1024-dim, cosine) |
| Auth | Cognito + Google OAuth |
| Streaming | SSE via Lambda Response Streaming |
Quick Reference
Common Commands
# Deploy infrastructure
cd terraform && terraform apply
# View logs
aws logs tail /aws/lambda/nb-rag-sys-chat --follow
# Test API endpoint
curl -X POST https://[api-url]/chat \
-H "Authorization: Bearer [jwt]" \
-d '{"query": "test"}'
# Check system health
./scripts/morning-health-check.sh
# Check S3 Vectors status
aws s3api head-bucket --bucket nb-rag-sys-vectors
Useful Links
- GitHub Repository: github.com/craftcodery/compass
- GitHub Releases: Releases
- Issues: Report a bug or request a feature
Getting Help
- Documentation: Browse this site
- Issues: github.com/craftcodery/compass/issues
Last updated: 2026-01-08