NorthBuilt RAG System Documentation

Production-ready serverless RAG system on AWS with S3 Vectors.

Quick Start by Role

New Engineers

1. Project Overview - Understand the system
2. Initial Setup - Configure your environment
3. Testing Guide - Test components and APIs
4. Contributing - Development workflow

DevOps / Infrastructure

1. Pre-Deployment Checklist - Verify prerequisites
2. Bootstrap Guide - Set up AWS foundation
3. Deployment Guide - Deploy infrastructure
4. Monitoring - CloudWatch dashboards and alarms

Operations

1. Operations Runbook - Day-to-day procedures
2. Data Ingestion - Add documents to the system
3. 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

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	$137-147/month (1K queries)
Query Latency	<2s p95 (end-to-end)
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
Deployment	GitHub Actions with OIDC

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: https://github.com/craftcodery/compass
• GitHub Pages Docs: https://craftcodery.github.io/compass
• CHANGELOG: View on GitHub
• AWS Console: https://console.aws.amazon.com

Getting Help

• Documentation: Browse this site
• Issues: https://github.com/craftcodery/compass/issues
• Discussions: https://github.com/craftcodery/compass/discussions
• Support: security@yourcompany.com (for security issues)

---

Documentation last updated: 2025-12-30