DEV Community: Saddam Azad

Enterprise Authentication with AWS Blocks

Saddam Azad — Tue, 28 Jul 2026 03:03:12 +0000

_Note: AWS Blocks is currently in preview and the API is subject to change. _

A login form is not authentication. Federation, multi-tenancy, RBAC, MFA, audit logging, GDPR compliance, rate limiting, CSRF protection, multi-account support, and transactional email -- that is authentication.

Most teams build auth incrementally. Add social login, then realize you need MFA. Add MFA, then discover you need per-tenant roles. Add roles, then panic about GDPR. Each layer is bolted on, each integration point is hand-rolled, each new requirement means rewriting the last thing you built.

AWS Blocks takes the opposite approach. The Building Blocks provide all of it, wired together from day one. One TypeScript file. Typed APIs. Infrastructure compiles from code.

This article walks through a complete enterprise auth system -- the architecture, the code, and the patterns that make it work. A reference implementation accompanies this article at github.com/saddam-azad/aws-blocks-auth.

Architecture Overview

The full system in one sketch:

Browser
  │
  ├─── email/password ──→ AuthCognito ──→ Cognito User Pool
  │                         │
  │                    session cookie (auth_*)
  │                         │
  └─── social login ───→ AuthOIDC ─────→ Google / GitHub
                            │
                       session cookie (oidc_*_session)
                            │
                      ┌─────┴─────┐
                      │  resolve   │  ← tries Cognito first,
                      │   Auth     │     falls back to OIDC
                      │   User()   │
                      └─────┬─────┘
                            │
                     Unified API Namespace
                            │
               ┌────────────┼────────────┐
               │            │            │
        DistributedTable  KVStore    EmailClient
          (orgs, users,   (sessions,  (SES delivery,
           audit log)     rate limits) React Email)

Two separate Building Blocks, two separate session stores, one unified API layer. The frontend does not know or care which provider authenticated the user.

Concern	AWS Blocks
Federation	AuthCognito + AuthOIDC
Multi-tenancy	DistributedTable + `__org` cookie
RBAC	Inline role checks + Pinia computed props
MFA	Cognito state machine (SMS/TOTP/Email)
Audit logging	DistributedTable with TTL
CSRF	`requireSameSite()` + SameSite cookies
Rate limiting	KVStore-based sliding window
GDPR	Consent, export, cascade delete
Multi-account	Session group KVStore
Transactional email	EmailClient + React Email

Prerequisites

AWS Blocks installed. Nuxt 4 SPA (the reference uses Nuxt, but the backend patterns are framework-agnostic). Node.js and bun.

Local dev works without an AWS account. No credentials required. No deployment required.

blocksapp/
├── aws-blocks/
│   ├── index.ts           # All backend logic (~1300 lines)
│   ├── index.handler.ts   # Lambda entry point
│   └── index.cdk.ts       # CDK infrastructure
├── app/
│   ├── stores/            # Pinia stores (auth, org, accounts)
│   ├── composables/       # Stateless helpers
│   ├── middleware/         # Route guards
│   ├── layouts/            # 5 layouts
│   ├── pages/              # File-based routing
│   └── plugins/            # Auth bootstrap + CSRF
├── emails/                 # React Email templates
└── server/middleware/       # Security headers

File	Purpose
`aws-blocks/index.ts`	All backend logic
`app/stores/auth.ts`	Unified auth store
`app/stores/org.ts`	Org + RBAC store
`app/stores/accounts.ts`	Multi-account store
`emails/*.tsx`	React Email templates
`server/middleware/security.ts`	Security headers

Local Development Setup

Most auth systems require a deployed Cognito User Pool, registered OAuth apps, and real SMS delivery before you can run a single npm run dev.

AWS Blocks inverts that. Social login works locally without real OAuth credentials. Cognito verification codes print to the console. Set your env vars and the real providers kick in automatically.

Social Login -- Env-Based Switching

const socialAuth = new AuthOIDC(scope, 'oidc', {
  providers: [
    process.env.GOOGLE_CLIENT_ID
      ? google({ clientId: () => googleClientId.get(), clientSecret: () => googleClientSecret.get() })
      : stubIdp({ name: 'google' }),
    process.env.GITHUB_CLIENT_ID
      ? github({ clientId: () => githubClientId.get(), clientSecret: () => githubClientSecret.get() })
      : stubIdp({ name: 'github' }),
  ],
});

When env vars are absent, stubIdp() handles the OAuth flow in-process. Real PKCE, real token exchange, real session cookie -- just a deterministic local user instead of a human.

When you set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, the real Google provider activates. No code changes. No restart required.

Cognito Mock -- Console Delivery

const auth = new AuthCognito(scope, 'cognito', {
  signInWith: ['email'],
  mfa: 'optional',
  mfaTypes: ['SMS', 'TOTP', 'EMAIL'],
  groups: ['users', 'admins'],
  ...(process.env.BLOCKS_SANDBOX !== 'true' && {
    codeDelivery: async (destination, code, purpose) => {
      console.log(`\n📧 ${purpose} code for ${destination}: ${code}\n`);
    },
  }),
});

In local mode, verification and MFA codes print to the terminal. No AWS SES or SNS needed. Set BLOCKS_SANDBOX=true and real delivery kicks in.

The codeDelivery callback is the bridge between local dev and production. It intercepts Cognito's verification flow and gives you the code where you can see it.

Dev Scripts

Script	What it does
`bun run dev`	Start backend + frontend with hot reload
`bun run sandbox`	Deploy to AWS sandbox (real resources)
`bun run email:dev`	Preview email templates locally
`bun run test:e2e`	Run end-to-end tests

The dev script starts the Blocks dev server on port 4100 and the Nuxt frontend on port 3100. Hot reload works for both backend and frontend simultaneously.

The Federation Layer

Cognito handles email/password and MFA well. OIDC handles social login well. No single tool does both well.

The naive approach gives you two login flows, two session stores, and two user objects. The frontend has to know which provider authenticated the user. Every API method has to branch on provider type.

AWS Blocks solves this with a single function.

The Core Pattern

Here is the simplest version:

async function resolveAuthUser(context: any) {
  try {
    return await auth.requireAuth(context);
  } catch {
    return await socialAuth.requireAuth(context);
  }
}

That works. But the frontend has to check both providers on every request. The key is the authType short-circuit:

async function resolveAuthUser(context: any, authType?: 'cognito' | 'oidc') {
  if (authType === 'oidc') return await socialAuth.requireAuth(context);
  if (authType === 'cognito') return await auth.requireAuth(context);
  try {
    return await auth.requireAuth(context);
  } catch {
    return await socialAuth.requireAuth(context);
  }
}

When authType is known -- from the activeAuthType cookie -- it short-circuits to the right provider. Otherwise it tries Cognito first and falls back to OIDC.

Wiring It In

Every API method calls resolveAuthUser() instead of calling either block directly:

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getProfile() {
    const user = await resolveAuthUser(context);
    return { username: user.username, email: user.email };
  },
  async adminOnly() {
    const user = await auth.requireRole(context, 'admins');
    return { message: `Welcome, admin ${user.username}` };
  },
}));

The frontend never branches on provider type in API calls. It calls api.getProfile() and gets a consistent user object back.

The Cookie Strategy

Three cookies work together:

Cookie	Purpose	Set by
`auth_` / `oidc__session`	Opaque session pointer (HMAC-signed)	AuthCognito / AuthOIDC
`__group`	Browser group ID for multi-account	Application code
`activeAuthType`	`'cognito'` or `'oidc'`	Application code

Notice something important.

activeAuthType is a plain JS-readable cookie. No crypto, no HMAC, no server-side lookup. It carries no sensitive data. It just tells init() which provider to check first and signOut() which provider to call.

