Infrastructure

Codapult ships three infrastructure modules — file storage, background jobs, and notifications — each using the adapter pattern. Switch implementations via a single environment variable; no code changes required.

File Storage

Upload and serve files through a unified API. The storage adapter is selected by STORAGE_PROVIDER.

| Provider | Env Value | Best For | | ---------------- | ----------------- | ----------------------- | | Local filesystem | local (default) | Development | | Amazon S3 | s3 | Production (AWS) | | Cloudflare R2 | r2 | Production (Cloudflare) |

Upload API

POST /api/upload accepts multipart form data. Authentication is required.

const form = new FormData();
form.append('file', file);

const res = await fetch('/api/upload', {
  method: 'POST',
  body: form,
});

const { url } = await res.json();

Image uploads are automatically optimized (resized, compressed) before storage.

Switching to S3 or R2

1. Install the AWS SDK (required only for S3/R2):

pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

2. Set the provider and credentials in .env.local:

STORAGE_PROVIDER="s3"   # or "r2"

S3_BUCKET="my-bucket"
S3_REGION="us-east-1"   # use "auto" for R2
S3_ENDPOINT=""           # required for R2 (e.g. https://<account>.r2.cloudflarestorage.com)
S3_ACCESS_KEY_ID="..."
S3_SECRET_ACCESS_KEY="..."
S3_PUBLIC_URL=""         # optional — public URL prefix for uploaded files

Production: Always use S3 or R2. The local adapter stores files on disk and is not suitable for multi-instance deployments.

Programmatic Usage

import { uploadFile, deleteFile } from '@/lib/storage';

const url = await uploadFile('avatars/user-123.webp', buffer, 'image/webp');
await deleteFile('avatars/user-123.webp');

Background Jobs

Offload work to background jobs for email sending, webhook delivery, credit resets, and RAG indexing. The job adapter is selected by JOB_PROVIDER.

| Provider | Env Value | Best For | | --------------- | ------------------ | ---------------------------- | | In-memory queue | memory (default) | Development, single-instance | | BullMQ (Redis) | bullmq | Production, multi-instance |

Enqueuing Jobs

import { enqueue, enqueueEmail } from '@/lib/jobs';

// Generic job
await enqueue('webhook-retry', { webhookId: 'wh_123', attempt: 1 });

// Shorthand for emails
await enqueueEmail('[email protected]', 'Welcome!', emailHtml);

Built-in Jobs

| Job Name | Description | | --------------- | ---------------------------------------------------------- | | send-email | Sends transactional email via Resend | | webhook-retry | Retries failed webhook deliveries with exponential backoff | | credit-reset | Resets monthly AI/usage credits for all organizations | | rag-index | Indexes documents for AI RAG pipeline |

Built-in Cron Jobs

| Schedule | Task | | -------- | ----------------------------------------- | | Daily | Session cleanup (remove expired sessions) | | Monthly | Credit reset (reset usage quotas) |

Switching to BullMQ

Set the provider and Redis connection in .env.local:

JOB_PROVIDER="bullmq"
REDIS_URL="redis://localhost:6379"

For production Kubernetes or Docker deployments, run the worker as a separate process alongside your Next.js server. The Helm chart includes a dedicated worker Deployment.

Notifications

In-app notifications with real-time delivery. The transport is selected by NOTIFICATION_TRANSPORT.

| Transport | Env Value | Description | | ------------------ | ---------------- | ------------------------------------------------------ | | Polling | poll (default) | Periodic HTTP requests — works everywhere, zero config | | Server-Sent Events | sse | One-way real-time stream from server to client | | WebSocket | ws | Full-duplex real-time — requires a separate WS server |

Dashboard Integration

The NotificationBell component in the dashboard header shows unread count and a dropdown list. It works with all three transports automatically.

Creating Notifications

import { createNotification } from '@/lib/notifications';

await createNotification({
  userId: 'user_abc',
  type: 'info', // 'info' | 'success' | 'warning' | 'error'
  title: 'Deployment complete',
  message: 'Your app was deployed to production.',
  link: '/dashboard/deployments/42',
});

Operations

| Function | Description | | ------------------------ | ---------------------------------- | | createNotification() | Create and deliver a notification | | getUserNotifications() | List notifications (newest first) | | getUnreadCount() | Count unread notifications | | markAsRead() | Mark a single notification as read | | markAllAsRead() | Mark all notifications as read |

WebSocket Configuration

When using the ws transport, configure the WebSocket server URL and port:

NOTIFICATION_TRANSPORT="ws"
NEXT_PUBLIC_WS_URL="ws://localhost:3001"
WS_PORT="3001"

Choosing a Transport

• Polling — simplest option, no infrastructure dependencies. Good for low-traffic apps.
• SSE — real-time without extra servers. One-way (server → client). Good default for production.
• WebSocket — full-duplex, lowest latency. Requires running a separate WS server process.