Forem: Josh Blair

Zero-Secret CI/CD: GitHub Actions + OIDC on AWS (Part 6)

Josh Blair — Thu, 21 May 2026 02:04:06 +0000

Zero-Secret CI/CD: GitHub Actions + OIDC on AWS (Part 6)

No AWS_ACCESS_KEY_ID in your GitHub secrets. Ever. Here's how OIDC trust works and why it's strictly better.

The most common GitHub Actions setup I see in portfolios stores AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as repository secrets. Those are long-lived credentials tied to an IAM user. One breach of your GitHub account — a compromised OAuth token, a compromised third-party Action, a secret accidentally logged in workflow output — and an attacker has permanent AWS access until someone notices and rotates the keys.

OIDC federation eliminates the stored credentials entirely. GitHub Actions assumes an IAM role using a short-lived signed token. When the job ends, the session expires. There are no keys to rotate because there are no keys.

This post covers how the trust relationship works, how the CI and deploy workflows are structured, and how the frontend gets deployed to CloudFront with correct cache headers.

How GitHub Actions OIDC Works

GitHub operates as an OpenID Connect identity provider. When a workflow job runs with the id-token: write permission, GitHub can mint a signed JWT asserting the identity of the running job:

{
  "sub": "repo:joshblair/sift:ref:refs/heads/main",
  "aud": "sts.amazonaws.com",
  "iss": "https://token.actions.githubusercontent.com",
  "repository": "joshblair/sift",
  "ref": "refs/heads/main"
}

AWS STS accepts this JWT via AssumeRoleWithWebIdentity and issues a short-lived role session — credentials that expire when the job ends, typically within an hour. The exchange only works if AWS has been told to trust GitHub's OIDC provider and the role's trust policy permits the specific repository making the request.

Setting Up the Trust (Once Per Account)

scripts/bootstrap.sh runs once to wire this up. It does three things:

1. Creates the GitHub OIDC provider in IAM:

aws iam create-open-id-connect-provider \
  --url "https://token.actions.githubusercontent.com" \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "6938fd4d98bab03faadb97b34396831e3780aea1"

This tells AWS to trust JWTs signed by GitHub's OIDC endpoint. It's a one-time setup for the AWS account — not per-repo.

2. Creates the IAM deploy role with a scoped trust policy:

{
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
      },
      "StringLike": {
        "token.actions.githubusercontent.com:sub": "repo:joshblair/sift:*"
      }
    }
  }]
}

The StringLike condition on sub limits trust to jobs running from the joshblair/sift repository. The wildcard * allows both branch pushes and pull request checks. For a production setup, you'd tighten this to repo:org/repo:ref:refs/heads/main to prevent deploy jobs from running on feature branches.

3. Prints the values to add as GitHub Actions variables:

Bootstrap complete. Add these as GitHub Actions variables in your repo settings:

  AWS_REGION       = us-west-2
  SAM_BUCKET       = sift-sam-123456789-us-west-2
  DEPLOY_ROLE_ARN  = arn:aws:iam::123456789:role/sift-github-actions-deploy

These go in the repository's Variables (not Secrets) — they're not sensitive values. Cognito configuration (VITE_USER_POOL_ID, VITE_USER_POOL_CLIENT_ID, VITE_COGNITO_DOMAIN) is also stored as variables.

In the Workflow

With the provider and role in place, a single step handles authentication in every job that needs AWS access:

permissions:
  id-token: write   # allows the job to request an OIDC token
  contents: read

- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
    aws-region:     ${{ vars.AWS_REGION }}

After this step, the job has temporary AWS credentials in its environment — the same AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN that the AWS CLI and SDKs look for, but populated automatically for the duration of the job.

CI: Three Parallel Jobs on Every Pull Request

ci.yml triggers on pull requests to main. Three jobs run in parallel — each covers a different part of the stack.

.NET Build and Test

- name: Restore
  run: dotnet restore
  working-directory: backend
- name: Build
  run: dotnet build --no-restore --configuration Release
- name: Test
  run: dotnet test --no-build --configuration Release --logger "console;verbosity=normal"

Standard dotnet pipeline. The --no-restore and --no-build flags avoid redundant work between steps. Tests run against unit test doubles — no database, no Bedrock — so they complete in a few seconds with no external dependencies.

Python Pipeline Tests

The six pipeline Lambda functions live in separate directories under backend/pipeline/. Each has its own tests/ subdirectory. The shared utilities (database connection, Bedrock client) live in a Lambda layer at backend/pipeline/layers/shared/python/.

In the Lambda execution environment, that layer is mounted at a path Python automatically searches. In CI there's no layer mounting — so the path is added to PYTHONPATH instead:

- name: Add shared layer to PYTHONPATH
  run: echo "PYTHONPATH=$PYTHONPATH:$GITHUB_WORKSPACE/backend/pipeline/layers/shared/python" >> $GITHUB_ENV

Writing to $GITHUB_ENV makes the variable available to all subsequent steps in the job — not just the current shell. This is the correct approach; export would only persist for the current run block.

The test suites then run one per handler:

- name: pytest — chunk (no AWS deps)
  run: pytest backend/pipeline/chunk/tests/ -v
- name: pytest — extract
  run: pytest backend/pipeline/extract/tests/ -v
- name: pytest — embed
  run: pytest backend/pipeline/embed/tests/ -v
- name: pytest — metadata
  run: pytest backend/pipeline/metadata/tests/ -v

The chunker tests are noted as having no AWS dependencies — that handler is pure Python stdlib, so no mocking needed. The others mock boto3 calls to Bedrock and S3.

TypeScript Check, Lint, and Build

- name: TypeScript check
  run: npx tsc --noEmit
- name: ESLint
  run: npx eslint src --max-warnings 0
- name: Build (smoke test)
  run: npm run build
  env:
    VITE_API_URL: https://placeholder.execute-api.us-west-2.amazonaws.com/dev
    VITE_USER_POOL_ID: us-west-2_PLACEHOLDER
    VITE_USER_POOL_CLIENT_ID: placeholder
    VITE_COGNITO_DOMAIN: placeholder.auth.us-west-2.amazoncognito.com

TypeScript checking and ESLint catch type errors and style issues. The vite build step is a smoke test: TypeScript's tsc --noEmit checks types but doesn't bundle. Vite's bundler can still fail on import cycles, missing environment variable references, or tree-shaking edge cases that tsc doesn't see. Placeholder values satisfy Vite's env var requirements without needing real infrastructure.

--max-warnings 0 on ESLint means warnings are treated as errors — a warning that gets committed and ignored accumulates into noise. Zero tolerance keeps the lint output meaningful.

Deploy: Two Sequential Jobs on Every Push to Main

deploy.yml triggers on pushes to main. It has two jobs: deploy-backend builds and deploys the infrastructure stacks, then deploy-frontend builds the React app with the real API URL and syncs it to S3.

Job 1: SAM Build and Deploy

After authenticating with OIDC, the job builds the Lambda functions:

- name: SAM build
  run: sam build --template-file infrastructure/template.yaml

The build step does the work of compiling or packaging each Lambda function according to the Metadata.BuildMethod in the template. The .NET functions use a Makefile target that runs dotnet publish. The Python pipeline functions are packaged with their dependencies. Because all functions target x86_64 — matching the ubuntu-latest runner — no cross-compilation or Docker containerization is needed.

The deploy step reads from the build output, not the source template:

- name: SAM deploy — main stack
  run: |
    sam deploy \
      --no-confirm-changeset \
      --no-fail-on-empty-changeset \
      --s3-bucket ${{ vars.SAM_BUCKET }} \
      --s3-prefix sift-main \
      --stack-name sift-dev \
      --parameter-overrides Env=dev SamBucket=${{ vars.SAM_BUCKET }} \
      --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

Notice there's no --template-file flag here. When sam deploy runs without specifying a template, it reads from .aws-sam/build/template.yaml — the processed template that references the compiled Lambda artifacts from the build step. Passing --template-file infrastructure/template.yaml would bypass the build and re-package raw source, which would break the .NET functions.

--no-fail-on-empty-changeset means the deploy step succeeds even if nothing changed. Without it, a push that only modifies the frontend would fail the backend deploy job with "No changes to deploy."

The frontend hosting stack is a plain CloudFormation template (no SAM transforms), deployed separately:

- name: Deploy frontend hosting stack
  run: |
    aws cloudformation deploy \
      --template-file infrastructure/template-frontend.yaml \
      --stack-name sift-frontend-dev \
      --parameter-overrides Env=dev \
      --no-fail-on-empty-changeset

The job then captures the stack outputs — API URL, S3 bucket name, CloudFront distribution ID — and writes them to $GITHUB_OUTPUT so the next job can read them:

- name: Capture stack outputs
  id: outputs
  run: |
    API_URL=$(aws cloudformation describe-stacks \
      --stack-name sift-dev \
      --query "Stacks[0].Outputs[?OutputKey=='ApiUrl'].OutputValue" \
      --output text)
    echo "api-url=$API_URL" >> $GITHUB_OUTPUT
    # ... bucket name and CF distribution ID

Job 2: Frontend Build and Sync

deploy-frontend declares needs: deploy-backend, which both enforces ordering and makes the first job's outputs available as needs.deploy-backend.outputs.*.

- name: Build
  run: npm run build
  env:
    VITE_API_URL:             ${{ needs.deploy-backend.outputs.api-url }}
    VITE_USER_POOL_ID:        ${{ vars.VITE_USER_POOL_ID }}
    VITE_USER_POOL_CLIENT_ID: ${{ vars.VITE_USER_POOL_CLIENT_ID }}
    VITE_COGNITO_DOMAIN:      ${{ vars.VITE_COGNITO_DOMAIN }}

VITE_API_URL is the only value that comes from the previous job's runtime output — it's only known after the SAM stack deploys. Everything else is static configuration stored as repository variables.

The S3 sync uses split cache headers:

- name: Sync to S3
  run: |
    aws s3 sync dist/ s3://${{ needs.deploy-backend.outputs.frontend-bucket }} \
      --delete \
      --cache-control "public,max-age=31536000,immutable" \
      --exclude "index.html"
    aws s3 cp dist/index.html s3://$BUCKET/index.html \
      --cache-control "no-cache,no-store,must-revalidate"

This is the standard SPA cache strategy. Vite includes a content hash in every asset filename — main-Dz9a8bK2.js, vendor-x4jKLmY8.css. These filenames change when the content changes. The browser can safely cache them for a year (max-age=31536000,immutable); if the file changes, it gets a new URL.

index.html doesn't have a hash in its name — it's always index.html. It contains <script src="./assets/main-Dz9a8bK2.js">, pointing to the current hashed filenames. If index.html is cached, the browser never fetches the new asset filenames after a deploy. no-cache,no-store,must-revalidate forces the browser to revalidate index.html on every navigation — it fetches fresh, reads the new asset filenames, and the rest loads from cache.

Finally, the CloudFront edge caches are invalidated:

- name: Invalidate CloudFront
  run: |
    aws cloudfront create-invalidation \
      --distribution-id ${{ needs.deploy-backend.outputs.cloudfront-id }} \
      --paths "/*"

Without this, CloudFront would serve the cached previous version of index.html from edge locations for up to 24 hours — undermining the no-cache header set on the origin.

CloudFront + S3 Hosting

template-frontend.yaml configures CloudFront to serve a private S3 bucket using Origin Access Control:

FrontendBucket:
  Type: AWS::S3::Bucket
  Properties:
    PublicAccessBlockConfiguration:
      BlockPublicAcls:       true
      IgnorePublicAcls:      true
      BlockPublicPolicy:     true
      RestrictPublicBuckets: true

The bucket has all public access blocked. The only way to read objects is through CloudFront.

Origin Access Control (OAC) replaces the older Origin Access Identity (OAI) pattern. OAC uses SigV4 request signing rather than a special IAM principal:

OriginAccessControl:
  Type: AWS::CloudFront::OriginAccessControl
  Properties:
    OriginAccessControlConfig:
      OriginAccessControlOriginType: s3
      SigningBehavior:               always
      SigningProtocol:               sigv4

The bucket policy grants s3:GetObject to CloudFront, scoped to this specific distribution's ARN:

Condition:
  StringEquals:
    AWS:SourceArn: !Sub arn:aws:cloudfront::${AWS::AccountId}:distribution/${CloudFrontDistribution}

The AWS:SourceArn condition means even if someone obtained CloudFront's service principal, they couldn't use it to access this bucket from a different distribution. The permission is tied to the specific CloudFront resource, not just the service.

The distribution handles the SPA routing requirement with custom error responses:

CustomErrorResponses:
  - ErrorCode: 403
    ResponseCode: 200
    ResponsePagePath: /index.html
  - ErrorCode: 404
    ResponseCode: 200
    ResponsePagePath: /index.html

When a user bookmarks app.example.com/documents and navigates directly to it, S3 returns a 403 (no object at that key) or 404. Without this configuration, the user sees an XML error response. With it, CloudFront intercepts that error and serves index.html instead — React Router then handles the /documents path client-side. The ErrorCachingMinTTL: 0 on each rule prevents CloudFront from caching the error responses themselves.

The Result

The full pipeline, end to end:

Developer opens a pull request → CI runs three parallel jobs (45–90 seconds)
Merge to main → Deploy job builds and deploys all infrastructure stacks
Frontend build runs with the real API URL from stack outputs
aws s3 sync with correct cache headers, CloudFront invalidation

The only AWS credentials that exist are the temporary role session credentials inside the running job. There's no AWS_ACCESS_KEY_ID in repository secrets, no IAM user to audit, and no credential rotation to schedule. The IAM role trust policy limits which repos can assume it, and the role itself is scoped to exactly the permissions needed to deploy Sift — no more.

The Complete Series

That's all six parts:

Part	Topic
1	Architecture overview — service choices and cost breakdown
2	Multi-tenant auth — Cognito JWT, API Gateway validation, Postgres RLS
3	Step Functions pipeline — state machine, Map state, Express Workflows
4	RAG and vector search — pgvector, Titan Embed v2, citations
5	React frontend — Amplify auth, presigned upload, React Query polling
6	CI/CD — OIDC federation, SAM build/deploy, CloudFront cache strategy

