# Ask Justin: How Its Built

## Overview
Ask Justin is a retrieval-augmented (RAG) chat experience designed to answer questions about my leadership approach, engineering execution, and scenario playbooks. The system is intentionally narrow: it pulls from curated content and responds with concise, director-level guidance.

## Guiding ideas (first principles)
- Truth over fluency: if the source material does not support an answer, the assistant should say so.
- Clarity and accountability: small, direct responses with explicit tradeoffs.
- Speed with guardrails: fast iteration, but high confidence in safety and correctness.
- Minimal surface area: only the data and features needed to answer leadership questions.

## Architecture (high level)
- Frontend: Next.js (Amplify SSR) chat UI with a lightweight streaming-style reader.
- API: API Gateway for /api/token, CloudFront + Lambda URL for streaming /api/chat.
- Retrieval: content and embeddings stored in S3; Lambda fetches the index at runtime.
- Models: OpenAI or Bedrock, selectable via environment variables.
- Security: Cloudflare Turnstile, JWTs, WAF rules, and strict CORS.

## Data flow
1) User asks a question in the UI.
2) The UI gets a short-lived JWT from /api/token.
3) /api/chat enforces scope, validates the JWT, and loads the RAG index.
4) The top sources are retrieved and passed to the model.
5) The answer is returned as SSE-compatible events.

## Content and RAG pipeline
- Source materials live in /content (resume, principles, scenarios, FAQs).
- A local indexing step chunks content and generates embeddings.
- The embeddings JSONL file is uploaded to S3 and read by the chat Lambda.
- Retrieval returns the top-K sources to ground responses.

## Streaming status
- /api/chat streams via CloudFront + Lambda URL with SSE.
- API Gateway remains in place for /api/token.

## Technology stack
- Frontend: Next.js (React), TypeScript
- API: AWS Lambda, API Gateway, Lambda URL, CloudFront
- Infra: Terraform
- Storage: S3 (content + embeddings), DynamoDB (quota scaffolding)
- Security: Cloudflare Turnstile, JWTs, AWS WAF
- Models: OpenAI Responses API or AWS Bedrock

## Why this approach
This system is built to answer questions like a hands-on engineering leader, not a generic chatbot. It is intentionally narrow, traceable to real source material, and designed to scale from startup-speed execution to enterprise-grade reliability.