Dynamic Cookie Security

Cookie security attributes are computed dynamically per request:

function cookieAttrs(context: any) {
  const sec = buildCookieSecurityAttrs({
    crossDomain: process.env.BLOCKS_SANDBOX === 'true',
    isLocalhost: isLoopbackRequest(context),
  });
  return `Path=/; HttpOnly; ${sec}`;
}

Environment	SameSite	Secure	Partitioned
Local dev (HTTP)	Lax	no	no
Production (HTTPS)	Lax	yes	no
Cross-domain	None	yes	yes

One function. Three environments. No manual configuration. buildCookieSecurityAttrs from @aws-blocks/auth-common/cookies handles the distinction automatically.

Multi-Tenancy and Organization Management

Organizations are the tenant boundary. All data queries are scoped to the active org via the __org cookie.

The Data Model

Three DistributedTables with GSIs for lookups:

const orgs = new DistributedTable(scope, 'orgs', {
  schema: orgSchema,
  key: { partitionKey: 'orgId' },
  indexes: {
    bySlug: { partitionKey: 'slug' },
    byCreatedBy: { partitionKey: 'createdBy', sortKey: 'createdAt' },
  },
});

Table	Schema	Key GSIs
`orgs`	orgId, name, slug, createdAt, createdBy	bySlug, byCreatedBy
`orgMemberships`	orgId, userId, role, joinedAt, invitedBy	byUser
`orgInvitations`	orgId, email, role, invitedBy, invitedAt, token, expiresAt	byToken, byEmail

The role field is an enum: owner > admin > member. The hierarchy is enforced inline in API methods.

Role Enforcement

Each org API method checks the caller's role directly:

async updateMemberRole(orgId: string, userId: string, role: string) {
  requireSameSite(context);
  const user = await resolveAuthUser(context);
  const membership = await orgMemberships.get({ orgId, userId: user.username });
  if (!membership || membership.role !== 'owner') {
    throw Object.assign(new Error('Only the owner can change roles'), { status: 403 });
  }
  // ...
}

There is no middleware for RBAC. There is no decorator. There is no reflection. Each method reads the membership, checks the role, and throws if the caller lacks permission. It is verbose. It is clear. It is hard to get wrong.

The Invitation Flow

Invite by email, accept via token-based link:

Owner or admin calls inviteToOrg(orgId, email, role)
Backend validates role hierarchy, creates invitation with 7-day expiry, sends email
Invitee clicks link in email, lands on /accept-invite?token=...
Login or signup, then auto-accept and redirect to org page

Rate-limited to 10 invitations per minute per user. Resend and cancel supported.

Frontend RBAC

The Pinia org store exposes computed properties:

const currentRole = computed(() => currentOrgData.value?.role ?? null)
const isMember = computed(() => currentRole.value !== null)
const isOwner = computed(() => currentRole.value === 'owner')
const isAdmin = computed(() => currentRole.value === 'owner' || currentRole.value === 'admin')

Pages use v-if for conditional rendering:

<UButton v-if="org.isAdmin" label="Invite" />
<UButton v-if="org.isOwner" label="Delete Org" color="error" />

No provider-specific logic in templates. No role-checking utility functions. Just computed properties and v-if.

Multi-Account Session Switching

Each auth block issues one session cookie per sign-in. Users with work and personal accounts need to switch without logging out.

The Session Group Pattern

A __group cookie identifies the browser. Each login registers a session in the group with its full auth cookie string and authType:

const sessionGroups = new KVStore<{
  sessions: Array<{
    sessionId: string;
    username: string;
    linkedAt: number;
    cookie: string;
    authType: 'cognito' | 'oidc';
  }>;
  activeSessionId: string;
}>(scope, 'session-groups', {});

The Flows

Register: after sign-in, the frontend calls registerSession(authType). Stores the session ID and provider type in the group. Caps at 3 linked accounts per browser.

Switch: switchSession(targetSessionId) swaps the cookie via Set-Cookie headers using cookieAttrs(). Returns { success, username, authType }. Hard page refresh destroys all Pinia state and reinitializes with the new cookie.

Unlink: removes a session from the group. Blocks unlinking the active session.

Sign-out: removes current session from the group. Only signs out the active provider.

The authType per session is critical. It tells the frontend which provider to call signOut() on.

Quick-Switch from the Login Page

Users can switch accounts from the login page without re-authenticating:

const sessions = await api.getGroupSessions();
// User clicks a session button
const result = await api.quickSwitchSession(sessionId);
setCookie('activeAuthType', result.authType);
window.location.href = '/dashboard';

The login page shows linked accounts with a one-click switch. No credential re-entry. No OAuth redirect.

Security Infrastructure

CSRF, rate limiting, audit logging, and input validation -- wired into every mutating API method. Not optional. Not configurable. Always on.

CSRF Protection

function requireSameSite(context: any) {
  const customHeader = context.request.headers.get('x-requested-with');
  if (customHeader) return;
  const origin = context.request.headers.get('origin');
  const referer = context.request.headers.get('referer');
  if (!origin && !referer) return;
}

Cross-origin JavaScript cannot set custom headers without CORS preflight. Requiring the x-requested-with header provides CSRF protection. SameSite cookies are the primary defense. This is defense-in-depth.

The header is injected by a Nuxt client plugin on every fetch:

// plugins/request-guard.client.ts
$fetch.defaults.headers['x-requested-with'] = 'XMLHttpRequest';

Rate Limiting

KVStore-based sliding window:

async function checkRateLimit(
  scope: string, identifier: string,
  maxAttempts: number, windowMs: number
) {
  const key = `${scope}:${identifier}`;
  const now = Date.now();
  const existing = await rateLimits.get(key);

  if (!existing || now > existing.expiresAt) {
    await rateLimits.put(key, { count: 1, expiresAt: now + windowMs });
    return { allowed: true };
  }
  if (existing.count >= maxAttempts) {
    return { allowed: false, retryAfterMs: existing.expiresAt - now };
  }
  await rateLimits.put(key, { count: existing.count + 1, expiresAt: existing.expiresAt });
  return { allowed: true };
}

Currently wired into inviteToOrg at 10 requests per minute per user. Expandable to sign-in, password reset, and account deletion.

Audit Logging

Every important mutation writes an audit event:

async function recordAuditEvent(
  eventType: string, userId: string, context: any,
  opts?: { targetUserId?: string; orgId?: string; metadata?: Record<string, unknown> }
) {
  const eventId = Date.now().toString(36) + crypto.randomBytes(8).toString('hex');
  const ip = context.request.headers.get('x-forwarded-for') || 'unknown';
  await auditLog.put({
    eventId, timestamp: Date.now(), eventType, userId,
    targetUserId: opts?.targetUserId, orgId: opts?.orgId,
    ip, metadata: opts?.metadata,
    expiresAt: Math.floor(Date.now() / 1000) + 90 * 24 * 60 * 60,
  });
}

90-day TTL. Queryable by user, org, and date range. Called from 15+ API methods including session management, org operations, GDPR actions, and auth events.

Input Validation

Zod schemas on every API method input:

const parsedEmail = z.string().email().parse(email);
const parsedName = z.string().min(1).max(100).parse(name);
const parsedOrgId = z.string().uuid().parse(orgId);

Invalid inputs throw before any business logic runs. No SQL injection, no malformed data, no surprises.

Security Headers

Server middleware sets headers on every response:

res.setHeader('X-Content-Type-Options', 'nosniff')
res.setHeader('X-Frame-Options', 'DENY')
res.setHeader('X-XSS-Protection', '1; mode=block')
res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin')
if (process.env.NODE_ENV === 'production') {
  res.setHeader('Strict-Transport-Security', 'max-age=63072000; includeSubDomains; preload')
  res.setHeader('Content-Security-Policy', "default-src 'self'; ...")
}