The live demo is at sift.bonefishsoftware.com. The code is at github.com/joshblair/sift.

Part of the Sift series: building a production-ready multi-tenant RAG platform on AWS.

Building the React Frontend: Document Library and Chat UI (Part 5)

Josh Blair — Thu, 21 May 2026 02:03:48 +0000

Building the React Frontend: Document Library and Chat UI (Part 5)

React Query's refetchInterval turns a polling requirement into a one-liner. Here's the whole frontend, explained.

The frontend is where the demo either lands or doesn't. Interviewers will click around. Uploads need to feel instant, the pipeline status needs to update without a refresh, and the chat responses need citations that prove the AI actually read the documents — not just hallucinated plausible-sounding text.

This post covers how each of those things works, starting from auth and working through upload, status polling, and the chat UI.

Tech Choices

A quick inventory before diving in:

Vite — faster dev server than Create React App, native ES module HMR, straightforward to configure
React 18 + TypeScript — strict mode, no any, every API response typed at the boundary
Tailwind v4 — utility-first, no separate CSS files to maintain
React Query (@tanstack/react-query) — server state management, automatic cache invalidation, and the polling behavior discussed below
AWS Amplify UI — the Authenticator component handles the full Cognito sign-in/sign-up flow without custom UI
Axios — request interceptor injects the Bearer token on every outbound request

Auth: Amplify and the Token Interceptor

configureAmplify() runs once at module load before anything else renders:

export function configureAmplify() {
  Amplify.configure({
    Auth: {
      Cognito: {
        userPoolId:       import.meta.env.VITE_USER_POOL_ID,
        userPoolClientId: import.meta.env.VITE_USER_POOL_CLIENT_ID,
        loginWith: {
          oauth: {
            domain:          import.meta.env.VITE_COGNITO_DOMAIN,
            scopes:          ['email', 'openid', 'profile'],
            redirectSignIn:  [window.location.origin],
            redirectSignOut: [window.location.origin],
            responseType:    'code',
          },
        },
      },
    },
  })
}

All values come from VITE_ environment variables, injected at build time from .env.local. The responseType: 'code' uses the PKCE authorization code flow — the correct flow for single-page apps, which can't keep a client secret.

The getAccessToken function returns the token that every API request carries:

export async function getAccessToken(): Promise<string> {
  const session = await fetchAuthSession()
  const token   = session.tokens?.idToken?.toString()
  if (!token) throw new Error('No ID token')
  return token
}

Notice it's returning the ID token, not the access token. This is intentional and slightly non-obvious. Cognito's Pre-Token Generation V1 trigger — which injects the tenantId custom claim (covered in Part 2) — only applies to the ID token. The access token doesn't get custom claims from V1 triggers. Since API Gateway validates the tenantId claim from the token, the ID token is what needs to be sent.

Amplify handles token refresh transparently — fetchAuthSession() returns a fresh token if the current one is near expiry, with no code required on the caller's side.

The Axios client wires this up with a request interceptor:

const api = axios.create({ baseURL: import.meta.env.VITE_API_URL })

api.interceptors.request.use(async (config) => {
  const token = await getAccessToken()
  config.headers.Authorization = `Bearer ${token}`
  return config
})

Every API call goes through this interceptor, so no individual function or component ever has to think about auth headers.

App Initialization

App.tsx wraps everything in the Amplify Authenticator component:

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Authenticator>
        {() => <AppRoutes />}
      </Authenticator>
    </QueryClientProvider>
  )
}

Authenticator renders the Cognito Hosted UI for unauthenticated users — sign-in, sign-up, email verification — and calls its render prop only after the user is authenticated. The entire application sits inside that render prop. No route guards, no redirect logic, no token-checking in individual components.

The first thing AppRoutes does on mount is sync the user record:

function AppRoutes() {
  const [synced, setSynced] = useState(false)

  useEffect(() => {
    tenantApi.sync().finally(() => setSynced(true))
  }, [])

  if (!synced) return <Spinner />
  // ... routes
}

POST /tenants/me/sync upserts the user row in the database using the JWT's sub and email claims. This handles first-time logins (where no user row exists yet) and keeps the email current if it changes in Cognito. The app doesn't render routes until this completes — a brief spinner rather than a flash of potentially stale state.

Document Upload: The Two-Step Flow

The upload flow has two distinct steps, and understanding why matters for the architecture.

Why not upload through API Gateway? API Gateway HTTP APIs have a 10MB payload limit. A single PDF can easily exceed that. The solution is to bypass API Gateway entirely for the file content and upload directly to S3.

Step 1: The client calls POST /documents/upload-url with the filename and file type. The Lambda creates the database record (status pending) and returns a presigned S3 PUT URL along with the new document ID.

Step 2: The client PUTs the file directly to the presigned URL — which goes straight to S3, bypassing API Gateway.

The useUploadDocument hook handles both steps:

export function useUploadDocument() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (file: File) => {
      const ext = file.name.split('.').pop()?.toLowerCase() ?? 'txt'
      const { uploadUrl, documentId } = await documentsApi.getUploadUrl(file.name, ext)

      // PUT directly to S3 presigned URL — bypasses API Gateway
      await axios.put(uploadUrl, file, {
        headers: { 'Content-Type': file.type },
      })

      return documentId
    },
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['documents'] }),
  })
}

The second axios.put uses the base axios instance, not the api client with the auth interceptor. The presigned URL already has credentials embedded — adding an Authorization header would cause S3 to reject the request.

onSuccess invalidates the documents query, which triggers an immediate refetch. The new document appears in the list as pending before the pipeline has even started.

Why create the DB record before the upload? The S3 key is {tenantId}/{documentId}/{filename}. Creating the database record first gives us the document ID to construct the key. When the upload completes and EventBridge fires, the Step Functions pipeline starts immediately — and the document row it needs to update already exists.

The dropzone handles drag-and-drop and file input with consistent behavior:

const handleFile = useCallback(async (file: File) => {
  const ext = '.' + file.name.split('.').pop()?.toLowerCase()
  if (!ACCEPTED_EXT.includes(ext)) {
    setError(`Unsupported file type. Accepted: ${ACCEPTED_EXT.join(', ')}`)
    return
  }
  setUploading(true)
  try {
    await onUpload(file)
  } catch {
    setError('Upload failed. Please try again.')
  } finally {
    setUploading(false)
  }
}, [onUpload])

File type validation happens client-side before any network request is made. During upload the dropzone is visually disabled (pointer-events-none) and shows a spinner — the user can't double-submit.

Status Polling: React Query's `refetchInterval`

Once a document is uploaded, the pipeline runs asynchronously. The frontend needs to show status updates — pending → processing → ready — without requiring a manual refresh.

React Query's refetchInterval option accepts a callback that can return a number (milliseconds) or false:

export function useDocuments() {
  return useQuery<Document[]>({
    queryKey:    ['documents'],
    queryFn:     documentsApi.list,
    refetchInterval: (query) => {
      const docs = query.state.data ?? []
      return docs.some(d => d.status === 'pending' || d.status === 'processing')
        ? 3000 : false
    },
  })
}

While any document in the list has status pending or processing, the hook polls every 3 seconds. When all documents are ready or failed, it stops. No WebSocket infrastructure, no long-polling, no useEffect with setInterval.

The DocumentCard component drives the status display:

const statusConfig = {
  pending:    { label: 'Pending',    variant: 'secondary',    icon: Clock },
  processing: { label: 'Processing', variant: 'warning',      icon: Loader2 },
  ready:      { label: 'Ready',      variant: 'success',      icon: CheckCircle2 },
  failed:     { label: 'Failed',     variant: 'destructive',  icon: XCircle },
} as const

The processing badge uses animate-spin on its icon — a CSS animation that costs nothing and makes the in-progress state visually obvious. Once processing completes, the card fills in the summary paragraph and topic chips from the metadata extraction step. On failure, the error message from the mark_failed Lambda appears inline in a red callout:

{doc.status === 'failed' && doc.errorMessage && (
  <p className="mt-2 text-xs text-red-600 bg-red-50 rounded p-2">{doc.errorMessage}</p>
)}

Chat: Local State in `useChat`

The chat interface doesn't use React Query — there's no server cache to manage, just a thread of messages that grows as the user asks questions.

useChat is a custom hook that manages the message array, loading state, and error state:

export function useChat() {
  const [messages, setMessages]   = useState<Message[]>([])
  const [isLoading, setIsLoading] = useState(false)
  const [error, setError]         = useState<string | null>(null)

  const sendMessage = useCallback(async (question: string) => {
    setError(null)
    setMessages(prev => [...prev, { role: 'user', content: question }])
    setIsLoading(true)

    try {
      const response = await chatApi.query(question)
      setMessages(prev => [
        ...prev,
        { role: 'assistant', content: response.answer, citations: response.citations },
      ])
    } catch {
      setError('Failed to get a response. Please try again.')
      setMessages(prev => prev.slice(0, -1))  // remove the user message on failure
    } finally {
      setIsLoading(false)
    }
  }, [])

  return { messages, isLoading, error, sendMessage, clearMessages }
}

The user's message is added to the thread immediately — before the API call completes — so the UI feels responsive. If the call fails, prev.slice(0, -1) removes it and shows an error, leaving the thread in the state it was before the failed send. This avoids the awkward state of showing a user message with no corresponding response.

The ChatPage scrolls to the bottom on every new message:

const bottomRef = useRef<HTMLDivElement>(null)

useEffect(() => {
  bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
}, [messages, isLoading])

The ref sits on a <div> after the last message. scrollIntoView fires both when a new message arrives and when isLoading becomes true (so the "Thinking…" indicator is visible). The input is disabled during loading — no queuing up a second question while the first is in flight.

Rendering Citations

ChatMessage handles both user and assistant messages. User messages are right-aligned in a blue bubble; assistant messages are left-aligned in grey. Citations appear as cards below the assistant's response:

{message.citations && message.citations.length > 0 && (
  <div className="space-y-1">
    <p className="text-xs text-slate-400 px-1">Sources:</p>
    {message.citations.map((c, i) => (
      <div key={i} className="rounded-md border border-slate-200 bg-white px-3 py-2 text-xs text-slate-600">
        <span className="font-medium text-blue-600">[{i + 1}]</span>{' '}
        <span className="font-medium">{c.filename}</span>
        <span className="text-slate-400"> · chunk {c.chunkIndex}</span>
        <p className="mt-1 text-slate-500 line-clamp-2 italic">"{c.excerpt}"</p>
      </div>
    ))}
  </div>
)}

The [1], [2] numbers here correspond to the same numbers Claude used inline in the answer text. The user can see "Revenue grew 18% in Q3 [1]" and then immediately read the exact sentence from the PDF that grounded that claim. line-clamp-2 keeps the excerpt compact — two lines of truncated italic text, enough to confirm the source without overflowing the card.

What's Missing for Production

The demo is complete enough to show in an interview, but a production deployment would need a few more things:

Error boundaries. A thrown exception anywhere in the component tree currently crashes the whole app. React error boundaries would catch rendering errors and show a recovery UI instead.

Pagination. The document list fetches all documents in a single request. At hundreds of documents, this becomes a performance problem — both for the API query and for rendering.

File size validation. The dropzone validates file type but not file size. A 500MB PDF will pass client-side validation and fail at the S3 put with an unhelpful error. A size check before requesting the upload URL is an easy addition.

Streaming chat responses. The chat waits for the full response before displaying anything. For longer answers this is a noticeable pause. Lambda Function URLs support HTTP response streaming, which would allow tokens to appear as they're generated. API Gateway doesn't support streaming, so this would require routing the /chat endpoint through a Function URL instead.

E2E tests. There are no Playwright or Cypress tests. For a portfolio project that's a reasonable trade-off; for a production app, automated browser tests on the upload and chat flows would be essential.

What's Next

Part 6 covers the CI/CD pipeline — GitHub Actions with OIDC federation, how the deploy workflow deploys five nested SAM stacks in dependency order, and why there are zero stored AWS credentials anywhere in the repository.

The code for this post:

frontend/src/auth/cognito.ts — Amplify config, ID token vs access token
frontend/src/api/client.ts — Axios client, auth interceptor, typed API surface
frontend/src/hooks/useDocuments.ts — React Query with adaptive refetchInterval
frontend/src/hooks/useUploadDocument.ts — two-step upload mutation
frontend/src/components/UploadDropzone.tsx — drag-and-drop with validation
frontend/src/components/DocumentCard.tsx — status badges, summary, error display
frontend/src/hooks/useChat.ts — local chat state, optimistic message add
frontend/src/pages/Chat.tsx — scroll behavior, loading indicator
frontend/src/components/ChatMessage.tsx — citation cards

Part of the Sift series: building a production-ready multi-tenant RAG platform on AWS.

RAG and Vector Search with pgvector and Amazon Bedrock (Part 4)

Josh Blair — Thu, 21 May 2026 02:02:41 +0000

RAG and Vector Search with pgvector and Amazon Bedrock (Part 4)

How to build retrieval-augmented generation that actually cites its sources — without a vector database subscription.

Most RAG tutorials reach for Pinecone, Chroma, or Weaviate as the vector store. Those are all fine services, but they add another cost line, another auth boundary, and a dependency you don't control. If you're already running Postgres — and for multi-tenant SaaS, you should be — the pgvector extension gives you vector similarity search inside your existing database, protected by the same Row-Level Security policies you already have.

This post covers the full query path in Sift: how a user's question becomes a vector, how pgvector finds the closest document chunks, and how Claude turns those chunks into a cited answer.

What RAG Actually Does

The core idea is simple. At query time:

Embed the user's question with the same model used to embed the documents
Find the document chunks whose embeddings are closest to the question embedding
Send those chunks to an LLM, tell it to answer the question using only that context
Return the answer with numbered citations linking back to the source text

That's it. The sophistication is in the details of each step.

Embeddings with Bedrock Titan Embed v2

Both the pipeline (at ingest time) and the chat handler (at query time) use the same embedding model: amazon.titan-embed-text-v2:0. Using the same model for both sides of the search is a hard requirement — embeddings from different models live in incompatible vector spaces.

