Nuxt 4 + DynamoDB + AWS Cognito + Native AWS SDK Ingestion Engine | CLAUDE.md Template

Overview

The CLAUDE.md template is a copyable blueprint that encodes Claude Code instructions for implementing a serverless ingestion engine in a Nuxt 4 application using AWS DynamoDB for storage and AWS Cognito for authentication. This page provides a complete, pasteable CLAUDE.md template tailored to the stack Nuxt 4 + DynamoDB + AWS Cognito + Native AWS SDK Ingestion Engine.

Direct answer: This CLAUDE.md template yields a ready-to-paste Claude Code block and strict rules to build an end-to-end ingestion workflow backed by DynamoDB with Cognito authentication, leveraging the native AWS SDK.

When to Use This CLAUDE.md Template

• You are building a Nuxt 4 app that ingests data into DynamoDB and requires authenticated access via Cognito.
• You want a canonical, copyable CLAUDE.md template to govern the ingestion code generation.
• You need explicit architecture, validation, and security rules to prevent drift in production.
• You want a consistent file structure and deployment guidance for this stack.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, a deterministic instruction engine that outputs production-grade code blocks for a Nuxt 4 stack using DynamoDB, AWS Cognito, and the native AWS SDK ingestion engine.

Architecture rules:
- Target runtime: Node.js 18+ with TypeScript support.
- Ingestion Engine runs as a serverless component (AWS Lambda) invoked by Nuxt server routes or API handlers.
- All AWS interactions use the AWS SDK v3 (modular clients).
- Data lives in DynamoDB with a primary key and optional GSI for lookups.
- Authentication is enforced via Cognito User Pools; endpoints validate JWTs and groups.

File structure rules:
- Keep ingestion code under ingestion/ with index.ts exporting the handler.
- Keep Nuxt-specific code under app/ and server/ for Nitro integration.
- Use lib/ for shared utilities, types/ for TS types, and tests/ for tests.
- Do not place AWS credentials in code; rely on environment variables or AWS IAM roles.

Authentication rules:
- Use Cognito JWT validation on all protected endpoints.
- Decode and verify token, check groups/roles, and map to application roles.
- Never export Cognito tokens to the client.

Database rules:
- DynamoDB table: IngestQueue with primary key (pk) and sort key (sk).
- Use on-demand billing mode; enable point-in-time recovery if needed.
- Use a GSI for ingestion status if required.

Validation rules:
- Validate inbound payloads with a JSON Schema before ingestion.
- Enforce size limits, allowed fields, and type checks.
- Return deterministic error messages to aid debugging.

Security rules:
- Do not embed secrets in code; use AWS Secrets Manager or SSM Parameter Store and IAM roles.
- Encrypt data at rest; enable DynamoDB encryption and KMS-managed keys for writes.
- Enforce least privilege IAM policies for ingestion components.

Testing rules:
- Unit tests for ingestion transformers and validators.
- Integration tests for DynamoDB interactions using a local or mocked DynamoDB.
- CI should run lints, type checks, unit and integration tests.

Deployment rules:
- Use AWS CDK to deploy Lambda, DynamoDB, and Cognito resources.
- GitHub Actions or CI/CD should inject environment variables securely.
- Do not deploy with hard-coded credentials.

Things Claude must not do:
- Do not bypass Cognito authentication on protected routes.
- Do not access DynamoDB directly from client-side code.
- Do not embed static AWS credentials in the CLAUDE.md template.
- Do not generate code that breaks strict TypeScript types or Nuxt 4 conventions.

Recommended Project Structure

nuxt-app/
  nuxt.config.ts
  app/
  components/
  layouts/
  pages/
  ingestion/
  lib/
  tests/
  package.json
  tsconfig.json

Core Engineering Principles

• Idempotent ingestion with deduping and idempotent handlers.
• Least privilege access for IAM roles used by ingestion and Lambda.
• Type-safe boundaries between client, server, and ingestion logic.
• Clear separation of concerns between authentication, data access, and transformation.
• Automated testing for unit, integration, and deployment stages.

Code Construction Rules

• Use Nuxt 4 conventions (Nitro server, route handlers, composables).
• Use TypeScript throughout with strict compiler options.
• All AWS SDK calls must be asynchronous and properly error-handled.
• Input validation must occur before any ingestion transform.
• All credentials must be sourced from environment or AWS IAM roles, not hard-coded.

Security and Production Rules

• Guard all endpoints with Cognito, validating JWTs and claims.
• Encrypt DynamoDB data at rest with a KMS key; enable TTL where applicable.
• Use IAM roles for Lambda with least privilege to DynamoDB and Cognito.
• Audit logs and monitor ingestion with CloudWatch; set alarms for anomalies.

Testing Checklist

• Unit tests for validators and transformers.
• Integration tests for DynamoDB write/read paths.
• End-to-end tests covering Nuxt route, Cognito auth, and ingestion output.
• Lints and TypeScript type-checks in CI.

Common Mistakes to Avoid

• Hardcoding credentials or secrets in code or CLAUDE.md templates.
• Skipping Cognito token validation on protected APIs.
• Using client-side code to access DynamoDB or AWS credentials directly.
• Not handling DynamoDB throttling or retries properly.

FAQ

What is this CLAUDE.md Template for?

The template provides a paste-ready Claude Code block to implement an ingestion engine in a Nuxt 4 app using DynamoDB, Cognito, and the Native AWS SDK.

Which stack does this template cover?

Nuxt 4 + DynamoDB + AWS Cognito + Native AWS SDK Ingestion Engine.

How do I customize the DynamoDB table name and primary key?

Modify the ingestion schema and DynamoDB table names in the code block; ensure the primary key aligns with your data model and perf needs.

How should Cognito tokens be validated?

Validate the JWT against the Cognito user pool, verify issuer, audience, and required claims; enforce group-based authorization where relevant.

Where should I deploy the ingestion components?

Use AWS CDK to deploy Lambda ingestion, DynamoDB tables, and Cognito resources; avoid embedding credentials in the deployment scripts.

What should Claude not do?

Do not bypass authentication, expose AWS credentials, or generate code that directly connects a client to DynamoDB; avoid drifting from Nuxt 4 conventions.