HSTS and CSP are only applied in production. Local dev runs without them to avoid breaking hot-reload.

Compliance and GDPR

Privacy is a first-class concern. Consent recording, data export, and account deletion are built into the API layer.

Consent Recording

async recordConsent(consentType: string, granted: boolean) {
  requireSameSite(context);
  const user = await resolveAuthUser(context);
  const existing = await userConsents.get(user.username) || [];
  existing.push({ consentType, granted, timestamp: Date.now(), ip: '...' });
  await userConsents.put(user.username, existing);
  await recordAuditEvent('consent_' + (granted ? 'granted' : 'revoked'), user.username, context);
  return { success: true };
}

Consent is stored per user with timestamp and IP. The audit log captures the event. The frontend shows a ConsentCheckbox on signup with links to the privacy policy.

Data Export

async exportUserData() {
  const user = await resolveAuthUser(context);
  return {
    profile: await users.get({ userId: user.username }),
    consents: await userConsents.get(user.username) || [],
    memberships: await orgMemberships.query('byUser', { userId: user.username }),
    auditEvents: await auditLog.query('byUser', { userId: user.username }),
  };
}

One call returns everything. Profile, consents, memberships, audit events. The user can download it, review it, or send it to a regulator.

Account Deletion

Cascade delete across all stores:

async deleteAccount() {
  requireSameSite(context);
  const user = await resolveAuthUser(context);
  const memberships = await orgMemberships.query('byUser', { userId: user.username });
  for (const m of memberships) {
    await orgMemberships.delete({ orgId: m.orgId, userId: user.username });
  }
  await userConsents.delete(user.username);
  await auth.deleteUser(context);
  await recordAuditEvent('account_deleted', user.username, context);
  return { success: true };
}

Remove from all orgs. Remove from all sessions. Remove consents. Delete the Cognito user. Record the event. The frontend requires typing "DELETE" to confirm.

Transactional Email

Branded, responsive emails delivered through Amazon SES. Templates built with React Email. Rendered to HTML on the server, sent via the EmailClient block.

The Setup

Five templates in emails/:

Template	Trigger	Content
`ConfirmationEmail`	Sign-up	Verification code
`PasswordResetEmail`	Password reset	Reset code
`OrgInvitationEmail`	Org invite	Accept button + org name
`NewSignInEmail`	Sign-in	Timestamp + IP + warning
`PasswordChangedEmail`	Password change	Timestamp + IP + warning

Lazy Initialization

let _emailClient: EmailClient | null = null;
async function getEmailClient(): Promise<EmailClient> {
  if (!_emailClient) {
    const from = await emailFromAddress.get();
    const replyTo = await emailReplyToAddress.get();
    _emailClient = new EmailClient(scope, 'email', {
      fromAddress: from,
      replyTo: replyTo ? [replyTo] : undefined,
    });
  }
  return _emailClient;
}

The from and reply-to addresses are stored as AppSetting values. The client initializes once and reuses across requests.

Template Example

The org invitation template:

export function OrgInvitationEmail({ orgName, inviterEmail, inviteUrl }: OrgInvitationEmailProps) {
  return (
    <Html lang="en">
      <Head />
      <Preview>You've been invited to {orgName}</Preview>
      <Body style={main}>
        <Container style={container}>
          <Heading style={h1}>You've been invited</Heading>
          <Text style={text}>
            <strong>{inviterEmail}</strong> has invited you to join <strong>{orgName}</strong>.
          </Text>
          <div style={buttonContainer}>
            <Button href={inviteUrl} style={button}>Accept Invitation</Button>
          </div>
          <Text style={footer}>This invitation expires in 7 days.</Text>
        </Container>
      </Body>
    </Html>
  );
}

Sending

async function doSendInvitationEmail(email: string, orgName: string, inviterEmail: string, token: string) {
  const inviteUrl = `${process.env.APP_URL || 'http://localhost:3000'}/accept-invite?token=${token}`;
  const html = await render(React.createElement(OrgInvitationEmail, { orgName, inviterEmail, inviteUrl }));
  const client = await getEmailClient();
  await client.send({
    to: email,
    subject: `You've been invited to ${orgName}`,
    body: `${inviterEmail} has invited you to join ${orgName}. Accept: ${inviteUrl}`,
    html,
  });
}

The body field is a plain-text fallback for email clients that do not render HTML. The html field is the React Email output.

Security Notifications

Auth events trigger automatic emails:

async recordAuthEvent(eventType: string) {
  const user = await resolveAuthUser(context);
  await recordAuditEvent(parsedType, user.username, context);

  if (parsedType === 'sign_in' || parsedType === 'password_changed') {
    const attributes = await auth.fetchUserAttributes(context);
    if (attributes.email) {
      const html = await render(React.createElement(NewSignInEmail, {
        email: attributes.email, timestamp, ip
      }));
      await client.send({ to: attributes.email, subject: '...', body: '...', html });
    }
  }
  return { success: true };
}

Sign-in notifications include the timestamp and IP address. Password change notifications include the same. Both display a red warning if the action was unauthorized.

Failures are silently caught. Auth operations are never blocked by email issues.

Local Email Preview

Run bun run email:dev to start the React Email dev server. Templates render in the browser with live hot-reload. No SES credentials needed. No email sent.

The Frontend Architecture

Three Pinia stores, three middleware files, and the principle that the frontend never touches auth infrastructure.

The Three Stores

auth.ts -- unified auth. Wraps Cognito and OIDC behind a single interface. init() reads the activeAuthType cookie and checks the correct provider first. signOut() only signs out the active provider.

async function init() {
  const activeType = getCookie('activeAuthType');
  if (activeType === 'oidc') {
    if (await socialAuthApi.checkAuth()) { user = await socialAuthApi.getCurrentUser(); return; }
    if (await authApi.checkAuth()) { user = await authApi.getCurrentUser(); return; }
  } else {
    if (await authApi.checkAuth()) { user = await authApi.getCurrentUser(); return; }
    if (await socialAuthApi.checkAuth()) { user = await socialAuthApi.getCurrentUser(); return; }
  }
  user = null;
}