The Python implementation in the pipeline's shared module:

EMBED_MODEL_ID = "amazon.titan-embed-text-v2:0"

def embed(text: str) -> list[float]:
    payload = json.dumps({"inputText": text, "dimensions": 1024, "normalize": True})
    response = _get_client().invoke_model(
        modelId=EMBED_MODEL_ID,
        contentType="application/json",
        accept="application/json",
        body=payload,
    )
    return json.loads(response["body"].read())["embedding"]

Two parameters worth noting.

dimensions: 1024 — Titan Embed v2 supports multiple output sizes (256, 512, or 1024 dimensions). Fewer dimensions mean smaller storage and faster search at the cost of some precision. 1024 is the maximum and gives the best retrieval quality; for a demo at this scale, there's no reason to trade it away.

normalize: True — this asks Bedrock to return a unit-length vector. Normalized embeddings mean cosine similarity is equivalent to dot product. pgvector can compute dot products slightly faster than cosine distance, and it simplifies reasoning about scores. More importantly, it means you don't have to normalize manually — if you skip it and your embeddings have different magnitudes, your similarity scores will be skewed by vector length rather than semantic meaning.

Authentication is IAM. The Lambda execution role has bedrock:InvokeModel permission via its attached policy — no API keys, no secrets to rotate.

Schema: Storing Vectors in Postgres

The document_chunks table has a vector(1024) column — the native pgvector type:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE document_chunks (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  document_id   UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
  tenant_id     UUID NOT NULL,
  chunk_index   INT NOT NULL,
  content       TEXT NOT NULL,
  embedding     vector(1024),
  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

The (1024) in the column type is a hard constraint — Postgres will reject inserts with a vector of any other dimension. That's a useful guardrail: if the embedding model changes and the dimension changes with it, the insert fails loudly rather than silently storing mismatched vectors.

The IVFFlat Index

An exact nearest-neighbor search scans every vector in the table and computes distance to the query vector. For a small dataset that's fine. At tens of millions of chunks it becomes expensive.

IVFFlat (Inverted File Flat) is an approximate nearest-neighbor index. It clusters the vectors into groups (called "lists") at index build time. At query time, it only searches the most promising lists rather than the entire table:

CREATE INDEX ON document_chunks
  USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

vector_cosine_ops tells the index to use cosine distance as its metric, which matches the <=> operator in the query. The lists = 100 parameter controls how many clusters to build — the pgvector docs recommend roughly sqrt(rows) as a starting point.

The IVFFlat gotcha: the index needs data to exist when it's built. An IVFFlat index built on an empty table is useless. In Sift, the initial migration creates the index after the schema is established, and the seed data runs in the same migration. For a production system where the table grows continuously, HNSW is a better choice — it maintains good search quality as data is inserted without needing a rebuild.

Inserting Vectors from Python

The psycopg2 driver doesn't natively understand the pgvector type. Rather than adding the pgvector Python package (which requires a compiled extension and adds deploy complexity), the pipeline constructs a Postgres vector literal as a plain string and casts it:

vector_literal = "[" + ",".join(str(v) for v in embedding) + "]"
cur.execute(
    """
    INSERT INTO document_chunks
        (document_id, tenant_id, chunk_index, content, embedding)
    VALUES (%s, %s, %s, %s, %s::vector)
    ON CONFLICT DO NOTHING
    """,
    (document_id, tenant_id, chunk_index, content, vector_literal),
)

The ::vector cast in the SQL converts the string to the native vector type at insert time. This works on any Postgres driver, any Lambda architecture (x86 or ARM), without native extensions. The ON CONFLICT DO NOTHING handles at-least-once delivery from the Step Functions Map state — if an EmbedChunk Lambda retries, it won't create duplicate chunks.

Similarity Search

At query time, the C# ChatService embeds the user's question and runs the search. The same vector literal approach works from the .NET side:

private async Task<List<ChunkResult>> SearchChunksAsync(Guid tenantId, float[] embedding)
{
    var vectorLiteral = $"[{string.Join(",", embedding)}]";

    await using var conn = await db.CreateAsync();
    await TenantContext.SetAsync(conn, tenantId);

    await using var cmd = conn.CreateCommand();
    cmd.CommandText = """
        SELECT dc.id, dc.document_id, dc.chunk_index, dc.content,
               d.filename,
               dc.embedding <=> $1::vector AS distance
        FROM document_chunks dc
        JOIN documents d ON d.id = dc.document_id
        ORDER BY distance
        LIMIT $2
        """;
    cmd.Parameters.AddWithValue(NpgsqlTypes.NpgsqlDbType.Text, vectorLiteral);
    cmd.Parameters.AddWithValue(TopK);
    // ...
}

The <=> operator is pgvector's cosine distance operator. It returns values between 0 and 2 — 0 means identical vectors, 2 means pointing in opposite directions. Ordering by ascending distance gives the most semantically similar chunks first.

Notice that TenantContext.SetAsync runs before the query. This sets the Postgres session variable that the RLS policy reads. The similarity search is automatically tenant-scoped — there's no WHERE tenant_id = $3 in this query, but Postgres applies the policy invisibly. A user from Acme Corp can only find chunks from their own documents, even though the <=> distance calculation runs across an index that spans all tenants' data.

Why 8 chunks? TopK = 8 is a constant in ChatService.cs. Eight chunks at ~512 tokens each is roughly 4,000 tokens of context — enough to answer most questions without overwhelming the model or the latency budget. The tradeoff is real: more chunks means higher recall (better chance the right information is included) at the cost of slower generation and more noise in the prompt. Eight is a practical default, not a theoretically derived optimum.

The RAG Prompt

With the top 8 chunks retrieved, the service builds the prompt:

var context = string.Join("\n\n", chunks.Select((c, i) =>
    $"[{i + 1}] From \"{c.Filename}\" (chunk {c.ChunkIndex}):\n{c.Content}"));

var systemPrompt = """
    You are a helpful document assistant. Answer the user's question using only
    the provided document excerpts. Cite your sources using [1], [2], etc.
    If the answer cannot be found in the excerpts, say so clearly.
    """;

var userMessage = $"Document excerpts:\n{context}\n\nQuestion: {question}";

Each chunk gets a numbered label [1], [2], etc., with the filename and chunk index. The system prompt instructs Claude to use those same numbers as inline citations. The model sees something like:

[1] From "Q3_Report.pdf" (chunk 4):
Revenue for Q3 was $4.2M, up 18% year-over-year driven by enterprise contracts...

[2] From "Q3_Report.pdf" (chunk 5):
The increase was concentrated in the healthcare vertical, which grew 31%...

Question: What drove the Q3 revenue increase?

And responds with an answer that cites [1] and [2] inline, so the reader knows exactly which passage each claim came from.

The model for this step is Claude Haiku 4.5 — fast and cheap for a task that's mostly about summarizing and organizing provided context rather than knowledge retrieval or reasoning. The max_tokens: 1024 cap keeps response times predictable.

Citations as First-Class Data

The response doesn't just return the answer string. The ChatResponse model carries a parallel citations array:

public class ChatResponse
{
    public string             Answer    { get; set; } = "";
    public List<ChatCitation> Citations { get; set; } = [];
}

public class ChatCitation
{
    public Guid   DocumentId { get; set; }
    public string Filename   { get; set; } = "";
    public string Excerpt    { get; set; } = "";
    public int    ChunkIndex { get; set; }
}

Each citation includes the first 200 characters of the chunk's content. The React frontend renders them as expandable cards below the answer — the user can click [1] to see the exact excerpt that grounded that part of the response, with the source document and chunk position shown.

This matters for trust. A RAG system that returns confident-sounding answers with no way to verify them is worse than one that shows its work.

Limitations and What Production Would Change

The implementation above works well at demo scale. A few things I'd change for a real production deployment:

Chunking strategy. The sliding-window chunker in Part 3 splits on character count, not semantic boundaries. A 512-token window can cut off mid-sentence, mid-table, or mid-list. Better approaches: a recursive sentence splitter that tries to preserve paragraph boundaries, or a semantic chunker that uses an embedding model to detect topic shifts. The trade-off is complexity and ingest latency.

Index type. IVFFlat is good for static or slowly-growing datasets, but it degrades as data is inserted after the index is built — you need periodic reindexing. HNSW (Hierarchical Navigable Small World) maintains search quality dynamically as data grows, at the cost of higher memory usage. For a production system with continuous ingestion, HNSW is the right default.

Reranking. Vector similarity is a good first filter but not a perfect one. A cross-encoder reranker — a small model that takes (question, chunk) pairs and scores their relevance directly — can significantly improve the precision of the final context window. The typical pattern is: retrieve top 20–50 chunks with vector search, rerank with a cross-encoder, pass the top 8 to the LLM.

Streaming. The current API waits for Claude to finish generating the full answer before returning it. For longer answers that can take 3–5 seconds, that's a noticeable pause. Lambda Function URLs support response streaming, which would let the frontend display tokens as they arrive. API Gateway HTTP APIs don't support streaming, so switching to Function URLs for the chat endpoint would be the path there.

What's Next

Part 5 covers the React frontend: how the upload flow works, the polling pattern that drives the document status cards, and how Amplify's auth integration wires up the Cognito token flow.

The code for this post:

backend/shared/bedrock.py — embedding call, normalize flag
migrations/001_initial_schema.sql — vector(1024) column, IVFFlat index
backend/pipeline/embed/embed_handler.py — vector literal insert, ON CONFLICT DO NOTHING
backend/src/Sift.Api/Services/ChatService.cs — full query path: embed → search → generate
backend/src/Sift.Api/Models/Chat.cs — response shape with citations

Part of the Sift series: building a production-ready multi-tenant RAG platform on AWS.

Serverless Document Pipelines with AWS Step Functions (Part 3)

Josh Blair — Thu, 21 May 2026 02:02:23 +0000

Serverless Document Pipelines with AWS Step Functions (Part 3)

Why I chose Step Functions over SQS + Lambda — and what the execution history is actually worth.

Every async processing pipeline starts the same way: a file lands somewhere, something needs to happen to it in multiple stages, and you need it to be reliable. The obvious architecture is SQS queues chained between Lambda functions. It's battle-tested, it scales, and you've probably built it before.

I deliberately chose not to use it here.

Sift's document processing pipeline has six stages: extract text, chunk it, generate embeddings in parallel, extract metadata with an LLM, and mark the document ready (or failed). I implemented all of it as a Step Functions Express Workflow. This post covers why, how the state machine is structured, and what the Map state for parallel embedding actually does.

The Trigger: S3 → EventBridge → Step Functions

When a user uploads a document, the browser sends it directly to S3 via a presigned URL. The API never sees the file content — it just issues the URL and records the pending document in the database. From there, the pipeline starts automatically.

The trigger chain has two hops.

Hop 1: S3 to EventBridge. The uploads bucket has EventBridge notifications enabled:

UploadsBucket:
  Type: AWS::S3::Bucket
  Properties:
    NotificationConfiguration:
      EventBridgeConfiguration:
        EventBridgeEnabled: true

That one flag makes the bucket publish Object Created events to the default EventBridge bus automatically, for every object upload. No SNS topic, no S3 notification configuration specifying ARNs.

Hop 2: EventBridge to Step Functions. An EventBridge rule matches those events and triggers the state machine:

S3UploadRule:
  Type: AWS::Events::Rule
  Properties:
    EventPattern:
      source: [aws.s3]
      detail-type: [Object Created]
      detail:
        bucket:
          name: [!Ref UploadsBucket]
    Targets:
      - Id: TriggerPipeline
        Arn: !Ref PipelineStateMachine
        RoleArn: !GetAtt EventBridgeToSfnRole.Arn
        InputTransformer:
          InputPathsMap:
            key:    "$.detail.object.key"
            bucket: "$.detail.bucket.name"
          InputTemplate: '{"s3Key": "[key]", "bucketName": "[bucket]"}'

(EventBridge InputTransformer uses <placeholder> angle-bracket syntax; shown here with brackets to avoid rendering issues.)

The InputTransformer is doing something important: it reshapes the raw S3 event (which has a lot of noise — checksums, ETags, content type) into a clean minimal payload before Step Functions even sees it. The state machine starts with just { s3Key, bucketName }.

Why EventBridge instead of S3 → Lambda directly?

S3 supports direct Lambda triggers. The reason to go through EventBridge anyway is decoupling: the Step Functions ARN isn't embedded in the S3 bucket configuration. If I wanted to add a second consumer — say, a Lambda that indexes the filename for search — I'd add another EventBridge rule target, not modify the S3 bucket. The bucket doesn't know what listens to its events.

The State Machine

The entire pipeline is defined as YAML inside the SAM template. Here's the full structure:

PipelineStateMachine:
  Type: AWS::Serverless::StateMachine
  Properties:
    Name: !Sub sift-pipeline-${Env}
    Type: EXPRESS
    Definition:
      Comment: Sift document ingestion pipeline
      StartAt: ExtractText
      States:
        ExtractText:
          Type: Task
          Resource: !GetAtt ExtractTextFunction.Arn
          Retry:
            - ErrorEquals: [States.TaskFailed]
              IntervalSeconds: 2
              MaxAttempts: 2
          Catch:
            - ErrorEquals: [States.ALL]
              ResultPath: $.error
              Next: MarkFailed
          Next: ChunkText

        ChunkText:
          Type: Task
          Resource: !GetAtt ChunkTextFunction.Arn
          Catch:
            - ErrorEquals: [States.ALL]
              ResultPath: $.error
              Next: MarkFailed
          Next: GenerateEmbeddings

        GenerateEmbeddings:
          Type: Map
          ItemsPath: $.chunks
          Parameters:
            documentId.$: $.documentId
            tenantId.$:   $.tenantId
            index.$:      $$.Map.Item.Value.index
            content.$:    $$.Map.Item.Value.content
          MaxConcurrency: 5
          ResultPath: $.embeddingResults
          Iterator:
            StartAt: EmbedChunk
            States:
              EmbedChunk:
                Type: Task
                Resource: !GetAtt EmbedChunkFunction.Arn
                Retry:
                  - ErrorEquals: [States.TaskFailed]
                    IntervalSeconds: 2
                    MaxAttempts: 3
                End: true
          Catch:
            - ErrorEquals: [States.ALL]
              ResultPath: $.error
              Next: MarkFailed
          Next: ExtractMetadata

        ExtractMetadata:
          Type: Task
          Resource: !GetAtt ExtractMetadataFunction.Arn
          Catch:
            - ErrorEquals: [States.ALL]
              ResultPath: $.error
              Next: MarkFailed
          Next: MarkReady

        MarkReady:
          Type: Task
          Resource: !GetAtt MarkReadyFunction.Arn
          End: true

        MarkFailed:
          Type: Task
          Resource: !GetAtt MarkFailedFunction.Arn
          End: true

Let's walk through each stage.

Stage 1: ExtractText

The first Lambda gets { s3Key, bucketName } and has two jobs: parse the tenant and document IDs from the key, and extract plain text from whatever file type was uploaded.

The S3 key format is {tenantId}/{documentId}/{filename} — the same prefix structure used for tenant isolation in S3 (covered in Part 2). Parsing it is a single split:

parts       = s3_key.split("/", 2)
tenant_id   = parts[0]
document_id = parts[1]
filename    = parts[2]

Text extraction is dispatched on file extension:

ext = filename.rsplit(".", 1)[-1].lower()
if ext == "pdf":
    text, page_count = _extract_pdf(content)
elif ext == "docx":
    text, page_count = _extract_docx(content)
elif ext == "csv":
    text, page_count = _extract_csv(content)
elif ext == "txt":
    text       = content.decode("utf-8", errors="replace")
    page_count = 1
else:
    raise ValueError(f"Unsupported file extension: {ext}")

For PDFs, pdfplumber handles multi-page extraction and tracks the page count. For DOCX, python-docx walks the paragraph list. For CSV, pandas converts the dataframe to a string representation with column names in the header — not ideal for prose, but searchable and embeddable. The page count flows downstream to the documents table and surfaces in the UI.

The Lambda also sets the document status to processing before returning. This tells the frontend's polling logic that the pipeline is running and to keep checking.

The return value passes everything forward:

return {
    **event,
    "tenantId":   tenant_id,
    "documentId": document_id,
    "filename":   filename,
    "text":       text,
    "pageCount":  page_count,
}

Stage 2: ChunkText

This stage splits the extracted text into overlapping windows. The constants:

CHUNK_SIZE    = 512   # tokens, approximated as characters / 4
CHUNK_OVERLAP = 64    # tokens of overlap between adjacent chunks
CHARS_PER_TOKEN = 4

The overlap is the important detail. If a chunk boundary lands in the middle of a sentence that contains the answer to a user's question, a chunk with no overlap might return two fragments — each with half the context — neither of which scores well in similarity search. With 64-token overlap, adjacent chunks share a paragraph's worth of text, so the answer has a better chance of appearing intact in at least one chunk.

The chunker is a sliding-window algorithm that splits on word boundaries:

def _chunk(text: str, size: int, overlap: int) -> list[str]:
    words  = text.split()
    chunks = []
    buf    = []
    buf_len = 0

    for word in words:
        word_len = len(word) + 1
        if buf_len + word_len > size and buf:
            chunks.append(" ".join(buf))
            # Roll back by overlap characters
            rolled, rolled_len = [], 0
            for w in reversed(buf):
                if rolled_len + len(w) + 1 > overlap:
                    break
                rolled.insert(0, w)
                rolled_len += len(w) + 1
            buf     = rolled
            buf_len = rolled_len
        buf.append(word)
        buf_len += word_len

    if buf:
        chunks.append(" ".join(buf))
    return chunks

No external dependencies — pure Python standard library. That means cold starts for this Lambda are essentially free. The output is a list of { index, content } objects that becomes the input to the Map state.

Stage 3: GenerateEmbeddings (The Map State)

This is where Step Functions earns its keep.

Embedding generation is the most time-consuming part of the pipeline. A 20-page PDF might produce 80–100 chunks, each requiring a separate Bedrock API call. Running them sequentially would be slow and wasteful. The Map state fans them out in parallel.

GenerateEmbeddings:
  Type: Map
  ItemsPath: $.chunks
  Parameters:
    documentId.$: $.documentId
    tenantId.$:   $.tenantId
    index.$:      $$.Map.Item.Value.index
    content.$:    $$.Map.Item.Value.content
  MaxConcurrency: 5
  ResultPath: $.embeddingResults

A few things are happening here.

ItemsPath: $.chunks tells Step Functions to iterate over the chunks array from the previous state's output. Each item becomes one Lambda invocation.

The Parameters block reshapes each iteration's input. Without it, each EmbedChunk Lambda invocation would receive the full chunks array — which it doesn't need, and which would exceed Lambda's payload size at any real document length. Instead, $$.Map.Item.Value.index and $$.Map.Item.Value.content pull just the current chunk's fields, and documentId.$ and tenantId.$ carry the parent context. The $$ prefix accesses the Step Functions execution context rather than the state input.

MaxConcurrency: 5 caps the parallelism. Bedrock has per-account request rate limits. With 100 chunks and no concurrency cap, all 100 invocations would fire simultaneously and most would get throttled — producing retries, latency, and noise. Five concurrent invocations keeps throughput high while staying well under the throttle threshold.

ResultPath: $.embeddingResults is subtle. Normally, a Map state replaces the entire state input with its result array. Setting a ResultPath instead merges the results into the existing input under a new key. This is important: ExtractMetadata needs the text, tenantId, documentId, and chunks fields from earlier stages. Without ResultPath, they'd be overwritten.

Each EmbedChunk Lambda invocation does two things:

def handler(event: dict, context) -> dict:
    embedding = embed(content)         # Bedrock Titan Embed v2
    _insert_chunk(document_id, tenant_id, chunk_index, content, embedding)
    return {"documentId": document_id, "tenantId": tenant_id, "index": index, "status": "ok"}

The embed() call hits Titan Embed v2 (1024 dimensions). The insert uses ON CONFLICT DO NOTHING — if the Lambda retries after a partial failure, it won't create duplicate chunks.

The vector gets written as a Postgres vector literal:

vector_literal = "[" + ",".join(str(v) for v in embedding) + "]"
cur.execute(
    "INSERT INTO document_chunks (document_id, tenant_id, chunk_index, content, embedding) "
    "VALUES (%s, %s, %s, %s, %s::vector)",
    (document_id, tenant_id, chunk_index, content, vector_literal),
)

Stage 4: ExtractMetadata

Once all chunks are embedded, a final Bedrock call generates a summary and topic list for the document. This surfaces in the UI as the document card's description.

The Lambda sends only the first 6,000 characters of the document text to stay within Claude Haiku's practical context window for this task:

excerpt = text[:6000].strip()

The prompt asks for structured JSON output:

system = (
    "You are a document analyst. Given document text, return a JSON object "
    "with exactly two keys: "
    '"summary" (one paragraph, max 200 words) and '
    '"topics" (array of 3-7 short topic strings). '
    "Return only the JSON object, no other text."
)

LLMs sometimes wrap their JSON output in markdown code fences even when told not to. The handler strips them before parsing:

FENCE   = "`" * 3  # markdown code fence marker
cleaned = response.strip().removeprefix(FENCE + "json").removeprefix(FENCE).removesuffix(FENCE).strip()
data    = json.loads(cleaned)

The results get written to the documents table. The page count and chunk count from earlier stages are also persisted here — they came through in the state machine data, so no extra database reads needed.

Stages 5 and 6: MarkReady and MarkFailed

These terminal states are simple status updates. MarkReady stamps status = 'ready' and processed_at = NOW(). MarkFailed records the error message (truncated to 1,000 characters) and sets status = 'failed'.

Every non-terminal state has a Catch block that routes all errors to MarkFailed:

Catch:
  - ErrorEquals: [States.ALL]
    ResultPath: $.error
    Next: MarkFailed

ResultPath: $.error merges the error details into the state data under $.error rather than replacing the entire input. That means MarkFailed still receives documentId and tenantId — it can always look up which document to update, even when the failure happens deep in an unexpected state.

The pipeline status flows back to the React frontend through the documents table. The UI polls the document status endpoint every few seconds and updates the card from uploading → processing → ready (or failed with the error message shown inline).

Why Express Workflows, Not Standard

Step Functions has two execution types. The choice matters for cost.

Standard Workflows charge per state transition — $0.025 per 1,000 transitions. A pipeline with 100 chunks runs the Map state, which means 100 EmbedChunk transitions plus the surrounding states. At scale, that adds up fast.

Express Workflows charge per execution and duration — $1.00 per million executions plus $0.00001 per GB-second. For a pipeline that completes in 2–4 minutes, the cost per document is a fraction of a cent.

The tradeoffs Express gives up: maximum 5-minute duration, at-least-once (not exactly-once) execution semantics, and no synchronous execution pattern. None of those matter here — the pipeline completes well under 5 minutes for any realistic document size, and ON CONFLICT DO NOTHING in the embed insert makes at-least-once delivery safe.

The Real Argument for Step Functions

None of the above required Step Functions specifically. You could build the same pipeline with SQS queues between Lambda functions. The chunked output goes on a queue; workers pick up items and embed them; another queue signals the metadata stage.

The practical difference shows up when something breaks.

When a document gets stuck in an SQS pipeline, diagnosing it means correlating CloudWatch log groups across multiple Lambda functions, checking DLQ message counts, and reconstructing the sequence of events from timestamps. The document is somewhere in the pipeline, but you're inferring state from indirect evidence.

In Step Functions, you open the console, click the execution, and see this:

ExtractText        → SUCCEEDED  (2.3s)
ChunkText          → SUCCEEDED  (0.1s)
GenerateEmbeddings → FAILED
  └─ EmbedChunk[47] → FAILED (attempt 3/3)
       Error: ThrottlingException
       Cause: Rate exceeded for model amazon.titan-embed-text-v2:0

The failure is pinpointed: chunk 47, third retry, Bedrock throttle. Every invocation's input and output is stored in the execution history. For a portfolio project where the goal is demonstrating architectural thinking clearly — including to interviewers who might pull up the AWS console during a technical screen — that visibility is genuinely worth something.

What's Next

Part 4 covers the RAG query path: how a user's question gets embedded, how pgvector finds the closest chunks across potentially thousands of document segments, and how the citation system links each paragraph of Claude's response back to the source text.

The code for this post:

infrastructure/template.yaml — state machine definition, EventBridge rule, InputTransformer
backend/pipeline/extract/extract_handler.py — file type dispatch, S3 key parsing
backend/pipeline/chunk/chunk_handler.py — sliding window chunker
backend/pipeline/embed/embed_handler.py — Bedrock Titan Embed v2, pgvector insert
backend/pipeline/metadata/metadata_handler.py — structured Haiku output, markdown fence stripping

Part of the Sift series: building a production-ready multi-tenant RAG platform on AWS.

Multi-Tenant Auth with Cognito and PostgreSQL Row-Level Security (Part 2)

Josh Blair — Thu, 21 May 2026 02:01:31 +0000

Multi-Tenant Auth with Cognito and PostgreSQL Row-Level Security (Part 2)

How a single Postgres session variable — app.current_tenant_id — eliminates an entire class of data-leak bugs at the database level.

The hardest bug to find in a multi-tenant SaaS app is the one that silently returns the wrong data. It doesn't throw an exception. It doesn't return a 403. It just quietly hands tenant A's documents to tenant B, and you don't find out until a customer does.

Most demo apps guard against this with WHERE tenant_id = @tenantId clauses scattered through their query code. That works until one gets missed — a new endpoint, a refactor that drops the filter, a copy-paste that forgets to update the variable name. One missed clause is a data leak.

Sift uses a different approach: the database enforces tenant isolation automatically, regardless of what the application code does. This post covers how the full chain works — from Cognito JWT to Postgres policy — and why each piece is necessary.

The Full Trust Chain

Here's the sequence for every authenticated API request:

Browser → Cognito (login)
       ← JWT signed with tenantId claim

Browser → API Gateway (request + JWT in Authorization header)
        → API Gateway validates JWT signature, rejects if invalid
        → Lambda receives validated claims in request context

Lambda  → extracts tenantId from request.RequestContext.Authorizer.Jwt.Claims
        → opens DB connection
        → calls set_config('app.current_tenant_id', tenantId, false)
        → runs query — Postgres RLS policy auto-filters every row

Each step is independently enforced. A user can't forge the tenantId in the JWT because they don't have Cognito's signing key. A request can't skip the JWT check because API Gateway rejects it before Lambda runs. A query can't bypass the RLS filter because the application user doesn't have BYPASSRLS.

Let's walk through each layer.

Layer 1: Cognito — Injecting tenantId into the JWT

Cognito User Pools support custom attributes on user objects. In template-cognito.yaml, the User Pool schema includes a custom:tenantId attribute:

UserPool:
  Type: AWS::Cognito::UserPool
  Properties:
    Schema:
      - Name: tenantId
        AttributeDataType: String
        Mutable: true
    LambdaConfig:
      PreTokenGeneration: !GetAtt PreTokenLambda.Arn

The custom:tenantId attribute is stored on the Cognito user record — set at invite/signup time by an admin or provisioning flow. But custom attributes don't appear in the JWT by default. That's where the Pre-Token Generation Lambda comes in.

The Pre-Token Generation Lambda

Every time Cognito issues a token, it calls this Lambda before signing it. The Lambda reads the user's custom:tenantId attribute and injects it as a top-level claim:

DEFAULT_TENANT = 'aaaaaaaa-0000-0000-0000-000000000001'  # acme demo tenant

def handler(event, context):
    tenant_id = event['request']['userAttributes'].get('custom:tenantId') or DEFAULT_TENANT
    event['response']['claimsOverrideDetails'] = {
        'claimsToAddOrOverride': {'tenantId': tenant_id}
    }
    return event

After this Lambda runs, the resulting JWT contains "tenantId": "<uuid>" as a standard claim alongside sub, email, and the rest. Cognito then signs the token with its RSA private key.

The security guarantee here is important: the tenantId in the JWT is now as trustworthy as the user's identity itself. The browser receives a signed token and passes it on requests — it cannot alter the tenantId without invalidating the signature.

Layer 2: API Gateway — JWT Validation for Free

API Gateway HTTP APIs support a native JWT authorizer. No custom Lambda authorizer needed — API Gateway handles validation itself before the request reaches the Lambda function:

HttpApi:
  Type: AWS::Serverless::HttpApi
  Properties:
    Auth:
      DefaultAuthorizer: CognitoJwtAuthorizer
      Authorizers:
        CognitoJwtAuthorizer:
          IdentitySource: $request.header.Authorization
          JwtConfiguration:
            issuer: !Sub
              - https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPoolId}
              - UserPoolId: !ImportValue
                  Fn::Sub: sift-${Env}-UserPoolId
            audience:
              - !ImportValue
                  Fn::Sub: sift-${Env}-UserPoolClientId