org.ts -- organizations, members, roles. Exposes isOwner, isAdmin, isMember computed properties. checkOrgAccess() gates /org/* routes.

accounts.ts -- multi-account. loadAccounts(), registerSession(), switchAccount(), unlinkAccount(). The switchAccount() method returns the API result so the frontend can set the activeAuthType cookie before redirect.

The Middleware Chain

auth.global.ts  (every route, org membership check for /org/*)
  └→ admin.ts    (Cognito group check for /admin/*)
  └→ guest.ts    (redirect authenticated users away from auth pages)

auth.global.ts runs on every route. It calls auth.init(), checks authentication, and calls orgStore.checkOrgAccess() for /org/* routes. Named middleware only adds additional checks on top.

Deduplication

A module-level inflight promise prevents concurrent init() calls. When multiple components mount simultaneously and all call init(), only one RPC fires. The others wait for the same promise.

let inflight: Promise<void> | null = null;
async function init() {
  if (inflight) return inflight;
  inflight = (async () => {
    // ... check providers, set user
  })().finally(() => { inflight = null; });
  return inflight;
}

Components access auth.user and auth.isAuthenticated. No redundant network requests. No race conditions between middleware and components.

Five Layouts

Layout	Use for	Sidebar
`default`	Public pages (landing, privacy)	No
`auth`	Login, signup, confirm, forgot	No
`dashboard`	Top-level pages (org list, create org)	No
`org`	Org-scoped pages (members, settings)	Yes
`profile`	User profile pages	Yes

Each layout serves a distinct purpose. The org layout shows a loading spinner while org.rbacLoading is true, then renders RbacUnauthorized if the user is not a member.

Plugins

Plugin	Purpose
`auth.client.ts`	Bootstrap auth on app load, provide `$api`, `$authApi`, `$socialAuthApi`
`request-guard.client.ts`	Inject `x-requested-with` header on every fetch for CSRF

The request-guard plugin runs on every client-side fetch. It sets the custom header that requireSameSite() checks on the backend.

The API Surface

38 methods in one namespace. The backend provides everything the frontend needs.

Category	Methods
Profile	`getProfile`, `authSource`, `setValue`, `getValue`
MFA	`mfaSetup`, `confirmMfaSetup`, `disableMfa`, `getMfaPreferences`
Sessions	`registerSession`, `linkedAccounts`, `switchSession`, `quickSwitchSession`, `unlinkSession`, `getGroupSessions`, `removeCurrentSessionFromGroup`
Organizations	`createOrg`, `listMyOrgs`, `getOrg`, `updateOrg`, `deleteOrg`
Members	`getOrgMembers`, `inviteToOrg`, `removeFromOrg`, `updateMemberRole`, `getOrgInvitations`, `acceptInvitation`
Org scope	`setActiveOrg`, `getActiveOrg`
Security	`recordConsent`, `getConsentStatus`, `exportUserData`, `deleteAccount`, `recordAuthEvent`
Admin	`adminOnly`, `getAuditLog`, `getOrgAuditLog`
Email	`sendConfirmationEmail`, `sendPasswordResetEmail`, `sendOrgInvitationEmail`

Security Wiring

Check	Methods
`requireSameSite()`	12 mutating methods
`requireRateLimit()`	`inviteToOrg` (10/min)
`recordAuditEvent()`	15+ methods
Zod validation	All inputs

Every mutating method calls requireSameSite(). Every sensitive method calls recordAuditEvent(). Every input is validated with Zod. No exceptions.

What You Didn't Build

The reference implementation is ~1300 lines of backend code. Here is what that code does not include:

No Cognito User Pool setup or configuration
No OAuth flow implementation (PKCE, token exchange, callback handling)
No MFA challenge state machine
No session cookie HMAC signing or verification
No CSRF token generation or validation
No rate limiting infrastructure
No audit event storage or querying
No email template rendering or delivery
No role hierarchy enforcement
No invitation token generation or expiry
No cookie security attribute computation
No API namespace transport or client generation

All of that is provided by the Building Blocks. The 1300 lines are your application logic -- the federation glue, the org management, the RBAC checks, the GDPR compliance. Not the infrastructure.

What's Next

Extensible RBAC -- the reference uses hardcoded three-tier roles. An optional resource:action permission system adds custom roles, fine-grained permissions across 6 resources, and a roles management UI. See the RBAC spec in .agents/RBAC.md.
Rate limiting expansion -- sign-in attempts (5/min), password reset (3/min), account deletion (1/hr). The checkRateLimit() function is already built. It needs to be wired into more methods.
Testing -- currently 1 trivial KV smoke test. Security tests (CSRF, rate limiting, session fixation), org tests (privilege escalation, last-owner protection), GDPR tests (consent, export, erasure), and E2E auth tests.
WCAG audit -- keyboard navigation, color contrast, aria labels across all 13 pages.

Learn More

AWS Blocks -- Infrastructure from Code framework
AWS Blocks Authentication -- AWS Auth Building Blocks
aws-blocks-auth -- Reference implementation
React Email -- Email template framework
Nuxt UI -- Vue component library

Chat with Your Documents: Building a RAG Pipeline with AWS Blocks

Saddam Azad — Sun, 19 Jul 2026 17:01:26 +0000

One of the first features users expect from an AI application is deceptively simple:

Upload a document. Ask questions. Get accurate answers.

Whether you're building an internal knowledge portal, customer support assistant, or documentation search, the workflow is remarkably similar.

Users upload files. The application extracts the text, splits it into chunks, generates embeddings, retrieves the most relevant passages, and uses them to ground an LLM's response.

This pattern -- known as Retrieval-Augmented Generation (RAG) -- has become the standard way of building AI applications that answer questions using private data.

The individual AWS services are excellent.

The challenge is assembling them into a cohesive developer experience.

A typical implementation requires wiring together S3, document extraction, vector storage, Bedrock, authentication, APIs, background jobs, IAM permissions, and frontend clients. Then you need to figure out how to develop all of it locally without deploying every few minutes.

This is exactly the problem AWS Blocks is designed to solve.

Instead of treating infrastructure, backend code, and frontend clients as separate projects, AWS Blocks treats them as different views of the same application.

Let's build a complete "Chat with your Documents" application and see how that changes the development experience.

What we're building

Our application will support the complete document lifecycle.

             Upload Document
                    │
                    ▼
             FileBucket Block
                    │
                    ▼
          Background Extraction
                    │
                    ▼
         KnowledgeBase Block
          ┌─────────┴─────────┐
          │                   │
    Chunk Documents     Create Embeddings
          │                   │
          └─────────┬─────────┘
                    │
               S3 Vectors
                    │
                    ▼
          Semantic Retrieval
                    │
                    ▼
            Amazon Bedrock
                    │
                    ▼
          Grounded AI Response

The result is a chatbot that only answers questions using the documents your users have uploaded -- and can cite exactly where those answers came from.

Prerequisites

This article assumes familiarity with:

TypeScript and Node.js
AWS concepts (S3, Lambda, IAM)
Vector embeddings and semantic search
Amazon Bedrock (or similar LLM providers)

No prior experience with AWS Blocks is required. We'll cover everything from scratch.

Getting started

We'll start with a new AWS Blocks application.

npx @aws-blocks/create-blocks-app chat-with-documents
cd chat-with-documents

Check the aws-blocks/ directory where you'll define your Building Blocks, typed APIs, and infrastructure. Throughout this article, we'll focus on extending that project to build a complete Retrieval-Augmented Generation (RAG) application.

Before writing any code, install the AWS Blocks skill from the Agent Toolkit for AWS.

npx skills add https://github.com/aws/agent-toolkit-for-aws --skill aws-blocks

The skill gives your AI coding assistant access to the latest AWS Blocks guidance, validated implementation patterns, common pitfalls, and best practices. Since AWS Blocks is evolving quickly, using the skill helps ensure code generation stays aligned with the current APIs and recommended architecture.

With the project scaffolded and the skill installed, we're ready to build the document ingestion and retrieval pipeline.

Project structure

One of the goals of AWS Blocks is keeping infrastructure, backend APIs, and frontend code together.

Instead of separating CDK projects, Lambda functions, generated SDKs, and frontend applications into different repositories, AWS Blocks encourages a single project where each feature is built as a vertical slice.

A project for this article might look something like this:

chat-with-documents/

├── aws-blocks/
│   ├── scripts/
│   ├── client.js
│   ├── index.ts
│   ├── index.cdk.ts             
│   ├── index.handler.ts         
│   └── package.json
│
├── src/app/                        # Frontend: Nextjs/Nuxt
│   ├── components/
│   ├── composables/
│   ├── pages/
│   └── plugins/
│
├── knowledge/
│   └── api-reference.md
│
├── uploads/
│   └── (raw user uploads)
│
├── AGENTS.md
├── cdk.json
├── next.config.ts                  # or nuxt.config.ts
├── package.json
└── tsconfig.json

Each directory has a single responsibility.

Directory	Purpose
`aws-blocks/`	Defines your Building Blocks, typed APIs, and the infrastructure required to run them.
`src/app/`	The Nuxt frontend: pages, components, composables, and plugins.
`knowledge/`	Documents that are indexed into the Knowledge Base for semantic retrieval.
`uploads/`	Temporary storage for user-uploaded files before they're extracted and indexed.

Schema and document storage

Every document that flows through the pipeline needs metadata -- file name, upload status, extraction results, workspace ownership.

AWS Blocks uses Zod schemas to define typed tables that work locally and in DynamoDB.

import { z } from 'zod'
import { DistributedTable } from '@aws-blocks/blocks'

const documentMetaSchema = z.object({
  documentId: z.string(),
  workspaceSlug: z.string(),
  key: z.string(),
  status: z.enum(['UPLOADED', 'PROCESSING', 'PROCESSED', 'INDEXED', 'FAILED']),
  fileName: z.string(),
  fileType: z.string(),
  fileSize: z.number(),
  uploadedAt: z.string(),
  pageCount: z.number().optional(),
  confidence: z.number().optional(),
})

The schema defines both the shape of your data and the constraints on it.

A DistributedTable pairs that schema with a key structure and optional indexes.

const documents = new DistributedTable(root, 'documents', {
  schema: documentMetaSchema,
  key: { partitionKey: 'documentId' },
  indexes: {
    byWorkspaceSlug: { partitionKey: 'workspaceSlug', sortKey: 'uploadedAt' },
  },
})

The byWorkspaceSlug index lets you query all documents for a workspace, sorted by upload time -- exactly what the document list view needs.

You can define as many tables as your application requires. Extraction metadata, for example, lives in its own table with a different shape.

const extracted = new DistributedTable(root, 'extracted', {
  schema: z.object({
    documentId: z.string(),
    pageCount: z.number(),
    confidence: z.number(),
    rawTextPreview: z.string(),
    tablesCount: z.number().optional(),
    keyValuesCount: z.number().optional(),
    formsCount: z.number().optional(),
    signaturesCount: z.number().optional(),
    extractedAt: z.string(),
  }),
  key: { partitionKey: 'documentId' },
})

Each table is a building block -- locally it uses an in-memory store, in production it provisions DynamoDB. Your application code calls documents.put() or documents.query() the same way in both environments.

The blocks define what your application needs -- the CDK connects those needs to real AWS resources. A separate index.cdk.ts file handles the infrastructure wiring: environment variables, IAM permissions, and event triggers.

export default function (stack: BlocksStack) {
  stack.handler.addEnvironment('METADATA_TABLE_NAME', documentsTable.tableName)
  stack.handler.addEnvironment('OUTPUT_BUCKET', processedBucketResource.bucketName)
}

Each block automatically provisions its core resources. The CDK file adds the glue -- passing resource names between blocks and granting the permissions they need.

IAM policies follow the same pattern. The chat endpoint needs Bedrock access, so you add it to the handler's role.

stack.handler.addToRolePolicy(new iam.PolicyStatement({
  actions: [
    'bedrock:InvokeModel',
    'bedrock:InvokeModelWithResponseStream',
    'bedrock:Retrieve',
  ],
  resources: ['*'],
}))

stack.handler.addToRolePolicy(new iam.PolicyStatement({
  actions: [
    'bedrock:ListDataSources',
    'bedrock:GetDataSource',
    'bedrock:StartIngestionJob',
  ],
  resources: ['*'],
}))

The extraction Lambda needs its own permissions -- Textract for document analysis, S3 for reading uploads and writing processed output.

textractProcessorFn.addToRolePolicy(new iam.PolicyStatement({
  actions: [
    'textract:StartDocumentAnalysis',
    'textract:GetDocumentAnalysis',
  ],
  resources: ['*'],
}))

rawBucketResource.grantRead(textractProcessorFn)
processedBucketResource.grantReadWrite(textractProcessorFn)
documentsTable.grantReadWriteData(textractProcessorFn)

The CDK file is where blocks meet the real cloud. Your application code stays focused on business logic -- the CDK handles resource naming, permissions, and event routing.

What we never had to build

It's worth noticing everything that's missing from this application.

No REST endpoints
No API Gateway configuration
No OpenAPI specification
No generated frontend SDK
No handwritten local mocks
No environment-specific code
No separate infrastructure project

Those capabilities are provided by the Building Blocks themselves.

Your application code stays focused on business logic while AWS Blocks supplies the infrastructure, runtime implementation, local development experience, and typed APIs behind the scenes.

Creating the Knowledge Base

Our application needs somewhere to store embeddings and perform semantic search.

That's exactly what the KnowledgeBase block provides.

import { Scope, ApiNamespace } from "@aws-blocks/blocks"
import { KnowledgeBase } from "@aws-blocks/bb-knowledge-base"

const scope = new Scope("chat-app")

const kb = new KnowledgeBase(scope, "docs", {
  source: "./knowledge",
  description: "Application documentation",
})

export const api = new ApiNamespace(scope, "api", () => ({
  search(query: string) {
    return kb.retrieve(query, {
      maxResults: 5,
    })
  },
}))

There's a lot happening in just a few lines of code.

The KnowledgeBase doesn't simply provision AWS resources. It also exposes a runtime API that can be called directly from your application. By defining the API alongside the infrastructure, AWS Blocks eliminates the need to manually create Lambda functions, API Gateway routes, OpenAPI specifications, or generated frontend SDKs.

You don't write separate infrastructure.

You simply declare what your application needs.

This is Infrastructure from Code in practice. The application defines both its behavior and the infrastructure required to run it.

One of the most interesting ideas behind AWS Blocks is that the same import can behave differently depending on where it's running. The KnowledgeBase import resolves to a local mock during development, the AWS runtime during sandbox and production, and an infrastructure definition during CDK deployment. This is powered by JavaScript conditional exports -- Node automatically selects the correct implementation. Your application never needs if (local) or if (production) logic.

The frontend doesn't need a generated client

Because the backend API is fully typed, the frontend simply imports it and calls it like any other TypeScript function.

const { results } = await api.search(
  "How do I rotate API keys?"
)

Notice that the frontend isn't making an HTTP request or calling a generated SDK. It's simply invoking the typed API exposed by the backend.

There isn't a separate SDK to generate or synchronize.

During local development, this call executes against the local mock implementation.

During Sandbox and Production, the exact same code executes against your deployed AWS resources.

The API remains constant. Only the implementation changes.

Uploading documents

The first half of a RAG pipeline isn't AI at all.

It's document processing.

Users upload PDFs, DOCX files, spreadsheets, or images.

Those files need somewhere to live before they can be processed.

AWS Blocks provides a FileBucket for exactly this purpose.

const bucket = new FileBucket(root, 'storage', {
  corsRules: [
    {
      allowedOrigins: ['*'],
      allowedMethods: ['GET', 'PUT', 'POST', 'HEAD'],
      allowedHeaders: ['*'],
      exposedHeaders: ['ETag'],
      maxAge: 3600,
    },
  ],
})

The FileBucket block provisions an S3 bucket and exposes a typed API for presigned URLs, uploads, and deletes. During local development it uses a local file system implementation -- no AWS account required.

After upload, a background job extracts text and writes it into the knowledge source.

uploads/

├── contract.pdf
├── handbook.docx
└── pricing.pdf


        │
        ▼

Extract Text


        │
        ▼

knowledge/

├── contract.md
├── handbook.md
└── pricing.md

The upload flow uses a two-step pattern: the frontend requests a presigned URL, uploads directly to S3, then confirms the upload so the backend can track it.

async initiateUpload(workspaceSlug: string, fileName: string, fileType: string, fileSize: number) {
  const documentId = crypto.randomUUID()
  const key = `uploads/${workspaceSlug}/${documentId}/${fileName}`
  const presignedUrl = await bucket.putUrl(key, { contentType: fileType })
  return { documentId, key, presignedUrl }
},

async confirmDocument(workspaceSlug: string, documentId: string, key: string, fileType: string, fileSize: number) {
  await documents.put({
    documentId,
    workspaceSlug,
    key,
    status: 'UPLOADED',
    fileName: key.split('/').pop() ?? 'unknown',
    fileType,
    fileSize,
    uploadedAt: new Date().toISOString(),
  })
  return { documentId }
},

The frontend calls initiateUpload to get a URL, uploads the file directly using fetch, then calls confirmDocument to persist the metadata. The backend never touches the file contents -- it just coordinates the flow.

Once a document is confirmed, an S3 event notification triggers automatic extraction.

const textractProcessorFn = new NodejsFunction(stack, 'TextractProcessorFunction', {
  entry: join(__dirname, '..', 'lambdas', 'textract-pipeline', 'index.ts'),
  handler: 'handler',
  runtime: Runtime.NODEJS_22_X,
  timeout: Duration.minutes(15),
  memorySize: 1024,
})

rawBucketResource.addEventNotification(
  s3.EventType.OBJECT_CREATED,
  new LambdaDestination(textractProcessorFn)
)

The extraction Lambda receives the S3 event, runs Amazon Textract to extract text and structure, then writes the results to the processed bucket. The document status transitions from UPLOADED to PROCESSING to PROCESSED as each stage completes.

Notice something important.

The application never manipulates embeddings directly.

It simply produces clean text.

The Knowledge Base handles chunking, indexing, and retrieval automatically.

The extraction layer

Raw uploads need to be processed before they can be indexed.

AWS Blocks provides AsyncJob for background work that might take minutes -- like running Textract on a 50-page PDF.

const processJob = new AsyncJob(root, 'processor', {
  handler: async (payload: Record<string, unknown>) => {
    console.log('[processor] received payload:', payload)
  },
})

An AsyncJob block provisions a Lambda function backed by an SQS queue with a dead-letter queue. Your handler processes one message at a time, and AWS Blocks manages retries and failure handling automatically.

The pipeline extracts text, tables, forms, and signatures from the document, then writes the results to the processed bucket as structured JSON. Each chunk gets its own file alongside a metadata file that the Knowledge Base will use during indexing.

The application can check extraction status through a simple endpoint.

async processDocument(_workspaceSlug: string, documentId: string) {
  const doc = await documents.get({ documentId })
  if (!doc) throw new Error('Document not found')
  return { status: doc.status, pageCount: doc.pageCount, confidence: doc.confidence }
},

Once extraction completes, the document status transitions to PROCESSED and the chunks are ready to be synced to the Knowledge Base.

Infrastructure from Code (IFC)

Traditional AWS applications usually look something like this.

CDK
    │
CloudFormation
    │
AWS Resources
    │
SDK
    │
Generated Client
    │
Frontend

Infrastructure lives in one project.

Application code lives somewhere else.

Generated clients have to stay synchronized.

Local mocks are usually handwritten.

Every deployment creates another opportunity for things to drift apart.

AWS Blocks takes a completely different approach.

Instead of infrastructure generating application code, the application defines the infrastructure.

This pattern is called Infrastructure from Code (IFC).

A single building block contains everything needed for every environment.

KnowledgeBase Block

├── Infrastructure (CDK)
├── Runtime implementation
├── Local mock
├── Typed client
└── Shared API

The frontend imports the exact same API that your backend defines.

During local development it automatically talks to local implementations.

During sandbox it talks to real AWS services.

During production it talks to deployed infrastructure.

Your application code never changes.

There are no generated SDKs.

No separate client packages.

No environment-specific implementations.

Just one API.

In Infrastructure as Code (IaC), you first describe infrastructure and then write an application that consumes it.

Infrastructure from Code (IFC) inverts that relationship. You write application code first, and AWS Blocks derives the infrastructure needed to run it.

Chunking matters more than most people realize

One of the biggest factors affecting answer quality isn't the language model.

It's chunking.

Large documents need to be divided into smaller pieces before embeddings are generated.

If chunks are too small, important context gets lost.

If they're too large, retrieval becomes less accurate.

AWS Blocks supports multiple chunking strategies depending on your workload.

Strategy	Best for
Semantic	Documentation, articles, manuals
Fixed-size	Predictable chunk sizes
Hierarchical	Large technical documents
None	Small FAQs or short documents

For most applications, semantic chunking provides the best balance between retrieval quality and simplicity.

Choosing a strategy is simply another part of configuring the block.

const kb = new KnowledgeBase(scope, "docs", {
  source: "./knowledge",
  chunking: {
    strategy: "semantic",
  },
})

Retrieval is where RAG becomes intelligent

When a user asks a question, we don't send every document to the LLM.

Instead, we retrieve only the pieces most relevant to that question.

For example, imagine the user asks:

How do I rotate API keys?

The retrieval engine might return:

Security Guide -> API Key Rotation
Operations Manual -> Secrets Management
Deployment Guide -> Environment Variables

Those chunks become the context for the LLM.

The model never sees unrelated documentation.

That keeps responses faster, cheaper, and significantly more accurate.

The core retrieval call is straightforward.

const results = await kb.retrieve(query, {
  maxResults: 5,
  filter: { documentId: { equals: docId } },
})

You pass a query and optionally filter by metadata -- workspace, document ID, or any attribute your schema defines. The Knowledge Base returns scored passages with their source text and metadata.

When users upload multiple documents, you need balanced results across all of them. A simple retrieve might return five chunks from the same document, missing relevant passages from others.

The solution is per-document quota allocation -- divide your total results evenly across documents, then merge and re-rank.

async retrievePassages(_workspaceSlug: string, query: string, documentIds: string[], topK = 10) {
  if (documentIds.length === 0) return []
  const resultsPerDoc = Math.ceil(topK / documentIds.length)
  const allResults: Array<{ text: string; score: number; source: string; metadata: Record<string, string> }> = []

  for (const docId of documentIds) {
    const results = await kb.retrieve(query, {
      maxResults: resultsPerDoc,
      filter: { documentId: { equals: docId } },
    })
    allResults.push(...results)
  }

  allResults.sort((a, b) => b.score - a.score)
  return allResults.slice(0, topK)
}

This pattern ensures every uploaded document gets a fair chance to contribute relevant passages, and the final ranking is based on relevance scores across the entire set.

The Chat Endpoint

This is where everything comes together -- retrieval, context assembly, and language model generation.

The chat endpoint takes a user's question and conversation history, retrieves relevant passages, and sends them to Bedrock for a grounded response.

Here's the simplest version: extract the user's query, retrieve passages, and call the model.

async chat(_workspaceSlug: string, documentIds: string[], messages: Array<{ role: string; content: string }>) {
  const lastUser = [...messages].reverse().find(m => m.role === 'user')
  const query = lastUser?.content ?? ''

  const passages: Array<{ text: string; score: number; metadata: Record<string, unknown> }> = []
  for (const docId of documentIds) {
    const results = await kb.retrieve(query, {
      maxResults: 3,
      filter: { documentId: { equals: docId } },
    })
    passages.push(...results)
  }
  passages.sort((a, b) => b.score - a.score)

  const bedrockClient = new BedrockRuntimeClient({})
  const response = await bedrockClient.send(new ConverseCommand({
    modelId: 'amazon.nova-lite-v1:0',
    messages: [{ role: 'user', content: [{ text: query }] }],
    inferenceConfig: { maxTokens: 1024 },
  }))

  return response.output?.message?.content?.map(c => c.text).join('')
}

That works, but it doesn't ground the model's response in the retrieved passages. The model will answer from its training data, not from the documents.

The key is building a context block from the passages and embedding it in the user message alongside the original question.

const contextBlock = passages.length > 0
  ? passages
      .map((p, i) => `[Passage ${i + 1}]${p.metadata?.pageNumber ? ` (page ${p.metadata.pageNumber})` : ''} ${p.text}`)
      .join('\n\n')
  : 'No passages retrieved for this document.'

const finalUserContent = query
  ? `DOCUMENT PASSAGES:\n${contextBlock}\n\nMY QUESTION:\n${query}`
  : contextBlock

const bedrockMessages = [
  ...history,
  { role: 'user', content: [{ text: finalUserContent }] },
]

A system prompt tells the model how to use those passages -- answer only from the provided context, cite passages by page number, and never fabricate information.

const systemPrompt = [
  'You are a document assistant helping a user understand their documents.',
  'Answer ONLY based on the document passages provided in the user message.',
  'For every factual claim cite the relevant passage using [page N] notation.',
  'If the answer cannot be found in the provided passages, say so explicitly -- do not fabricate.',
  'Be concise. Use clear, professional language.',
].join('\n')

Finally, the response should include citations -- the passages that contributed to the answer, scored by relevance.

const citations = passages
  .filter(p => (p.score ?? 0) > 0.3)
  .slice(0, 3)
  .map(p => ({
    passage: (p.text ?? '').substring(0, 200),
    documentId: (p.metadata?.documentId as string) ?? documentIds[0],
    pageNumber: p.metadata?.pageNumber as number | undefined,
    score: p.score ?? 0,
  }))

return { answer, citations }

The complete endpoint handles retrieval, context assembly, prompt engineering, model invocation, and citation extraction in a single typed method -- no separate Lambda, no API Gateway, no generated SDK.

In production, wrap this in error handling. Bedrock calls can timeout, Textract can fail on corrupted files, and retrieval can return empty results. A try/catch around the Bedrock invocation with a fallback message ("I couldn't generate a response. Please try again.") keeps the user experience smooth.

Multi-tenant applications

Most SaaS products don't have one knowledge base.

They have hundreds.

Every organization should only retrieve its own documents.

Instead of maintaining separate vector databases, AWS Blocks lets retrieval be filtered using document metadata.

const results = await kb.retrieve(question, {
  filter: {
    folder: {
      equals: workspaceId,
    },
  },
})

A document stored under workspace-123/ automatically receives the appropriate metadata, allowing retrieval to be scoped to a single tenant without maintaining separate indexes.

The application logic remains exactly the same.

Local development without AWS

This is where AWS Blocks really shines.

Traditional cloud development often looks like this.

Write code
      │
Deploy
      │
Wait
      │
Upload documents
      │
Wait
      │
Test
      │
Repeat

That feedback loop can easily take several minutes.

AWS Blocks replaces it with a local implementation.

During development:

documents are indexed locally
the local implementation uses TF-IDF instead of embeddings so indexing is nearly instantaneous and doesn't require an AWS account, while preserving the same retrieval API you'll use in production
uploads remain on your machine
APIs stay fully typed
frontend code behaves exactly like production

No AWS account is required.

No credentials are required.

No deployment is required.

Once you're happy with the experience, you can switch to sandbox.

Your code doesn't change.

Only the implementation does.

Why this feels different: Vertical development instead of service integration

Most cloud applications are built horizontally.

You start by provisioning infrastructure, then expose APIs, then generate SDKs, and finally wire everything into your frontend.

Frontend
    │
Generated Client
    │
API
    │
Lambda
    │
S3
    │
Bedrock
    │
IAM

Each layer is developed independently. A small feature often requires changes across multiple projects, deployments to test the backend, and handoffs between infrastructure and application code.

AWS Blocks encourages a vertical way of building software instead.

Think about a single feature -- chat with documents.

Instead of touching five different layers of your stack, you build one vertical slice that owns everything it needs.

Chat with Documents

├── Upload documents
├── Extract text
├── Index knowledge
├── Retrieve context
├── Generate answers
├── Typed API
├── Local mock
└── AWS infrastructure

That entire feature lives together as application code.

The infrastructure, runtime implementation, local development experience, and frontend API are simply different representations of the same building blocks.

This changes the way you develop.

Rather than spending days wiring together services before you can test a feature, you build a complete workflow from the UI all the way to the cloud resources behind it.

You can upload a document, ask a question, tweak the retrieval logic, adjust chunking, or refine prompts -- all without changing how your frontend communicates with the backend.

Even better, that workflow remains the same across every environment.

           Same application code

        ┌──────────┬──────────┐
        │          │          │
     Local      Sandbox   Production
        │          │          │
   Local Mock   Real AWS   Real AWS

During local development, AWS Blocks swaps in local implementations that let you iterate quickly without deploying infrastructure.

When you're ready for integration testing or production, the exact same code automatically runs against real AWS services.

You aren't rewriting your application for each environment -- the implementation changes underneath you.

This is the core idea behind Infrastructure from Code (IFC).

Infrastructure is no longer something you build first and consume later.

It's simply another capability of the same application code.

Why this approach scales

As applications grow, RAG pipelines usually become more sophisticated.

You might add:

authentication
background extraction jobs
streaming chat responses
citations
multiple knowledge bases
document permissions
evaluation pipelines
feedback collection
Bedrock Guardrails

Traditionally, every feature introduces another AWS service and another integration.

With AWS Blocks, each concern becomes another building block.

The application continues to look like application code rather than infrastructure code.

That separation becomes increasingly valuable as projects become larger.

Cost considerations

RAG applications have two cost drivers: vector storage and LLM inference.

Traditional vector databases (OpenSearch, Pinecone, Weaviate) charge per million vectors stored and per query. For high-volume document libraries, those costs add up quickly.

Amazon S3 Vectors, used by the KnowledgeBase block, offers a more cost-optimized approach. Storage is charged at standard S3 rates, and retrieval costs are significantly lower than dedicated vector databases. For applications processing thousands of documents, this can reduce vector storage costs by 80% or more compared to managed vector services.

LLM inference is the other major cost. Using retrieval to ground responses means sending fewer tokens to the model. Instead of feeding an entire document library into the context window, you send only the 3-5 most relevant passages. That keeps per-query costs low and response times fast.

The local development story also saves money during development. Without TF-IDF-based local mocks, every test cycle would require deploying to AWS and running real embedding generation. Local iteration eliminates those costs entirely.

Putting it all together

The finished architecture looks something like this.

          Nextjs/Nuxt Frontend
                  │
          Typed API Calls
                  │
          AWS Blocks API
     ┌────────────┼────────────┐
     │            │            │
FileBucket  KnowledgeBase  Authentication
     │            │
     │      Amazon Bedrock
     │            │
     └────── S3 Vectors ──────┘
                  │
         Grounded Responses

Each block owns its infrastructure, runtime implementation, and local development experience.

The frontend simply imports the API.

The development workflow

One of the goals of AWS Blocks is making every environment behave consistently.

Command	Environment	Purpose
`npm run dev`	Local mocks	Fast iteration
`npm run sandbox`	Real AWS	Validate integrations
`npm run deploy`	Production	Deploy application

Because every environment exposes the same APIs, moving between them is mostly a configuration change -- not a development task.

Your frontend continues to call the same typed methods throughout the entire lifecycle.

The API stays the same.

Only the implementation underneath it changes.

What's next

We've built a complete RAG application -- from upload to grounded response -- using a single project and a single set of APIs. But this is just the starting point.

The same building block pattern extends naturally to features you'll want next:

Streaming responses -- swap the Bedrock Converse call for a streaming variant and pipe tokens to the frontend in real time
Document permissions -- add a DocumentPermission block to control who can query which documents
Evaluation pipelines -- build a test harness that runs sample questions against your knowledge base and scores answer quality
Bedrock Guardrails -- add content filtering and safety constraints to the chat endpoint

Each of these is another building block. The infrastructure, runtime, local mock, and typed API follow the same pattern you've already seen. You add a block, define its API, and the rest of the stack adapts.

The shift -- from stitching AWS services together to composing building blocks -- changes what's possible in a day, a week, a sprint. That's the real advantage of Infrastructure from Code.

Learn more

AWS Blocks Documentation -- Building Blocks, API reference, patterns
Agent Toolkit for AWS -- The canonical skill for AWS Blocks best practices, security patterns, and common mistakes.
Bedrock Knowledge Bases -- AWS documentation
Amazon S3 Vectors -- Cost-optimized vector storage for AI agents, inference, RAG, and semantic search.
AWS Blocks Getting Started -- Project scaffolding and first steps

Deploy React + Vite on AWS S3 and CloudFront: A Complete Guide

Saddam Azad — Mon, 17 Feb 2025 22:29:41 +0000

Now that Create React App (CRA) is being deprecated, the easiest way to get started with React is with Vite.

Introduction

Vite is a next-generation frontend tooling that offers a fast development experience for modern web projects, including those built with React. When it comes to deploying your application, AWS provides scalable and reliable infrastructure, but setting it up can be complex.

When it comes to deploying your application, Amazon Web Services (AWS) offers scalable and reliable infrastructure solutions. However, setting up the necessary services—like S3 buckets, CloudFront distributions, and CI/CD pipelines—can be complex and time-consuming.

That's where the CDK-SPA library comes into play. CDK-SPA leverages the AWS Cloud Development Kit (CDK) to automate the provisioning of AWS resources required for hosting static site generators (SSG) and single-page applications (SPAs). This simplifies the deployment process, allowing you to focus more on developing your application and less on managing infrastructure.

The library uses AWS S3 for hosting with CloudFront CDN.

The library also configures a webhook in your Github to autodeploy using AWS CodeBuild and CodePipeline.

In this guide, we'll walk through deploying a React + Vite application on AWS using CDK-SPA.

Github repo Stackblitz demo

Prerequisites

Before you begin, make sure you have the following:

An AWS Account: Sign up for an AWS account if you don't have one.
Node.js and npm: Ensure you have Node.js (v18 or later) and npm installed.
AWS CLI: Install and configure the AWS Command Line Interface.
Before deploying, bootstrap your AWS environment:

cdk bootstrap aws://your-aws-account-id/us-east-1

AWS CDK: Install the AWS CDK globally

npm install -g aws-cdk

Staring a New Project

Create a new React project with Vite and TypeScript.

New Project in Stackblitz

Here's the step-by-step process:

Open your terminal and run the following command to create a new project:

pnpm create vite@latest

Enter your project name
Select "React" as your framework
Choose "TypeScript" as your variant

Create GitHub Personal Access Token

Here's how to create a GitHub Personal Access Token (PAT):

Go to your GitHub account settings.
Navigate to Developer settings > Personal access tokens.
Click on Generate new token.
Choose Tokens (classic).
Give the token a descriptive name.
Set the expiration to No expiration (ignore the warning, for now).
Select the scopes (permissions):
- repo: Full control of private repositories.
- admin:repo_hook: Full control of repository hooks.
Click Generate token.

Important: Copy the token immediately and store it securely. You won't be able to see it again. If you lose it, you'll need to generate a new one.

Store the Token in AWS Secrets Manager

Use the AWS CLI to create a new secret in AWS Secrets Manager:

aws secretsmanager create-secret --name your-secret-name --secret-string your-token

Replace your-secret-name with a name for your secret.
Replace your-token with your actual GitHub token.
The command will return something like this:

{
    "ARN": "arn:aws:secretsmanager:us-east-1:665186350000:secret:your-secret-token-VgnkyF",
    "Name": "your-secret-name",
    "VersionId": "b1a532d2-4434-42a3-9283-41581be07455"
}

Take note of the ARN.

Note: Storing secrets in AWS Secrets Manager may incur a cost (around $0.40 per month).

Setting Up the Project

Navigate to your project directory and install the project dependencies:

pnpm install

Install the CDK-SPA library and AWS CDK as development dependencies:

pnpm install --save-dev @thunderso/cdk-spa aws-cdk-lib@2.150.0 tsx

Run the following command to create the CDK stack entry point:

npx cdk-spa-init

This will generate a stack directory with an index.ts file, which defines how your app will be deployed via CDK.

Configure the Stack

Edit stack/index.ts and replace placeholders with your actual configuration.

import { App } from "aws-cdk-lib";
import { SPAStack, type SPAProps } from "@thunderso/cdk-spa";

const appStackProps: SPAProps = {
  env: {
    account: 'your-aws-account-id', // Replace with your AWS Account ID
    region: 'us-east-1', // Or your preferred region
  },
  application: 'my-app',
  service: 'web',
  environment: 'prod',

  sourceProps: {
    owner: 'cloudbitsio', // GitHub username or organization
    repo: 'vite-react', // Repository name
    branchOrRef: 'main', // Branch to deploy
    rootdir: '', // Root directory if not at the repo root
  },

  buildProps: {
    runtime: 'nodejs',
    runtime_version: '20',
    installcmd: 'npm ci',
    buildcmd: 'npm run build',
    outputdir: 'dist/',
  },

  githubAccessTokenArn: 'arn:aws:secretsmanager:us-east-1:665186350000:secret:your-secret-token-VgnkyF',

};

new SPAStack(
  new App(),
  `${appStackProps.application}-${appStackProps.service}-${appStackProps.environment}-stack`,
  appStackProps
);

Set githubAccessTokenArn in your stack/index.ts to the ARN of the secret you just created.

Deploy the Application

Use the CDK CLI to deploy your application:

npx cdk deploy --require-approval never --all --app="npx tsx stack/index.ts"

If you have multiple AWS profiles, select your profile to match your stack configuration.

npx cdk deploy --require-approval never --all --app="npx tsx stack/index.ts" --profile default

Access Your Application

Use the CloudFront URL provided in the deployment outputs to access your app. It will look something like https://d1234567890abcdef.cloudfront.net.

Additional Resources

Vite Documentation: https://vitejs.dev/
React Documentation: https://reactjs.org/
AWS CDK Documentation: https://docs.aws.amazon.com/cdk/
CDK-SPA on npm: https://www.npmjs.com/package/@thunderso/cdk-spa
CDK-SPA GitHub Repository: https://github.com/thunder-so/cdk-spa
Demo Repository: https://github.com/cloudbitsio/vite-react

Troubleshooting

Deployment Failures:
If the deployment fails, check the AWS CloudFormation console for stack events to identify the issue. Common problems include missing permissions, incorrect configuration, or resource conflicts.
Access Denied Errors:
Ensure your AWS credentials have the necessary permissions. You may need to adjust IAM policies or roles to grant appropriate access.

Conclusion

Congratulations! You've successfully deployed a React application on AWS using CDK-SPA. This setup automates the deployment process, allowing you to focus on developing your application rather than managing infrastructure.

thunder.so Looking for Beta Testers

Saddam Azad — Wed, 04 May 2022 07:09:40 +0000

Hello community, we are building Thunder.so - an easy way to provision cloud infrastructure and deploy your sites.

We know how steep the learning curve is for cloud (AWS, I'm looking at you) and it can days to set up a simple staging environment.

Forget about SSH-ing into your EC2 instance and manually installing stuff. Forget about complex CloudFormation scripts. Just place a yaml file in your project directory and we will set up the entire stack, including CI/CD automation in minutes.

If you are a developer who spends time setting up servers instead of writing code, sign up for our beta program.

Looking forward to the feedback from this community.