This configuration tells API Gateway to:

Extract the Bearer token from the Authorization header
Verify the signature against Cognito's public keys (fetched from the issuer URL's JWKS endpoint)
Verify the aud claim matches the expected client ID
Reject the request with a 401 if any check fails

If the JWT is invalid, expired, or has the wrong audience, Lambda never runs. The tenantId claim that reaches Lambda has already been cryptographically validated.

Layer 3: Lambda — Extracting the Claim

Once API Gateway passes the request through, the validated JWT claims are available in the Lambda event's request context. Extracting tenantId is a single line:

private static Guid GetTenantId(APIGatewayHttpApiV2ProxyRequest request)
{
    var claim = request.RequestContext.Authorizer.Jwt.Claims["tenantId"];
    return Guid.Parse(claim);
}

This runs at the top of every Lambda handler before any service code executes:

public async Task<APIGatewayHttpApiV2ProxyResponse> FunctionHandler(
    APIGatewayHttpApiV2ProxyRequest request, ILambdaContext context)
{
    var tenantId   = GetTenantId(request);
    var cognitoSub = request.RequestContext.Authorizer.Jwt.Claims["sub"];
    // ... route to service
}

The tenantId extracted here gets passed down to the service layer, which uses it to set the database session variable before running any query.

Layer 4: PostgreSQL Row-Level Security

This is where the real defense happens.

The Problem with WHERE Clauses

The naive approach is filtering every query manually:

SELECT * FROM documents WHERE tenant_id = @tenantId AND id = @docId

This works until it doesn't. Add a new endpoint in a hurry, forget the WHERE tenant_id clause, and you've got a data leak — with no runtime error to alert you. The query succeeds; it just returns data it shouldn't.

Row-Level Security moves the filter into the database engine. The policy is applied automatically to every query on that table, whether the application code includes a filter or not.

Setting Up RLS

The schema enables RLS on every tenant-scoped table and defines a single policy:

ALTER TABLE documents       ENABLE ROW LEVEL SECURITY;
ALTER TABLE document_chunks ENABLE ROW LEVEL SECURITY;
ALTER TABLE users           ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON documents
  USING (tenant_id = current_setting('app.current_tenant_id')::UUID);

CREATE POLICY tenant_isolation ON document_chunks
  USING (tenant_id = current_setting('app.current_tenant_id')::UUID);

CREATE POLICY tenant_isolation ON users
  USING (tenant_id = current_setting('app.current_tenant_id')::UUID);

current_setting('app.current_tenant_id') reads a Postgres session-level variable that the application sets before running any query. The ::UUID cast means a missing or malformed value throws an error rather than silently returning empty results.

Setting the Session Variable

In TenantContext.cs, every service method that opens a database connection immediately calls:

public static async Task SetAsync(NpgsqlConnection connection, Guid tenantId)
{
    await using var cmd = connection.CreateCommand();
    // is_local=false → session scope. Safe because Lambda connections are
    // never pooled across requests (Pooling=false in DbConnectionFactory).
    cmd.CommandText = "SELECT set_config('app.current_tenant_id', $1, false)";
    cmd.Parameters.AddWithValue(tenantId.ToString());
    await cmd.ExecuteNonQueryAsync();
}

The false parameter in set_config means session scope rather than transaction scope. This is intentional: the Lambda's database connections are not pooled across requests (Pooling=false in the connection factory), so a session-scoped variable is both safe and slightly more efficient than resetting it per-transaction.

Every service method calls this before touching data:

public async Task<IEnumerable<Document>> ListAsync(Guid tenantId)
{
    await using var conn = await _db.CreateAsync();
    await TenantContext.SetAsync(conn, tenantId);
    // From this point on, every query automatically filters to tenantId's rows
    // ...
}

The BYPASSRLS Gotcha

There's one critical detail that's easy to miss: Postgres superusers bypass RLS by default. If your application database user has superuser privileges, ENABLE ROW LEVEL SECURITY does nothing — the policies are silently skipped.

The application user in Sift is the standard credentials from Secrets Manager — a normal role with SELECT, INSERT, UPDATE, DELETE on the application tables, and nothing more. No SUPERUSER. No BYPASSRLS. This isn't incidental; it's a deliberate requirement for RLS to actually work.

If you're debugging why your RLS policies seem to have no effect, check the role: SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = 'your_app_user';

Layer 5: S3 Key Prefix

RLS handles the database. S3 needs a complementary approach.

Every document is stored at a key prefixed with the tenant's ID:

{tenantId}/{documentId}/filename.pdf

When a user requests a presigned upload URL, the Lambda constructs the key using the tenantId from their validated JWT. The browser then uploads directly to S3 using that presigned URL — it has no say in what key gets used.

The result: even if a presigned URL leaked somehow, it would only allow access to that specific object under the tenant's prefix. Tenant A's presigned URL cannot be used to list or access tenant B's documents — the key prefixes are different UUIDs.

S3 doesn't have "row-level security" — but a properly namespaced key structure combined with IAM policies that don't allow s3:ListBucket on the uploads bucket achieves the same practical outcome.

Why Three Layers?

Each layer protects a different attack surface:

Layer	Protects Against
Cognito JWT	User forging a different tenantId on the client
API Gateway validation	Bypassing auth entirely (no token, expired token)
Postgres RLS	Application bugs — a missing WHERE clause, a new query that forgets the filter
S3 key prefix	Cross-tenant object access, presigned URL misuse

The layers are independent. A bug that breaks one doesn't compromise the others. If somehow a tenantId was wrong in application code, RLS would still return empty results — not the wrong tenant's data. Defense in depth means the blast radius of any single failure is contained.

Seeing It in Action

The live demo has two tenants: Acme Corp and Globex Inc, both seeded in the initial migration. You can log in as an Acme Corp user, upload a document, then log in as a Globex user — the document list is empty. Both tenants run against the same Aurora cluster, the same Lambda functions, the same S3 bucket. The query is identical. Postgres silently returns the right rows for each.

What's Next

Part 3 covers the Step Functions Express pipeline — how the six-stage document processing workflow is orchestrated, why the Map state handles embedding generation, and how the state machine's declarative retry config replaces dozens of lines of error-handling code.

The code for everything in this post:

infrastructure/template-cognito.yaml — Pre-Token Lambda and User Pool definition
migrations/001_initial_schema.sql — full CREATE POLICY statements
backend/src/Sift.Api/Infrastructure/TenantContext.cs — the set_config call
backend/src/Sift.Api/Infrastructure/DbConnectionFactory.cs — why Pooling=false matters
backend/src/Sift.Api/Functions/DocumentsFunction.cs — JWT claim extraction

Part of the Sift series: building a production-ready multi-tenant RAG platform on AWS.

Building a Multi-Tenant AI Document Platform on AWS (Part 1: Architecture)

Josh Blair — Thu, 21 May 2026 02:01:28 +0000

Building a Multi-Tenant AI Document Platform on AWS (Part 1: Architecture)

How I designed a production-ready RAG system from scratch using AWS-native services — and kept the monthly bill under $20.

Every senior full-stack role I see right now lists "AI experience" somewhere in the requirements. The problem is that most AI portfolio projects look the same: a Next.js frontend, a call to the OpenAI API, maybe a LangChain wrapper. They're fine demos, but they don't show anything about how you'd actually build and operate a system at scale.

I wanted to build something that would hold up in a technical interview with an AWS architect — not just "I built a chatbot." So I built Sift: a multi-tenant RAG (Retrieval-Augmented Generation) document platform, fully serverless, built on AWS-native services, with real data isolation between tenants, an async document processing pipeline, and a total monthly cost of about $10–15 in a live demo environment.

This is the first post in a six-part series. Here I'll walk through the overall architecture and explain why I made each service choice. Future posts will dig into specific areas: auth and multi-tenancy, the Step Functions pipeline, the RAG implementation, the React frontend, and the CI/CD pipeline.

What Sift Does

Users upload documents — PDF, DOCX, CSV, or plain text. Sift processes them asynchronously through a six-stage pipeline, generating text embeddings and storing them in a vector database. Users then ask natural language questions, and Sift retrieves the most relevant chunks from their documents and feeds them to a Claude model to generate a grounded answer with numbered citations linking back to the source text.

It's a legitimate enterprise use case: internal knowledge bases, contract review, research assistants. The architecture reflects that — it's not a demo that would fall apart the moment a second organization tried to use it.

The Full Architecture

Here's how data flows through the system:

Let's go through each choice.

Why Each Service?

Aurora Serverless v2 with pgvector

The go-to recommendation for vector storage right now is a managed vector database — Pinecone, Weaviate, OpenSearch with k-NN. I deliberately chose not to use any of them.

Sift already needs a relational database for its operational data: tenants, users, documents, processing status. Aurora PostgreSQL Serverless v2 handles all of that and the vector search with the pgvector extension. That's one less service to operate, one less connection to secure, one less cost line item.

pgvector supports cosine similarity search, IvfFlat indexes for approximate nearest-neighbor search at scale, and runs directly in the Postgres query planner — which means I can join vector search results with relational data in a single query. When a user asks a question, I can filter to only that tenant's documents before the similarity search, not after. That's a meaningful security and efficiency win.

The Serverless v2 auto-pause feature means the cluster scales to zero ACUs (Aurora Capacity Units) during idle periods. For a portfolio demo that doesn't have 24/7 traffic, that alone cuts the database cost from ~$50–70/month for a minimum-size provisioned Aurora instance to roughly $7/month in actual usage.

The tradeoff: the first query after an idle period has a cold-start delay while the cluster resumes — typically 5–15 seconds. That's acceptable for a demo, and for production you'd set a non-zero minimum ACU to keep it warm.

Step Functions Express Workflows

When I first sketched the pipeline, the obvious choice was SQS queues between Lambda stages — it's the standard event-driven pattern and I've used it plenty of times. I chose Step Functions Express instead, and it was the right call for this project.

The visibility argument is simple: when I open the AWS console and click into a Step Functions execution, I can see exactly which stage a document is in, what the input and output were at each step, and precisely where it failed if something went wrong. With SQS, you're inferring pipeline state from DLQ message counts and CloudWatch metrics. That's fine in production where you've built dashboards for it — it's friction in a portfolio project where the goal is demonstrating the architecture clearly.

Step Functions also handles retries and error catching declaratively in the state machine definition. Instead of writing retry logic in each Lambda, I configure it once in the YAML:

Retry:
  - ErrorEquals: [States.ALL]
    IntervalSeconds: 2
    MaxAttempts: 3
    BackoffRate: 2

Transient errors — throttling, network blips — get retried automatically. Unrecoverable failures route to the MarkFailed state, which updates the document status and preserves the error for display in the UI.

Express Workflows (vs. Standard Workflows) are priced per execution and duration rather than per state transition. For a document pipeline that completes in under 5 minutes, this is significantly cheaper. The tradeoff is that Express Workflows have a maximum duration of 5 minutes and don't support activities or sync patterns that Standard Workflows do — neither matters here.

Amazon Bedrock

I used Bedrock for both embedding generation (Titan Embed v2, 1024 dimensions) and the chat completion (Claude Haiku 4.5).

The straightforward reason is that it keeps everything inside the AWS trust boundary. No data leaves my VPC to a third-party API. Authentication is IAM, not an API key stored in a secret. There's no separate vendor account to manage, no risk of data being used for model training, and the latency is lower because it's in-region.

The more practical reason: on an AWS-focused résumé, "I used Bedrock" is worth more than "I used OpenAI." It demonstrates familiarity with Bedrock's APIs, model catalog, and IAM integration patterns that you'd actually use in enterprise AWS environments.

Titan Embed v2 produces 1024-dimensional vectors with normalized outputs — which means cosine similarity and dot product give equivalent results, simplifying the pgvector query. Claude Haiku 4.5 handles the metadata extraction (generating a document summary and extracting topics from text chunks) and the final chat response generation. Haiku is fast and cheap for the metadata step; the quality is more than adequate for structured extraction tasks.

Amazon Cognito

Auth is one of those areas where building your own is almost always the wrong call. Cognito gives you a managed user pool with email/password auth, JWT issuance, and a hosted UI for free at demo scale.

The interesting piece is the Pre-Token Generation Lambda trigger. When Cognito issues a JWT, it calls a Lambda function that can add custom claims to the token before it's signed. I use this to inject a tenantId claim — the tenant the user belongs to — directly into the token.

That tenantId flows downstream: API Gateway validates the JWT and rejects unauthenticated requests; my Lambda functions extract the claim from the validated token context; and the database uses it to enforce Row-Level Security. The tenant identity is cryptographically bound to the token — a user can't forge a different tenantId without Cognito's private signing key.

AWS SAM over CDK

CDK is a better abstraction for large teams and complex infrastructure. SAM is CloudFormation with a thinner layer of syntactic sugar, which means the output is standard CloudFormation YAML that any AWS engineer can read without knowing TypeScript or Python CDK constructs.

For portfolio purposes, that's actually the right choice. When I'm walking through this in an interview, I want to point directly at template.yaml and explain the AWS::Serverless::StateMachine resource, the IAM policy, the event source mapping — without the interviewer needing to know what aws_cdk.aws_stepfunctions compiles to under the hood.

Multi-Tenancy: Three Layers of Isolation

This is where a lot of "multi-tenant" demos fall short — they add a tenantId column to their tables and filter on it in application code. That works until a bug in one query path leaks cross-tenant data.

Sift uses three independent isolation layers:

Layer 1 — Cognito custom claim. The tenantId is in the signed JWT. No application code can inject or modify it.

Layer 2 — S3 key prefix. Every uploaded document is stored at {tenantId}/{documentId}/{filename}. Tenant A can't construct a presigned URL for tenant B's key without knowing the exact key path — and they'd also need to be an IAM principal with S3 access, which they're not.

Layer 3 — PostgreSQL Row-Level Security. Before any database query executes, the Lambda sets a session variable:

SELECT set_config('app.current_tenant_id', $1, false)

The RLS policies on every table enforce this automatically at the database level:

CREATE POLICY tenant_isolation ON documents
  USING (tenant_id = current_setting('app.current_tenant_id')::UUID);

Even if application code contained a bug that omitted a WHERE tenant_id = ? clause, the database would still return only the current tenant's rows. The isolation is enforced below the application layer.

One important gotcha: the database application user must not have BYPASSRLS privileges. Postgres superusers bypass RLS by default. If your Lambda connects as a superuser, your RLS policies are decoration.

Cost Breakdown

One thing I wanted to demonstrate with this project is that you can run a legitimate, production-architected system for almost nothing at low volume:

Service	Monthly Cost
Aurora Serverless v2 (auto-pause, demo traffic)	~$7
Amazon Bedrock (embeddings + chat, light usage)	~$2–5
Lambda, API Gateway, S3, CloudFront	Free tier
Cognito (under 50k MAU)	Free tier
Total	~$10–15

The variable cost scales with Bedrock usage — each embedding call and each chat completion. At real production volume you'd be looking at real Bedrock costs, and you'd want to add CloudFront caching for static assets and tune Lambda memory settings. But the architectural pattern holds: Aurora Serverless v2 auto-pause means you're not paying for compute when nobody is using the system.

AWS Well-Architected Alignment

Since this is a portfolio project for AWS architecture roles, I mapped the design against the six pillars explicitly:

Operational Excellence — SAM + GitHub Actions with OIDC: the entire infrastructure is code, deployments are automated, there are no manual steps
Security — OIDC federation (zero stored credentials), Row-Level Security, Cognito JWT, no Lambda with public S3 access
Reliability — Step Functions retry logic, EventBridge decoupling between S3 upload and pipeline execution, Aurora Multi-AZ in production config
Performance Efficiency — Aurora Serverless v2 scales with demand, Map state in Step Functions parallelizes embedding generation
Cost Optimization — Aurora auto-pause, Bedrock pay-per-token, Lambda and CloudFront at free tier scale
Sustainability — Serverless by default: compute resources allocated only when actively processing

What's Next

This series covers each major subsystem in depth:

Part 2: Multi-tenant auth — how the Cognito Pre-Token Lambda works, the RLS policy setup, and the C# tenant context middleware
Part 3: The Step Functions pipeline — state machine design, the Map state for parallel embedding, error handling
Part 4: RAG and vector search — chunking strategy, pgvector queries, and how citations are generated
Part 5: The React frontend — polling patterns, Amplify auth integration, the upload flow
Part 6: CI/CD with GitHub Actions and OIDC — zero-secret deployments to AWS

The live demo is running at sift.bonefishsoftware.com — log in with the shared Acme Corp credentials from the README and try uploading a PDF.

The code is at github.com/joshblair/sift.

Part of the Sift series: building a production-ready multi-tenant RAG platform on AWS.

Serverless Contact Form — Lambda, API Gateway, DynamoDB, and SES

Josh Blair — Thu, 21 May 2026 00:07:07 +0000

Overview

The contact form on bonefishsoftware.com is fully serverless — no EC2, no always-on server. A visitor submits the form, the request hits an API Gateway HTTP API, a Python Lambda function validates and stores the submission in DynamoDB, then sends an email notification via SES. Cost at low volume: effectively zero.

Flow

Infrastructure — AWS SAM

The contact API is deployed using AWS SAM (Serverless Application Model), a CloudFormation extension that simplifies Lambda + API Gateway resource definitions.

Why SAM over plain CloudFormation?

SAM's AWS::Serverless::Function with Events automatically creates the API Gateway routes, integrations, Lambda permissions, and stage. Doing this in plain CloudFormation requires 6–8 separate resource definitions. SAM condenses it to one function resource with an Events section.

Key lesson: `AWS::Serverless::HttpApi` vs `AWS::ApiGatewayV2::Api`

The most important thing to get right: when using SAM's HttpApi event type, the ApiId must reference an AWS::Serverless::HttpApi resource — not a native AWS::ApiGatewayV2::Api.

Using the wrong resource type results in the SAM transform silently skipping route and integration creation, leaving you with a deployed API that returns 404 on every request.

# ✅ Correct — SAM manages routes/integrations automatically
ContactApi:
  Type: AWS::Serverless::HttpApi
  Properties:
    CorsConfiguration:
      AllowOrigins: [https://bonefishsoftware.com]
      AllowMethods: [POST, OPTIONS]
      AllowHeaders: [Content-Type]

ContactFunction:
  Type: AWS::Serverless::Function
  Events:
    PostContact:
      Type: HttpApi
      Properties:
        ApiId: !Ref ContactApi   # ← references Serverless::HttpApi
        Path: /contact
        Method: POST

# ❌ Wrong — routes NOT created by SAM
ContactApi:
  Type: AWS::ApiGatewayV2::Api  # ← native resource, SAM ignores events

Lambda Function (Python)

# lambda/contact/handler.py

import json, os, uuid
from datetime import datetime, timezone
import boto3
from botocore.exceptions import ClientError

ALLOWED_ORIGIN = os.environ.get("ALLOWED_ORIGIN", "https://bonefishsoftware.com")
TABLE_NAME = os.environ["TABLE_NAME"]
FROM_ADDRESS = os.environ["FROM_ADDRESS"]
TO_ADDRESS = os.environ["TO_ADDRESS"]

dynamodb = boto3.resource("dynamodb")
ses = boto3.client("ses")

def handler(event, context):
    # Handle CORS preflight
    if event.get("requestContext", {}).get("http", {}).get("method") == "OPTIONS":
        return _response(200, {})

    # Parse and validate
    try:
        body = json.loads(event.get("body") or "{}")
    except (json.JSONDecodeError, TypeError):
        return _response(400, {"error": "Invalid request body."})

    name    = (body.get("name") or "").strip()
    email   = (body.get("email") or "").strip()
    message = (body.get("message") or "").strip()
    company = (body.get("company") or "").strip()

    if not name or not email or not message:
        return _response(400, {"error": "Name, email, and message are required."})

    if "@" not in email or "." not in email.split("@")[-1]:
        return _response(400, {"error": "Please provide a valid email address."})

    submission_id = str(uuid.uuid4())
    timestamp = datetime.now(timezone.utc).isoformat()

    try:
        _save_to_dynamo(submission_id, timestamp, name, email, company, message)
        _send_email(submission_id, timestamp, name, email, company, message)
    except ClientError as e:
        print(f"AWS error: {e}")
        return _response(500, {"error": "Failed to process your message. Please try again."})

    return _response(200, {"message": "Message received! We'll be in touch soon."})

Why no external dependencies?

Python's boto3 SDK is built into the Lambda runtime — no requirements.txt needed. The deployment package is just a single handler.py file, keeping Lambda cold-start time minimal.

Validation approach

Validation is intentionally lightweight:

Required field presence check
Naive email format check (contains @ and a . after it)

We're not the primary spam defense here — the contact form has no public financial incentive to spam, and rate limiting can be added at the API Gateway level later if needed.

DynamoDB Table

SubmissionsTable:
  Type: AWS::DynamoDB::Table
  Properties:
    TableName: bonefish-contact-submissions
    BillingMode: PAY_PER_REQUEST
    AttributeDefinitions:
      - AttributeName: submissionId
        AttributeType: S
      - AttributeName: timestamp
        AttributeType: S
    KeySchema:
      - AttributeName: submissionId
        KeyType: HASH
      - AttributeName: timestamp
        KeyType: RANGE

PAY_PER_REQUEST billing — no provisioned capacity to manage. At the volume of a contact form (single-digit submissions per day at most), this costs essentially nothing.

Composite key (submissionId + timestamp) — the UUID ensures uniqueness; the timestamp makes it easy to sort and query submissions chronologically in future tooling.

SES Email Delivery

Domain verification (DKIM)

Emails sent from noreply@bonefishsoftware.com require the domain to be verified in SES. This involves adding three DKIM CNAME records to Route 53:

aws sesv2 create-email-identity \
  --email-identity bonefishsoftware.com \
  --region us-west-2
# → returns 3 DKIM tokens

# Add CNAME records: <token>._domainkey.bonefishsoftware.com → <token>.dkim.amazonses.com

DKIM signing tells receiving mail servers that the email genuinely came from our domain, improving deliverability and preventing spoofing.

Sandbox mode

By default, SES operates in sandbox mode — you can only send to verified email addresses. This is sufficient for the contact form (we only send TO josh.blair@gmail.com, which is verified). The submitter's email address appears only in the Reply-To header and the email body — never as a direct recipient.

SES production access (removing sandbox restrictions) was requested via:

aws sesv2 put-account-details \
  --mail-type TRANSACTIONAL \
  --website-url https://bonefishsoftware.com \
  --use-case-description "..." \
  --production-access-enabled

Reply-To header

ses.send_email(
    Source=FROM_ADDRESS,                  # noreply@bonefishsoftware.com
    Destination={"ToAddresses": [TO_ADDRESS]},  # josh.blair@gmail.com
    Message={...},
    ReplyToAddresses=[email],             # submitter's email
)

Setting ReplyToAddresses to the submitter's email means hitting "Reply" in gmail automatically addresses the response to the client — no copy-pasting required.

CORS Configuration

CORS is configured at the API Gateway level (not in the Lambda response), via the AWS::Serverless::HttpApi resource:

ContactApi:
  Type: AWS::Serverless::HttpApi
  Properties:
    CorsConfiguration:
      AllowOrigins:
        - https://bonefishsoftware.com
        - http://localhost:5173    # local dev
      AllowHeaders:
        - Content-Type
      AllowMethods:
        - POST
        - OPTIONS
      MaxAge: 300

The Lambda still returns Access-Control-Allow-Origin headers in its response (for safety), but API Gateway handles the OPTIONS preflight response automatically.

Lesson learned: An early version used AWS::ApiGatewayV2::Api instead of AWS::Serverless::HttpApi. The CORS configuration was present but the routes were never created — resulting in 404 responses and CORS errors in the browser. Switching to AWS::Serverless::HttpApi resolved both issues simultaneously.

Frontend Integration

The contact form in React fetches the API URL from a Vite environment variable:

// src/pages/Contact.tsx
const apiUrl = import.meta.env.VITE_CONTACT_API_URL;

async function handleSubmit(e: React.FormEvent) {
  e.preventDefault();
  setStatus('submitting');
  try {
    const res = await fetch(apiUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(form),
    });
    if (!res.ok) throw new Error('Request failed');
    setStatus('success');
  } catch {
    setStatus('error');
  }
}

VITE_CONTACT_API_URL is injected at build time by CodeBuild as an environment variable. Vite replaces import.meta.env.VITE_* references with literal string values during the build — there's no runtime environment lookup.

SAM Deployment

sam deploy \
  --template-file infra/stacks/contact-api.yml \
  --stack-name bonefish-contact-api \
  --region us-west-2 \
  --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \
  --s3-bucket bonefish-pipeline-artifacts-709085484102 \
  --s3-prefix sam-contact \
  --no-confirm-changeset

CAPABILITY_AUTO_EXPAND is required when the template uses Transform: AWS::Serverless-2016-10-31. This tells CloudFormation to expand SAM macros before processing the template.

SAM packages the Lambda code (zips lambda/contact/), uploads to the artifacts S3 bucket, and replaces the local CodeUri path with the S3 URL in the transformed template — all automatically.

Cost Analysis

At typical consulting site traffic:

Resource	Usage	Estimated cost
API Gateway HTTP API	100 requests/month	$0.001
Lambda	100 invocations × 128MB × 500ms	< $0.01
DynamoDB	100 writes, PAY_PER_REQUEST	< $0.01
SES	100 emails	$0.01
Total		< $0.05/month

The entire contact form backend costs pennies per month.

CI/CD with AWS CodePipeline and CodeBuild

Josh Blair — Thu, 21 May 2026 00:06:17 +0000

Overview

Every push to the main branch on GitHub automatically builds the React app and deploys it to S3 + CloudFront — zero manual steps. This article covers how that pipeline is wired together using AWS CodePipeline, CodeBuild, and GitHub via CodeStar Connections.

Pipeline Flow

CloudFormation Stack

The pipeline infrastructure is defined in infra/stacks/pipeline.yml.

CodeStar Connection (GitHub App)

GitHubConnection:
  Type: AWS::CodeStarConnections::Connection
  Properties:
    ConnectionName: bonefish-github
    ProviderType: GitHub

Manual step required: After deploying the stack, you must go to AWS Console → CodePipeline → Settings → Connections and click "Update pending connection" to authorize the GitHub App. This cannot be automated — AWS requires explicit human approval to grant access to your GitHub account.

When authorizing, install the AWS Connector for GitHub app on your GitHub account and grant it access to the specific repository. "Connect as a GitHub user" only works for CodeBuild — CodePipeline requires the GitHub App.

Artifact Bucket

Intermediate pipeline artifacts (source zip, build output) are stored in a private S3 bucket:

ArtifactBucket:
  Type: AWS::S3::Bucket
  Properties:
    BucketName: !Sub 'bonefish-pipeline-artifacts-${AWS::AccountId}'
    VersioningConfiguration:
      Status: Enabled
    PublicAccessBlockConfiguration:
      BlockPublicAcls: true
      BlockPublicPolicy: true
      IgnorePublicAcls: true
      RestrictPublicBuckets: true

CodeBuild Project

BuildProject:
  Type: AWS::CodeBuild::Project
  Properties:
    Name: bonefish-build
    ServiceRole: !GetAtt CodeBuildRole.Arn
    Artifacts:
      Type: CODEPIPELINE
    Environment:
      Type: LINUX_CONTAINER
      ComputeType: BUILD_GENERAL1_SMALL
      Image: aws/codebuild/standard:7.0
      EnvironmentVariables:
        - Name: S3_BUCKET
          Value: !Ref S3BucketName
        - Name: DISTRIBUTION_ID
          Value: !Ref DistributionId
    Source:
      Type: CODEPIPELINE
      BuildSpec: buildspec.yml

CodePipeline

Pipeline:
  Type: AWS::CodePipeline::Pipeline
  Properties:
    Name: bonefish-website-pipeline
    RoleArn: !GetAtt PipelineRole.Arn
    PipelineType: V2
    Stages:
      - Name: Source
        Actions:
          - Name: GitHub
            ActionTypeId:
              Category: Source
              Owner: AWS
              Provider: CodeStarSourceConnection
              Version: '1'
            Configuration:
              ConnectionArn: !Ref GitHubConnection
              FullRepositoryId: !Sub '${GitHubOwner}/${GitHubRepo}'
              BranchName: !Ref GitHubBranch
              DetectChanges: true
            OutputArtifacts:
              - Name: SourceArtifact
      - Name: Build
        Actions:
          - Name: BuildAndDeploy
            ActionTypeId:
              Category: Build
              Owner: AWS
              Provider: CodeBuild
              Version: '1'
            Configuration:
              ProjectName: !Ref BuildProject
            InputArtifacts:
              - Name: SourceArtifact

DetectChanges: true means CodePipeline automatically triggers on every push to the configured branch — no webhooks to configure manually.

IAM Roles

Two IAM roles are needed: one for CodePipeline, one for CodeBuild.

CodePipeline Role

PipelineRole:
  Type: AWS::IAM::Role
  Properties:
    AssumeRolePolicyDocument:
      Statement:
        - Effect: Allow
          Principal:
            Service: codepipeline.amazonaws.com
          Action: sts:AssumeRole
    Policies:
      - PolicyName: PipelinePolicy
        PolicyDocument:
          Statement:
            - Sid: ArtifactBucket
              Effect: Allow
              Action: [s3:GetObject, s3:PutObject, s3:GetObjectVersion, s3:GetBucketVersioning]
              Resource: [!Sub '${ArtifactBucket.Arn}', !Sub '${ArtifactBucket.Arn}/*']
            - Sid: CodeBuild
              Effect: Allow
              Action: [codebuild:BatchGetBuilds, codebuild:StartBuild]
              Resource: !GetAtt BuildProject.Arn
            - Sid: CodeStarConnection
              Effect: Allow
              Action: [codestar-connections:UseConnection]
              Resource: !Ref GitHubConnection

CodeBuild Role

CodeBuildRole:
  Type: AWS::IAM::Role
  Properties:
    AssumeRolePolicyDocument:
      Statement:
        - Effect: Allow
          Principal:
            Service: codebuild.amazonaws.com
          Action: sts:AssumeRole
    Policies:
      - PolicyName: CodeBuildPolicy
        PolicyDocument:
          Statement:
            - Sid: Logs
              Effect: Allow
              Action: [logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents]
              Resource: '*'
            - Sid: ArtifactBucket
              Effect: Allow
              Action: [s3:GetObject, s3:PutObject, s3:GetObjectVersion]
              Resource: !Sub '${ArtifactBucket.Arn}/*'
            - Sid: WebsiteSync
              Effect: Allow
              Action: [s3:PutObject, s3:DeleteObject, s3:GetObject, s3:ListBucket]
              Resource:
                - !Sub 'arn:aws:s3:::${S3BucketName}'
                - !Sub 'arn:aws:s3:::${S3BucketName}/*'
            - Sid: CloudFrontInvalidation
              Effect: Allow
              Action: [cloudfront:CreateInvalidation]
              Resource: !Sub 'arn:aws:cloudfront::${AWS::AccountId}:distribution/${DistributionId}'

Principle of least privilege — CodeBuild can only write to the specific S3 bucket and invalidate the specific CloudFront distribution.

buildspec.yml

The build specification lives in the repo root and tells CodeBuild exactly what to do:

version: 0.2

env:
  variables:
    VITE_CONTACT_API_URL: ""  # overridden by CodeBuild project env var

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci

  build:
    commands:
      - npm run build

  post_build:
    commands:
      - aws s3 sync dist/ s3://$S3_BUCKET --delete
      - aws cloudfront create-invalidation --distribution-id $DISTRIBUTION_ID --paths "/*"

Key points

npm ci not npm install

npm ci installs exactly what's in package-lock.json and fails if there are any discrepancies. This ensures deterministic builds — the same packages every time, in every environment.

--delete flag on s3 sync

Removes files from S3 that no longer exist in the build output. Without this, deleted pages or renamed assets would stay in S3 forever and get served to users.

CloudFront invalidation

Vite includes content hashes in asset filenames (index-BX7FeaXh.js), so JS/CSS files are automatically cache-busted. However, index.html itself doesn't have a hash — it must be explicitly invalidated so CloudFront fetches the new version immediately.

VITE_CONTACT_API_URL env var

Vite's import.meta.env.VITE_* variables are replaced at build time (not runtime). The API Gateway URL is injected by CodeBuild as an environment variable and baked into the built JS bundle. This means the frontend always has the correct endpoint URL without any runtime configuration.

Troubleshooting the GitHub Connection

The CodeStar Connection requires careful setup. Common issues encountered:

Status: PENDING after stack deploy

Expected. You must visit the AWS Console to authorize it. Cannot be done via CLI.

"No Branch found" error

The GitHub App was authorized but the private repository wasn't explicitly granted access. Fix: GitHub → Settings → Applications → AWS Connector for GitHub → Configure → add the repo.

"Role does not have sufficient permissions" error

After replacing a broken connection with a new one, the CodePipeline IAM role policy still referenced the old connection ARN. Fix: update the codestar-connections:UseConnection resource ARN in the IAM policy to match the new connection ARN.

Deployment Timeline

From git push to live site:

Phase	Duration
CodePipeline detects change	~10 seconds
Source download from GitHub	~15 seconds
`npm ci` (cache warm)	~30 seconds
`npm run build` (tsc + vite)	~15 seconds
`aws s3 sync`	~10 seconds
CloudFront invalidation	~10 seconds
Total	~90 seconds

Full deployment in under two minutes on every push to main.

Static Site Hosting on AWS — S3, CloudFront, ACM, and Route 53

Josh Blair — Thu, 21 May 2026 00:06:08 +0000

Overview

This article covers deploying a static React site to AWS using S3 as the origin, CloudFront as the CDN, ACM for TLS certificates, and Route 53 for DNS. Everything is defined as CloudFormation infrastructure-as-code.

Architecture

CloudFormation Infrastructure

The hosting infrastructure is split across three stacks deployed in sequence:

Stack	File	Region	Purpose
`bonefish-acm`	`infra/acm/certificate.yml`	us-east-1	ACM TLS certificate
`bonefish-website`	`infra/stacks/website.yml`	us-west-2	S3 + CloudFront
`bonefish-pipeline`	`infra/stacks/pipeline.yml`	us-west-2	CI/CD (covered in article 4)

ACM Certificate (us-east-1)

Why us-east-1? CloudFront is a global service that only accepts ACM certificates provisioned in us-east-1. This is an AWS requirement regardless of where your other resources live.

# infra/acm/certificate.yml
Resources:
  Certificate:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: bonefishsoftware.com
      SubjectAlternativeNames:
        - www.bonefishsoftware.com
      ValidationMethod: DNS

DNS validation: ACM generates two CNAME records that must be added to your DNS zone. Because the domain is managed by Route 53, we added these via CLI:

aws route53 change-resource-record-sets \
  --hosted-zone-id $ZONE_ID \
  --change-batch '{ "Changes": [
    { "Action": "UPSERT", "ResourceRecordSet": {
      "Name": "_bf48ff...bonefishsoftware.com.",
      "Type": "CNAME", "TTL": 300,
      "ResourceRecords": [{"Value": "_ea68....acm-validations.aws."}]
    }}
  ]}'

Once the domain's nameservers resolve correctly, ACM validates automatically (typically 2–5 minutes).

S3 Bucket

The S3 bucket is private — no public access whatsoever. CloudFront accesses it via OAC (Origin Access Control).

WebsiteBucket:
  Type: AWS::S3::Bucket
  Properties:
    BucketName: bonefishsoftware-com-website
    VersioningConfiguration:
      Status: Enabled
    PublicAccessBlockConfiguration:
      BlockPublicAcls: true
      BlockPublicPolicy: true
      IgnorePublicAcls: true
      RestrictPublicBuckets: true

Bucket Policy — allow CloudFront OAC only

WebsiteBucketPolicy:
  Type: AWS::S3::BucketPolicy
  Properties:
    Bucket: !Ref WebsiteBucket
    PolicyDocument:
      Statement:
        - Effect: Allow
          Principal:
            Service: cloudfront.amazonaws.com
          Action: s3:GetObject
          Resource: !Sub '${WebsiteBucket.Arn}/*'
          Condition:
            StringEquals:
              AWS:SourceArn: !Sub >-
                arn:aws:cloudfront::${AWS::AccountId}:distribution/${Distribution}

The AWS:SourceArn condition means only our specific CloudFront distribution can read from this bucket — not any other CloudFront distribution in any AWS account.

Origin Access Control (OAC)

OAC is the modern replacement for Origin Access Identity (OAI). Key advantages:

Supports all S3 API operations
Works with SSE-KMS encrypted buckets
Uses AWS SigV4 request signing (more secure)

OriginAccessControl:
  Type: AWS::CloudFront::OriginAccessControl
  Properties:
    OriginAccessControlConfig:
      Name: bonefishsoftware-com-oac
      OriginAccessControlOriginType: s3
      SigningBehavior: always
      SigningProtocol: sigv4

CloudFront Distribution

Distribution:
  Type: AWS::CloudFront::Distribution
  Properties:
    DistributionConfig:
      Enabled: true
      DefaultRootObject: index.html
      Aliases:
        - bonefishsoftware.com
        - www.bonefishsoftware.com
      ViewerCertificate:
        AcmCertificateArn: !Ref CertificateArn
        SslSupportMethod: sni-only
        MinimumProtocolVersion: TLSv1.2_2021
      HttpVersion: http2and3
      Origins:
        - Id: S3Origin
          DomainName: !GetAtt WebsiteBucket.RegionalDomainName
          S3OriginConfig:
            OriginAccessIdentity: ''
          OriginAccessControlId: !GetAtt OriginAccessControl.Id
      DefaultCacheBehavior:
        TargetOriginId: S3Origin
        ViewerProtocolPolicy: redirect-to-https
        CachePolicyId: 658327ea-f89d-4fab-a63d-7e88639e58f6  # CachingOptimized
        Compress: true
      CustomErrorResponses:
        - ErrorCode: 403
          ResponseCode: 200
          ResponsePagePath: /index.html
          ErrorCachingMinTTL: 0
        - ErrorCode: 404
          ResponseCode: 200
          ResponsePagePath: /index.html
          ErrorCachingMinTTL: 0
      PriceClass: PriceClass_100

Key configuration points

RegionalDomainName not DomainName

Always use WebsiteBucket.RegionalDomainName (e.g. bucket.s3.us-west-2.amazonaws.com) when configuring an S3 origin with OAC. Using the global DomainName can cause redirect loops.

PriceClass_100

CloudFront price classes control which edge locations serve your content. PriceClass_100 covers North America and Europe — the right choice for most US-based businesses. PriceClass_All includes Asia/Pacific/South America but costs more.

http2and3

Enables HTTP/2 and HTTP/3 (QUIC) — better performance for browsers that support it.

Route 53 DNS Setup

Since the domain is registered in Route 53, nameservers were updated via CLI:

aws route53domains update-domain-nameservers \
  --domain-name bonefishsoftware.com \
  --region us-east-1 \
  --nameservers \
    Name=ns-1325.awsdns-37.org \
    Name=ns-759.awsdns-30.net \
    Name=ns-1601.awsdns-08.co.uk \
    Name=ns-72.awsdns-09.com

Two Alias records point the apex domain and www to CloudFront:

aws route53 change-resource-record-sets \
  --hosted-zone-id $ZONE_ID \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "bonefishsoftware.com",
        "Type": "A",
        "AliasTarget": {
          "HostedZoneId": "Z2FDTNDATAQYW2",
          "DNSName": "d39qxh6q0wxdkd.cloudfront.net",
          "EvaluateTargetHealth": false
        }
      }
    }]
  }'

Z2FDTNDATAQYW2 is the fixed Hosted Zone ID for all CloudFront distributions — not specific to yours. Always use this value for CloudFront A alias records.

Deployment Order

The order matters because each stack depends on outputs from the previous:

1. Create Route 53 hosted zone
   → Get nameservers, update domain registrar

2. Deploy ACM certificate stack (us-east-1)
   → Add DNS validation CNAMEs to Route 53
   → Wait for ISSUED status (~2–5 min once DNS propagates)

3. Deploy website stack (us-west-2)
   → Pass CertificateArn as parameter
   → Outputs: BucketName, DistributionId, DistributionDomain

4. Deploy pipeline stack (us-west-2)
   → Pass BucketName + DistributionId from step 3

Gradual Cutover Strategy

Rather than blocking on the ACM cert, the website.yml template supports deploying without a cert first:

Parameters:
  CertificateArn:
    Type: String
    Default: ''   # ← Leave blank for initial deploy

Conditions:
  HasCustomDomain: !And
    - !Not [!Equals [!Ref CertificateArn, '']]
    - !Not [!Equals [!Ref DomainName, '']]

This lets you deploy the full CloudFront + S3 stack immediately, get the CloudFront URL (*.cloudfront.net), test it, and then update the stack with the cert ARN once it's issued — no downtime, no waiting.

SES DKIM Records

For outbound email from noreply@bonefishsoftware.com, three DKIM CNAME records were added to Route 53:

jbly6mlsiqbi6h7rnnfthdfkiaxzmvjn._domainkey.bonefishsoftware.com
  → jbly6mlsiqbi6h7rnnfthdfkiaxzmvjn.dkim.amazonses.com

xj7cx3tujwzexkmsxmfruyannxq3sevj._domainkey.bonefishsoftware.com
  → xj7cx3tujwzexkmsxmfruyannxq3sevj.dkim.amazonses.com

fyee6qf6o4fzqiolzxl2dyd4rjboqw4l._domainkey.bonefishsoftware.com
  → fyee6qf6o4fzqiolzxl2dyd4rjboqw4l.dkim.amazonses.com

These allow SES to cryptographically sign outbound emails, which improves deliverability and prevents spoofing.

React + Vite + TypeScript + Tailwind CSS v4 — Project Setup

Josh Blair — Thu, 21 May 2026 00:05:15 +0000

Overview

This article covers scaffolding a production-ready React single-page application using Vite, TypeScript, and Tailwind CSS v4. This is the frontend that gets built into static assets and served from S3 + CloudFront.

Tech Choices

Vite over Create React App

CRA is deprecated. Vite is the modern standard — it uses native ES modules for near-instant dev server startup and produces an optimized production build via Rollup.

TypeScript

Type safety catches bugs at compile time instead of runtime. The CloudFormation templates and the site itself are both infra-as-code; TypeScript gives the same discipline on the frontend.

Tailwind CSS v4

Tailwind v4 (released 2024) is a ground-up rewrite. Key changes from v3:

No tailwind.config.js — theme customization moves into CSS via @theme in your stylesheet
No PostCSS config file — use the @tailwindcss/vite Vite plugin instead
CSS-first configuration — design tokens are CSS custom properties

Scaffolding

# Create project with react-ts template
npm create vite@latest . -- --template react-ts

# Install routing and Tailwind
npm install react-router-dom
npm install -D tailwindcss @tailwindcss/vite

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

The @tailwindcss/vite plugin replaces the old PostCSS setup. No postcss.config.js needed.

src/index.css

/* Google Fonts import MUST come before @import "tailwindcss" */
@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&display=swap');
@import "tailwindcss";

/* Custom design tokens via @theme (Tailwind v4 CSS-first config) */
@theme {
  --color-bg: #111318;
  --color-surface: #1C2028;
  --color-accent: #00D4FF;
  --color-text: #F0F4F8;
  --color-text-muted: #8B95A3;
  --color-border: #2A3040;
  --font-sans: 'Space Grotesk', system-ui, sans-serif;
}

body {
  background-color: #111318;
  color: #F0F4F8;
  font-family: 'Space Grotesk', system-ui, sans-serif;
  margin: 0;
}

#root {
  min-height: 100dvh;
  display: flex;
  flex-direction: column;
}

Gotcha: In Tailwind v4, @import "tailwindcss" expands to real CSS. Any @import url(...) (like Google Fonts) must appear before it or the browser ignores the font import. This caused a CSS warning in the build until we fixed the order.

Project Structure

src/
├── components/
│   ├── Navbar.tsx        # Sticky nav, mobile hamburger, active link highlighting
│   ├── Footer.tsx        # Logo, nav links, LinkedIn + GitHub icons
│   └── SectionHeader.tsx # Reusable section heading (title + subtitle)
├── pages/
│   ├── Home.tsx          # Hero, featured services, cert strip, CTA banner
│   ├── Services.tsx      # Full 6-card service grid
│   ├── Technologies.tsx  # Grouped tech badges + certifications
│   ├── Portfolio.tsx     # Placeholder project cards
│   ├── Team.tsx          # Bio card with photo, certs, social links
│   └── Contact.tsx       # Form → API Gateway fetch
├── data/
│   ├── services.ts       # Service card data (title, description, icon)
│   ├── technologies.ts   # Tech groups + certifications
│   └── team.ts           # Team member data
├── App.tsx               # BrowserRouter + route config
├── main.tsx              # React DOM root
└── index.css             # Global styles + Tailwind v4 config

Data-driven content

Rather than hardcoding content in page components, all repeated content lives in typed data files:

// src/data/services.ts
export interface Service {
  id: string;
  title: string;
  description: string;
  icon: string;
}

export const services: Service[] = [
  {
    id: 'eda-serverless',
    title: 'Event-Driven Architecture & Serverless',
    description: 'Architect decoupled, resilient systems using SQS, SNS, EventBridge, and Lambda...',
    icon: '⚡',
  },
  // ...
];

This makes it trivial to add, update, or reorder content without touching component markup.

Routing

React Router v7 handles client-side routing:

// src/App.tsx
import { BrowserRouter as Router, Routes, Route, Navigate } from 'react-router-dom';

export default function App() {
  return (
    <Router>
      <Navbar />
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/services" element={<Services />} />
        <Route path="/technologies" element={<Technologies />} />
        <Route path="/portfolio" element={<Portfolio />} />
        <Route path="/team" element={<Team />} />
        <Route path="/contact" element={<Contact />} />
        <Route path="*" element={<Navigate to="/" replace />} />
      </Routes>
      <Footer />
    </Router>
  );
}

SPA Routing on CloudFront

Because React Router handles navigation client-side, all URLs (/services, /team, etc.) point to the same index.html. When a user navigates directly to https://bonefishsoftware.com/team, S3 returns a 403 (key doesn't exist). CloudFront must be configured to map 403 and 404 errors back to index.html:

# In website.yml CloudFormation
CustomErrorResponses:
  - ErrorCode: 403
    ResponseCode: 200
    ResponsePagePath: /index.html
    ErrorCachingMinTTL: 0
  - ErrorCode: 404
    ResponseCode: 200
    ResponsePagePath: /index.html
    ErrorCachingMinTTL: 0

Without this, refreshing any non-root page returns a CloudFront error page.

Design System

Color palette (dark charcoal + electric cyan):

Token	Hex	Usage
`bg`	`#111318`	Page background
`surface`	`#1C2028`	Cards, panels
`surface-2`	`#232936`	Nested surfaces
`accent`	`#00D4FF`	Cyan highlights, links, active states
`text`	`#F0F4F8`	Primary text
`text-muted`	`#8B95A3`	Secondary text, descriptions
`border`	`#2A3040`	Card borders, dividers

Font: Space Grotesk — a modern geometric sans-serif that feels technical but approachable.

Logo Integration

The company logo is an SVG with a transparent background. The white stripe visible in the logo is part of the Colorado flag design — it's not a background fill.

Using the SVG directly in the Navbar (instead of PNG) means:

Zero white-box artifact on the dark background
Infinitely scalable — looks sharp at any size
Small file size

// Navbar.tsx
<NavLink to="/">
  <img src="/logo.svg" alt="Bonefish Software" className="h-10 w-auto" />
</NavLink>

The no-text variant (/logo-icon.svg) is used in the footer where horizontal space is tighter.

Production Build

npm run build
# → tsc -b && vite build
# → dist/ (index.html + hashed JS/CSS bundles)

Build output for this site:

dist/index.html                   0.64 kB │ gzip:  0.39 kB
dist/assets/index-[hash].css     22.21 kB │ gzip:  4.91 kB
dist/assets/index-[hash].js     257.69 kB │ gzip: 81.09 kB

The entire site gzips to under 86 kB — fast on any connection.

Building a Production Company Website on AWS — Project Overview

Josh Blair — Thu, 21 May 2026 00:05:06 +0000

What We Built

This series documents the end-to-end process of designing, building, and deploying a production company website for a software and cloud consulting business. The result is a modern, fully serverless stack with automated CI/CD deployments — built intentionally to demonstrate and practice the AWS services I use professionally.

Tech stack at a glance:

Layer	Technology
Frontend	React 18 + Vite + TypeScript + Tailwind CSS v4
Hosting	Amazon S3 + CloudFront (CDN)
DNS & TLS	Route 53 + ACM (SSL/TLS certificate)
CI/CD	GitHub + AWS CodePipeline + CodeBuild
Contact API	API Gateway (HTTP) + AWS Lambda (Python)
Data storage	Amazon DynamoDB
Email delivery	Amazon SES
IaC	AWS CloudFormation + AWS SAM

Architecture Overview

CI/CD Pipeline

Every push to the main branch on GitHub automatically triggers a full build and deploy:

Articles in This Series

#	Article	What it covers
1	Project Overview (this article)	Full architecture, stack decisions, what we're building
2	React + Vite + Tailwind Setup	Scaffolding the SPA, routing, design system, component structure
3	Static Site Hosting on AWS	S3, CloudFront with OAC, ACM, Route 53 DNS, CloudFormation
4	CI/CD with CodePipeline & CodeBuild	GitHub connection, pipeline stages, buildspec.yml, IAM roles
5	Serverless Contact Form	Lambda, API Gateway, DynamoDB, SES, CORS, SAM deployment

Key Design Decisions

Why React + Vite (not Next.js)?

Next.js is a great framework, but for a static marketing site, it's overhead. Vite produces a clean static build (dist/) that S3 + CloudFront serves perfectly. The site has no server-side rendering requirements. Vite also gives faster local dev iteration.

Why S3 + CloudFront (not Amplify or Vercel)?

This project is intentionally built on "raw" AWS primitives — CodePipeline, CloudFormation, S3, CloudFront — rather than abstracted platforms. The goal is to learn and demonstrate AWS services used in real enterprise projects.

Why CloudFormation (not CDK or Terraform)?

CloudFormation is the AWS-native tool that every AWS practitioner encounters. Understanding it directly — before abstracting to CDK — builds a stronger mental model of what's actually being deployed.

Why separate ACM cert in us-east-1?

CloudFront is a global service and requires ACM certificates to be provisioned specifically in us-east-1, regardless of where your other resources live. This is an AWS constraint, not a design choice.

Why CloudFront OAC (not OAI)?

Origin Access Control (OAC) is the modern replacement for Origin Access Identity (OAI). It supports all S3 operations, works with SSE-KMS encrypted buckets, and uses AWS SigV4 signing.

Repository Structure

bonefishsoftware.com/
├── src/                    # React source
│   ├── components/         # Navbar, Footer, SectionHeader
│   ├── pages/              # Home, Services, Technologies, Portfolio, Team, Contact
│   └── data/               # services.ts, technologies.ts, team.ts
├── public/                 # Static assets (logo, sitemap, robots.txt)
├── lambda/
│   └── contact/            # Python Lambda — contact form handler
├── infra/
│   ├── acm/                # certificate.yml (deploy to us-east-1)
│   └── stacks/
│       ├── website.yml     # S3 + CloudFront (deploy to us-west-2)
│       ├── pipeline.yml    # CodePipeline + CodeBuild (deploy to us-west-2)
│       └── contact-api.yml # SAM — API Gateway + Lambda + DynamoDB (deploy to us-west-2)
├── docs/                   # This documentation
├── buildspec.yml           # CodeBuild build spec
└── index.html              # Vite entry point with SEO meta tags

Forem: Josh Blair

Zero-Secret CI/CD: GitHub Actions + OIDC on AWS (Part 6)

Zero-Secret CI/CD: GitHub Actions + OIDC on AWS (Part 6)

How GitHub Actions OIDC Works

Setting Up the Trust (Once Per Account)

In the Workflow

CI: Three Parallel Jobs on Every Pull Request

.NET Build and Test

Python Pipeline Tests

TypeScript Check, Lint, and Build

Deploy: Two Sequential Jobs on Every Push to Main

Job 1: SAM Build and Deploy

Job 2: Frontend Build and Sync

CloudFront + S3 Hosting

The Result

The Complete Series

Building the React Frontend: Document Library and Chat UI (Part 5)

Building the React Frontend: Document Library and Chat UI (Part 5)

Tech Choices

Auth: Amplify and the Token Interceptor

App Initialization

Document Upload: The Two-Step Flow

Status Polling: React Query's refetchInterval

Chat: Local State in useChat

Rendering Citations

What's Missing for Production

What's Next

RAG and Vector Search with pgvector and Amazon Bedrock (Part 4)

RAG and Vector Search with pgvector and Amazon Bedrock (Part 4)

What RAG Actually Does

Embeddings with Bedrock Titan Embed v2

Schema: Storing Vectors in Postgres

The IVFFlat Index

Inserting Vectors from Python

Similarity Search

The RAG Prompt

Citations as First-Class Data

Limitations and What Production Would Change

What's Next

Serverless Document Pipelines with AWS Step Functions (Part 3)

Serverless Document Pipelines with AWS Step Functions (Part 3)

The Trigger: S3 → EventBridge → Step Functions

The State Machine

Stage 1: ExtractText

Stage 2: ChunkText

Stage 3: GenerateEmbeddings (The Map State)

Stage 4: ExtractMetadata

Stages 5 and 6: MarkReady and MarkFailed

Why Express Workflows, Not Standard

The Real Argument for Step Functions

What's Next

Multi-Tenant Auth with Cognito and PostgreSQL Row-Level Security (Part 2)

Multi-Tenant Auth with Cognito and PostgreSQL Row-Level Security (Part 2)

The Full Trust Chain

Layer 1: Cognito — Injecting tenantId into the JWT

The Pre-Token Generation Lambda

Layer 2: API Gateway — JWT Validation for Free

Layer 3: Lambda — Extracting the Claim

Layer 4: PostgreSQL Row-Level Security

The Problem with WHERE Clauses

Setting Up RLS

Setting the Session Variable

The BYPASSRLS Gotcha

Layer 5: S3 Key Prefix

Why Three Layers?

Seeing It in Action

What's Next

Building a Multi-Tenant AI Document Platform on AWS (Part 1: Architecture)

Building a Multi-Tenant AI Document Platform on AWS (Part 1: Architecture)

What Sift Does

The Full Architecture

Why Each Service?

Aurora Serverless v2 with pgvector

Step Functions Express Workflows

Amazon Bedrock

Amazon Cognito

AWS SAM over CDK

Multi-Tenancy: Three Layers of Isolation

Cost Breakdown

AWS Well-Architected Alignment

Status Polling: React Query's `refetchInterval`

Chat: Local State in `useChat`

Key lesson: `AWS::Serverless::HttpApi` vs `AWS::ApiGatewayV2::Api`