If you’re new to Kubernetes, the Kubernetes for Docker Users primer covers Pods, Deployments, Services, PVCs, and Helm basics. For packaging and GitOps, see Kubernetes Packaging and Deployment.

Why not Bitnami?

The obvious choice for an in-cluster MongoDB is the Bitnami chart, which is widely used and simple to install. The problem is vector search. Applications that need semantic search or Atlas-style indexes require the mongot process — a sidecar that runs alongside mongod and handles full-text and vector indexes. Bitnami deploys a plain community MongoDB without mongot, so Atlas Search is simply not available.

The only supported path to mongot in a self-hosted environment is the MongoDB Kubernetes Operator, which introduces the MongoDBCommunity and MongoDBSearch custom resources. The operator manages the StatefulSet, replica set initialization, user creation, and TLS — and, when MongoDBSearch is enabled, injects the mongot sidecar with the right configuration.

Our chart wraps the operator’s CRDs with sensible defaults and a single helm upgrade --install interface, so operators don’t need to understand the operator’s internals to get a working cluster. You can run MongoDB with or without search; if you don’t need vector or full-text search, you can disable the mongot sidecar and save resources.

Two-phase install

mongot requires a running, authenticated replica set to connect to — it cannot start on a fresh cluster. The install therefore happens in two phases:

# Phase 1: bring up the replica set without search
helm upgrade --install mongodb oci://ghcr.io/analytiq-hub/mongodb-atlas-local \
  --version 2.0.1 --namespace mongodb \
  --set mongodb.adminPassword="..." \
  --set mongodb.appUser.password="..." \
  --set search.enabled=false

# Wait for replica set Ready
kubectl wait --for=condition=ready pod -l app=mongodb-mongodb-atlas-local \
  -n mongodb --timeout=300s

# Phase 2: enable search
helm upgrade mongodb oci://ghcr.io/analytiq-hub/mongodb-atlas-local \
  --version 2.0.1 --namespace mongodb --reuse-values \
  --set search.enabled=true

Attempting a single-phase install with search.enabled=true results in mongot crash-looping because the replica set isn’t ready to accept its connection.

Node sizing for stateful workloads

Adding MongoDB changes the cluster sizing arithmetic considerably. Each replica pod runs two containers: mongod (500m CPU, 400Mi) and mongodb-agent (500m CPU, 400Mi), plus a mongot sidecar (250m CPU, 250Mi) when search is enabled. A 3-replica set therefore requests ~2.25 vCPU and ~3.15 Gi of memory, on top of whatever other workloads you run.

The scheduler must fit the entire pod on one node. On a cluster with two t3.medium nodes (2 vCPU / 4 Gi each), if existing workloads already consume ~1.7 vCPU in requests, there may be ~2.2 vCPU free across both nodes — but never more than ~740m on a single node. A MongoDB pod that needs ~750m CPU cannot be scheduled. Adding a third node (or sizing nodes with enough headroom) resolves it.

The practical lesson: account for stateful pods when sizing the initial node group, or ensure the autoscaler can provision new nodes quickly enough not to block workloads.

EBS CSI Driver and the gp2 trap (EKS)

When we added MongoDB to an EKS cluster, PVCs sat in Pending indefinitely with the error:

no persistent volumes available for this claim and no storage class is set

EKS creates a gp2 StorageClass by default, but it has two problems. First, it is not marked as the default class — PVCs with an empty storageClassName get no provisioner assigned. Second, and more importantly, gp2 uses the legacy in-tree kubernetes.io/aws-ebs provisioner, which was removed in Kubernetes 1.27. On EKS 1.35, it is simply gone.

The fix is to create a gp3 StorageClass backed by the EBS CSI driver (ebs.csi.aws.com) and mark it as the cluster default:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  type: gp3
  encrypted: "true"

WaitForFirstConsumer is important — it delays EBS volume creation until the pod is actually scheduled to a node, which ensures the volume is created in the correct availability zone. allowVolumeExpansion: true enables online resizing without pod restarts.

Provision this StorageClass (and the EBS CSI driver) via Terraform or your preferred IaC so new clusters get it automatically.

Summary

We use this chart for Doc Router and other applications that need MongoDB with vector search. For the full Doc Router deployment story (Helm chart, workers, CI/CD, multi-cloud), see Deploying Doc Router on Kubernetes.

Andrei Radulescu-Banu is the founder of DocRouter.AI (document processing with LLMs) and SigAgent.AI (Claude Agent monitoring). His company AnalytiqHub.com provides consulting services for cloud and AI engineering.

If you’re new to Kubernetes, start with Kubernetes for Docker Users: A Practical Primer, which covers the core concepts — Pods, Deployments, Services, Namespaces, Secrets, PVCs, Helm, and Kind — before diving into this post. For packaging and GitOps (Kustomize, Helm, Flux), see Kubernetes Packaging and Deployment.

Why Kubernetes?

Doc Router was originally deployed using Docker Compose, which worked well for single-node setups. As we started onboarding enterprise customers with availability and scalability requirements, we needed:

• Horizontal scaling — multiple replicas behind a load balancer
• Automated failover — pods restarted on failure without manual intervention
• Rolling deployments — zero-downtime upgrades
• Resource isolation — CPU and memory limits per component

Architecture

The production deployment consists of two main workloads:

• Frontend — Next.js server (SSR + API routes via NextAuth)
• Backend — FastAPI application with embedded background workers

Both run as Kubernetes Deployments behind a shared nginx ingress with TLS terminated by cert-manager (Let’s Encrypt).

MongoDB can run outside the cluster (MongoDB Atlas) or in-cluster via our mongodb-atlas-local Helm chart — see Self-Hosted MongoDB on Kubernetes with Atlas Search for the install guide. AWS S3 remains an external dependency.

Helm Chart

We packaged the deployment as a Helm chart (deploy/charts/doc-router) published to GitHub Container Registry (ghcr.io) as an OCI artifact. The chart is versioned independently of the Docker images, so we can update deployment configuration without rebuilding the application.

Key design decisions:

• Single values.yaml with sensible defaults — operators override only what differs per cluster
• ConfigMap for non-secret config — NEXTAUTH_URL, FASTAPI_ROOT_PATH, worker count, S3 bucket
• Kubernetes Secret for credentials — MongoDB URI, API keys, NextAuth secret — created by the deploy script, never stored in the chart
• Ingress host derived from APP_HOST — a single variable drives the entire URL configuration

Choosing a Container Registry

We evaluated two natural options: Amazon ECR (since we’re already on AWS/EKS) and GitHub Container Registry (ghcr.io) (since our source is on GitHub).

ECR has one significant operational advantage for EKS: nodes authenticate via IAM role, so there is no image pull secret to manage. Costs are low — $0.10/GB stored, with no data transfer charge for pulls within the same AWS region. However, ECR is tightly coupled to AWS. A second deployment on Digital Ocean or a customer’s on-premises cluster would need separate registry credentials and mirroring, making it a poor fit for a multi-cloud or self-hosted product.

ghcr.io is cloud-neutral — any cluster anywhere can pull images with a single token. It integrates naturally with GitHub Actions (the GITHUB_TOKEN secret already has packages: write permission), so publishing images is zero-configuration. The chart package also appears directly on the repository’s GitHub page alongside the source code and releases, which is the right home for an open-source project.

The catch: ghcr.io packages are private by default for organizations, and GitHub’s free tier includes only 500 MB storage and 1 GB transfer per month. For clusters that pull large images repeatedly, those limits are reached quickly. Making packages public eliminates the cost entirely, but requires an organization admin to enable public package creation in the org settings — it is disabled by default.

We chose ghcr.io and made our packages public. The images contain no secrets — only application code — so public visibility is appropriate and keeps infrastructure simple. Clusters pull anonymously with no credentials required.

For customers who need private images (for example, an enterprise build with proprietary integrations), the REGISTRY_PROVIDER variable in the overlay .env file can be switched to aws or do to use ECR or Digital Ocean Container Registry instead, with registry login handled automatically by the deploy scripts.

Merging Workers into FastAPI

The original architecture ran the background workers (OCR, LLM, KB indexing, webhooks) as a separate process alongside uvicorn. In Kubernetes, this meant each backend pod ran two Python processes, consuming ~375 MB of memory.

We merged the workers into the FastAPI lifespan using asyncio.create_task:

@asynccontextmanager
async def lifespan(app):
    # startup
    worker_tasks = start_workers(n_workers)
    yield
    # shutdown
    for task in worker_tasks:
        task.cancel()
    await asyncio.gather(*worker_tasks, return_exceptions=True)

This halved per-pod memory usage (~190 MB) and eliminated the process management overhead. The workers share the same event loop as the API, which is safe because all worker I/O is already async.

Worker Polling Optimization

With multiple replicas, each pod runs a full set of worker coroutines polling MongoDB queues. At idle with 4 workers per pod, that was ~80 MongoDB queries per second cluster-wide.

We implemented exponential backoff with shared state across parallel workers:

_queue_idle_sleep: dict[str, float] = {}  # shared across all workers on a queue

# on idle: back off
sleep = _queue_idle_sleep.get("ocr", POLL_MIN_SLEEP)
await asyncio.sleep(sleep)
_queue_idle_sleep["ocr"] = min(sleep * 2, POLL_MAX_SLEEP)

# on message found: reset for all workers on this queue
_queue_idle_sleep["ocr"] = POLL_MIN_SLEEP

This reduces idle polling to near-zero while keeping response latency low when work arrives.

Graceful Shutdown

When Kubernetes scales down a pod (HPA scale-in or rolling update), it sends SIGTERM. We needed in-flight jobs to be marked as failed rather than silently abandoned.

Since workers are asyncio tasks, cancellation arrives as asyncio.CancelledError — a BaseException, not caught by except Exception. We added explicit handling in each worker:

try:
    await ad.msg_handlers.process_ocr_msg(analytiq_client, msg)
except asyncio.CancelledError:
    logger.warning(f"Worker cancelled mid-flight on msg {msg.get('_id')}, marking failed")
    await ad.queue.delete_msg(analytiq_client, "ocr", str(msg["_id"]), status="failed")
    raise  # allow the task to actually cancel

The failed job can then be retried on another pod.

Database Migrations as a Helm Pre-Upgrade Hook

Running database migrations safely in a multi-replica environment requires that migrations complete before any new application code starts serving traffic. In Docker Compose this is handled by startup ordering, but in Kubernetes rolling updates, new pods can start before old ones are gone — with no guarantee about migration timing.

We solved this with a Helm hook Job that runs migrate.py using the same backend image, annotated to execute before the upgrade rolls out:

annotations:
  "helm.sh/hook": pre-upgrade,pre-rollback
  "helm.sh/hook-weight": "-5"
  "helm.sh/hook-delete-policy": hook-succeeded,before-hook-creation

The pre-upgrade hook ensures migrations run and complete successfully before Helm touches any Deployment. If the migration Job fails, Helm aborts the upgrade entirely — the old version keeps running. hook-delete-policy: hook-succeeded cleans up the completed Job automatically, keeping the namespace tidy. The before-hook-creation policy ensures the old Job is removed if a previous run left one behind.

One subtlety: at pre-upgrade time, the ConfigMap has not yet been updated by Helm (hooks run before regular resources). The migration Job therefore mounts only the Secret — which contains MONGODB_URI — and not the ConfigMap:

envFrom:
- secretRef:
    name: doc-router-secrets
# ConfigMap intentionally omitted — not yet updated at hook time

This means migrate.py must be written to need only the database connection string, with no dependency on application config values.

The result is a safe, atomic upgrade sequence: migrate → roll out new pods → terminate old pods — with automatic rollback if the migration fails.

HPA Tuning

We configured Horizontal Pod Autoscaler on the backend with both CPU and memory targets:

metrics:
- type: Resource
  resource:
    name: cpu
    target:
      type: Utilization
      averageUtilization: 80
- type: Resource
  resource:
    name: memory
    target:
      type: Utilization
      averageUtilization: 80

A subtle issue: HPA scale-down uses ceil(currentReplicas × currentUtil / targetUtil). With 5 pods at 72% memory utilization against an 80% target, ceil(5 × 72/80) = ceil(4.5) = 5 — the ceiling arithmetic created a deadlock where the cluster could never scale below 5 pods.

The fix was increasing the memory request from 512 Mi to 768 Mi. After the worker merge reduced actual usage to ~190 MB, utilization dropped to ~25% — well below the threshold — and the cluster scaled back down to the minimum of 2 replicas.

Environment Configuration

Next.js NEXT_PUBLIC_* variables are baked into the browser bundle at build time, not injected at runtime. This caused a subtle bug: our local .env.local file set NEXT_PUBLIC_FASTAPI_FRONTEND_URL=http://127.0.0.1:8000. Because .env.local wasn’t listed in .dockerignore, it was copied into the Docker build context and read by Next.js during npm run build — silently overriding the intended production value and baking the localhost URL into every image.

We fixed this in two steps:

1. Exclude all .env.* files from the Docker build context by adding **/.env.* to .dockerignore, so local development env files can never leak into images.

2. Remove NEXT_PUBLIC_FASTAPI_FRONTEND_URL entirely. Rather than baking an absolute URL into the bundle, the frontend now always calls /fastapi — a relative path that works from any hostname. Next.js rewrites proxy /fastapi/:path* to the backend service URL at the server layer:

// next.config.mjs
async rewrites() {
  return [{
    source: '/fastapi/:path*',
    destination: `${process.env.FASTAPI_BACKEND_URL}/fastapi/:path*`,
  }];
}

FASTAPI_BACKEND_URL is a server-side runtime variable (not NEXT_PUBLIC_) pointing to the in-cluster backend service (http://backend.<namespace>.svc.cluster.local:8000). It is never exposed to the browser. The result is a truly environment-agnostic frontend image that requires no rebuild when moving between clusters.

CI/CD Pipeline

Structure

We use three GitHub Actions workflows:

• backend-tests.yml — runs Python tests against a local MongoDB Atlas instance (with vector search via mongodb-atlas-local) plus TypeScript tests. Triggered by workflow_call or workflow_dispatch.
• frontend-build.yml — runs npm run build for the Next.js frontend. Also triggered by workflow_call or workflow_dispatch.
• ci.yml — runs both test workflows on every pull request to main.
• release.yml — triggered on semver tags (v[0-9]*.[0-9]*.[0-9]*). Runs both test workflows first, then builds and pushes Docker images if they pass.

Why semver tags, not branch pushes

An early version of the pipeline ran tests on every push to main and triggered builds from there. This caused two problems:

1. Tests ran twice per release — once on the branch push, once triggered by the tag.
2. The tag trigger didn’t wait for tests — if a tag was pushed immediately after a commit, the build could race ahead of a still-running test run.

The current design avoids both: release.yml is only triggered by a semver tag, and the build-push job declares needs: [test-backend, test-frontend], so Docker images are never built unless all tests pass on that exact commit. Tests run exactly once per release.

The ci.yml workflow handles the PR gate separately — developers get test feedback on their branch without triggering a build.

Reusable test workflows

Making the test workflows workflow_call-able (rather than duplicating the job definitions in both ci.yml and release.yml) keeps the test logic in one place. Both workflows call the same definitions; any change to the test steps is automatically reflected in both gates.

workflow_dispatch is kept on each test workflow so that individual test suites can be re-run manually from the GitHub Actions UI without needing to push a commit or tag.

Image tagging

The build step computes image tags from the git tag:

TAG="$"          # e.g. v27.0.1-rc2 or v27.0.1
FRONTEND_TAGS="${FRONTEND}:${TAG}"
# :latest only for stable releases (no pre-release suffix)
if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  FRONTEND_TAGS="${FRONTEND_TAGS},${FRONTEND}:latest"
fi

Release candidates (v27.0.1-rc2) get a versioned tag only. Stable releases (v27.0.1) also update :latest. This means a cluster running :latest auto-updates on the next helm upgrade, while a cluster pinned to a specific tag is unaffected.

Helm chart publishing is manual

The Helm chart is published separately with ./deploy/scripts/publish-chart.sh <overlay>. We kept this manual for two reasons: the chart version is independent of the app version (you might push 10 image releases without any chart changes), and publishing the chart is a deliberate operator action — it should not happen automatically on every tag.

Egress IPs and External Service Whitelisting

A practical difference between EKS and DOKS emerged when connecting to MongoDB Atlas, which requires IP whitelisting for all incoming connections.

On EKS, the cluster’s private node group sits behind a single NAT gateway. All outbound traffic from every pod — regardless of which node it runs on — exits through one stable public IP. Adding that single IP to MongoDB Atlas’s allowlist is all that’s needed, and the IP never changes when nodes are replaced or the cluster scales.

On DOKS, there is no NAT gateway by default. Each node is assigned its own public IP, and pods reach the internet directly through the node they’re scheduled on. This means:

• There is no single egress IP — the source address MongoDB sees depends on which node the backend pod happens to be running on.
• With two nodes, you need two IPs in the allowlist. With autoscaling, new nodes get new IPs, and the allowlist breaks until you add them.

For a fixed-size dev cluster, the workaround is to whitelist all current node IPs. For a production DOKS cluster with autoscaling, the correct solution is to provision a Digital Ocean Load Balancer as a NAT gateway, routing all cluster egress through a single stable IP. This adds ~$12/month but is the only reliable option when the external service requires a static source address.

For our dev cluster (doc-router-dev), we whitelist the two node IPs directly. For production DOKS deployments, a managed NAT gateway is required.

Overlay-based Deploy Scripts

Rather than a one-size-fits-all deploy script, we use an overlay pattern:

.env              # shared defaults (local dev values)
.env.eks-test     # overrides for the test EKS cluster
.env.eks-prod     # overrides for production

The deploy scripts (k8s-deploy.sh, build-push.sh) accept an overlay name and source both files, with the overlay taking precedence. A single variable — APP_HOST — drives all URL configuration, making it straightforward to add a new environment. k8s-deploy.sh is idempotent — it uses helm upgrade --install and handles both fresh installs and rolling updates without any distinction.

What’s Next

• On-premises distribution — Helm chart and images are public on ghcr.io; self-hosted MongoDB is available via the mongodb-atlas-local chart (see Self-Hosted MongoDB on Kubernetes with Atlas Search); documentation for a one-command on-prem install is the next step
• Offline license keys — JWT-based licenses signed with a private key, verified against a public key baked into the image, for air-gapped installations
• Multi-cloud support — Digital Ocean Kubernetes is now supported alongside EKS; Azure Kubernetes Service support is planned

Andrei Radulescu-Banu is the founder of DocRouter.AI (document processing with LLMs) and SigAgent.AI (Claude Agent monitoring). His company AnalytiqHub.com provides consulting services for cloud and AI engineering.

The manifest problem

A real Kubernetes application needs dozens of YAML files: Deployments, Services, ConfigMaps, Secrets, Ingress rules, HorizontalPodAutoscalers, PodDisruptionBudgets. Writing them by hand is feasible once, but the moment you need the same app running in three environments — local, staging, production — you face a choice:

• Copy the files for each environment and keep them in sync manually (fragile)
• Use a tool that handles the variation for you

Two tools dominate: Kustomize and Helm. They solve the same problem differently, and many projects use both — Helm for third-party software, Kustomize for their own app.

Kustomize — layered YAML patches

Kustomize ships with kubectl (no install needed) and works with plain YAML. The idea is a base + overlays structure:

manifests/
  base/
    deployment.yaml      # canonical deployment
    service.yaml
    kustomization.yaml   # lists the resources
  overlays/
    dev/
      kustomization.yaml # patches for dev
      patch-replicas.yaml
    prod/
      kustomization.yaml # patches for prod
      patch-replicas.yaml
      patch-resources.yaml

The base defines the resource once. Each overlay patches only what differs. A typical patch looks like:

# overlays/prod/patch-replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: 4       # override base value of 2

To deploy the prod overlay:

kubectl apply -k overlays/prod/

Kustomize merges the base YAML with all patches before sending anything to the API server. You always see plain, readable YAML — there is no templating language to learn, and the output is predictable.

Variable substitution

For values that vary by environment (hostnames, image tags, resource sizes), Kustomize offers substituteFrom: it reads variables from a ConfigMap or Secret and injects them into the manifests at apply time:

# kustomization.yaml
configurations:
  - var-references.yaml
vars:
  - name: APP_DOMAIN
    objref:
      kind: ConfigMap
      name: project-values
      apiVersion: v1
    fieldref:
      fieldpath: data.domain

This is less flexible than Helm’s full templating but keeps the YAML closer to what Kubernetes actually receives.

What Kustomize does not do

Kustomize has no concept of a release, no revision history, and no built-in rollback. If you apply a broken overlay, you must fix it and reapply, or manually apply a previous version. For the same reason, there is no --atomic safety net — if a deployment fails mid-rollout, you notice from kubectl output, not from the packaging tool.

Helm — templated packages

Helm wraps Kubernetes YAML in a full templating engine (Go templates) and adds lifecycle management on top. A chart is a directory:

doc-router/
  Chart.yaml          # name, version, appVersion
  values.yaml         # default values
  templates/
    deployment.yaml   # Go template
    service.yaml
    ingress.yaml
    _helpers.tpl      # reusable template fragments

A template looks like:

# templates/deployment.yaml
spec:
  replicas: 
  template:
    spec:
      containers:
        - name: backend
          image: ":"
          resources:
            requests:
              cpu: 

To install with custom values:

helm upgrade --install doc-router ./doc-router \
  --set replicaCount=4 \
  --set image.tag=v1.2.3

Or via an override file:

helm upgrade --install doc-router ./doc-router -f values-prod.yaml

Release history and rollback

Helm records every install and upgrade as a numbered revision in the cluster. You can inspect history and roll back:

helm history doc-router -n doc-router
helm rollback doc-router 2 -n doc-router   # back to revision 2

With --atomic, a failed upgrade automatically triggers a rollback — the old version keeps running uninterrupted.

Publishing charts as OCI artifacts

A packaged chart can be pushed to any OCI-compatible registry (ghcr.io, ECR, Docker Hub) and pulled from anywhere:

helm push doc-router-0.3.7.tgz oci://ghcr.io/analytiq-hub
helm upgrade --install doc-router oci://ghcr.io/analytiq-hub/doc-router --version 0.3.7

This means a customer cluster can install your app with a single command, pulling both the chart and images from the same registry, with no Git access required.

Kustomize vs Helm — when to use each

In practice many projects use both: Helm for installing third-party dependencies (ingress-nginx, cert-manager, MongoDB operator), and Kustomize for their own application manifests. The two are compatible — a Kustomize overlay can reference a Helm chart as a generator.

GitOps — the cluster manages itself

Both Kustomize and Helm, as described so far, are imperative: a human (or a CI job) runs a command that pushes changes into the cluster. GitOps flips this model.

In GitOps, the desired cluster state is declared in a Git repository (or an OCI artifact registry). A controller running inside the cluster continuously watches that source and reconciles actual state to match it. No one runs helm upgrade — the cluster pulls its own updates.

Developer pushes to Git / CI pushes OCI artifact
         ↓
  Source of truth updated
         ↓
  In-cluster controller detects drift
         ↓
  Controller applies the diff
         ↓
  Cluster matches desired state

The key property: the cluster self-heals. If someone manually deletes a Deployment or edits a ConfigMap, the controller notices the drift and reverts it within seconds. The Git repo (or OCI artifact) is always the authoritative source.

Flux — a GitOps controller

Flux is one of the two dominant GitOps controllers (the other is Argo CD). It runs as a set of controllers in the cluster and watches sources:

Sources

Flux can watch:

• Git repositories — on every push, Flux reconciles the cluster
• OCI artifact registries — on every flux push artifact, Flux pulls and applies
• Helm repositories — for managing Helm releases declaratively

Core resources

GitRepository / OCIRepository — defines where Flux watches:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  url: oci://123456789.dkr.ecr.us-east-1.amazonaws.com/my-app-manifests
  ref:
    tag: latest

Kustomization — tells Flux what to apply from the source:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  sourceRef:
    kind: OCIRepository
    name: my-app
  path: ./manifests/kubernetes/overlays/prod
  prune: true      # delete resources removed from source
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: backend
      namespace: my-app

HelmRelease — manages a Helm release declaratively:

apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: ingress-nginx
  namespace: flux-system
spec:
  interval: 1h
  chart:
    spec:
      chart: ingress-nginx
      version: "4.11.3"
      sourceRef:
        kind: HelmRepository
        name: ingress-nginx
  values:
    controller:
      replicaCount: 2

CI/CD with Flux

A typical Flux-based pipeline looks like:

1. Developer opens a PR
2. CI runs tests
3. PR merged to main
4. CI builds Docker image → pushes to ECR
5. CI packages Kustomize manifests as OCI artifact → flux push artifact → ECR
6. Flux detects new artifact version
7. Flux applies manifests to cluster
8. Cluster rolls out new Deployment

Steps 6–8 happen automatically, inside the cluster, with no deploy script and no human intervention.

Flux vs running deploy scripts

GitOps is the right choice for teams with multiple people deploying to shared clusters, or for production environments where drift must be detected and prevented. For a small team or a self-hosted product where simplicity matters, shell scripts with helm upgrade --install are easier to understand, debug, and hand off to a customer.

Summary

A mature production setup typically uses all three: Kustomize or Helm for defining manifests, Flux or Argo CD for reconciling them, and a CI pipeline that produces the artifacts both consume.

Next: Deploying Doc Router on Kubernetes walks through a real application deployment (Helm chart, workers, CI/CD, EKS and Digital Ocean). If you need in-cluster MongoDB with vector search, see Self-Hosted MongoDB on Kubernetes with Atlas Search.

Andrei Radulescu-Banu is the founder of DocRouter.AI (document processing with LLMs) and SigAgent.AI (Claude Agent monitoring). His company AnalytiqHub.com provides consulting services for cloud and AI engineering.

Here’s how the key concepts map across.

From containers to Pods

In Docker Compose, the unit of work is a container. In Kubernetes, it is a Pod — a group of one or more containers that always run together on the same machine and share a network namespace. Most Pods contain a single container, but some use sidecars: a main process plus a helper (a log shipper, a proxy, or in our case the mongot search process alongside mongod).

Pods are ephemeral. When a Pod dies, Kubernetes replaces it with a new one — possibly on a different machine, with a new IP address. You never SSH into a Pod or rely on its IP being stable.

Deployments — the equivalent of a Compose service

A Deployment tells Kubernetes: “keep N replicas of this Pod running at all times.” If a Pod crashes, the Deployment controller starts a replacement. If you push a new image, it performs a rolling update — starting new Pods before terminating old ones so traffic is never interrupted.

In Docker Compose terms, a Deployment is your service: block plus restart policies and rolling update logic built in.

Services — stable internal addresses

Because Pod IPs change on every restart, Kubernetes introduces Services: stable DNS names and virtual IPs that front a group of Pods. A Service named backend in the doc-router namespace is reachable at backend.doc-router.svc.cluster.local from anywhere in the cluster, regardless of how many backend Pods exist or where they are running.

This replaces the automatic DNS that Docker Compose sets up between containers on the same network.

Namespaces — isolation within a cluster

A Namespace is a logical partition of the cluster. Resources in different namespaces don’t collide even if they share a name. A typical setup uses separate namespaces for each concern: doc-router for the application, mongodb for the database, ingress-nginx for the load balancer, cert-manager for TLS certificates.

In Docker Compose terms, a namespace is roughly equivalent to a separate Compose project — distinct networks and name scopes.

ConfigMaps and Secrets — environment variables at scale

Docker Compose lets you set environment: variables inline or via an .env file. Kubernetes separates non-sensitive config from sensitive config:

• ConfigMap — key-value pairs mounted as environment variables or files. Used for things like FASTAPI_ROOT_PATH, worker count, S3 bucket name.
• Secret — base64-encoded values stored (optionally encrypted at rest) separately from your app manifests. Used for database URIs, API keys, and auth secrets. Pods reference Secrets by name; the values are injected at runtime, never baked into the image.

PersistentVolumeClaims — durable storage

Docker Compose uses named volumes (backed by the local filesystem) to persist data across container restarts. Kubernetes uses PersistentVolumeClaims (PVCs): a request for a piece of storage of a given size and access mode. The cluster fulfils the claim by provisioning a real volume — an EBS disk on AWS, a DO Block Storage volume on Digital Ocean — and mounting it into the Pod.

PVCs survive Pod restarts and rescheduling. If a database Pod moves to a different node, the volume is detached and reattached automatically. Storage is provisioned dynamically by a StorageClass, which specifies the provisioner (e.g. ebs.csi.aws.com on EKS) and volume type.

Ingress and the load balancer

In Docker Compose you typically expose one port from one container. In Kubernetes, multiple Services need to be reachable from the outside under different paths or hostnames, all through a single external IP.

ingress-nginx is a Kubernetes controller that runs an nginx reverse proxy inside the cluster. When deployed on EKS, it automatically provisions an AWS Network Load Balancer with a stable public IP. You define Ingress rules — “route /fastapi to the backend Service, everything else to the frontend Service” — and ingress-nginx handles the routing. On a new cluster, the load balancer is the only resource with a public IP; everything else is internal.

cert-manager — automatic TLS

cert-manager is a Kubernetes controller that watches Ingress resources and automatically requests TLS certificates from Let’s Encrypt. When you annotate an Ingress with cert-manager.io/cluster-issuer: letsencrypt-prod, cert-manager handles the ACME challenge, obtains the certificate, stores it in a Secret, and renews it before it expires. You never touch a certificate manually.

Helm — packaging it all together

Kubernetes resources are defined as YAML files. A real application needs dozens of them: Deployments, Services, ConfigMaps, Secrets, Ingress rules, PodDisruptionBudgets. Helm is the package manager for Kubernetes — it bundles all those YAML files into a chart, parameterises them with a values.yaml file, and installs or upgrades the whole bundle with a single command:

helm upgrade --install doc-router oci://ghcr.io/analytiq-hub/doc-router \
  --namespace doc-router --set appHost=example.com ...

A chart can be published as an OCI artifact to any container registry alongside the Docker images.

If Docker Compose is a docker run wrapper, Helm is closer to an apt package: versioned, reproducible, and upgradeable.

How Helm applies changes

Every time you run helm upgrade, Helm compares the new rendered YAML against what it last applied and sends only the diff to the Kubernetes API — resources that haven’t changed are left untouched. Helm records each upgrade as a numbered revision, stored as a Secret in the cluster:

$ helm history doc-router -n doc-router
REVISION  STATUS     CHART           APP VERSION  DESCRIPTION
1         superseded doc-router-0.3.5  v27.0.0    Install complete
2         superseded doc-router-0.3.6  v27.0.1    Upgrade complete
3         deployed   doc-router-0.3.7  v27.0.2    Upgrade complete

Rolling back to a known-good state

If an upgrade goes wrong, rolling back to the previous revision is a single command:

helm rollback doc-router -n doc-router        # rolls back to revision 2
helm rollback doc-router 1 -n doc-router      # rolls back to a specific revision

Helm re-applies the exact YAML from that revision — the same image tags, the same config values — so the cluster returns to the state that last worked. Using --atomic during an upgrade makes this automatic: if the new Pods don’t become healthy within the timeout, Helm rolls back on its own without any manual intervention.

Zero-downtime rolling updates

When Helm upgrades a Deployment with a new image, Kubernetes does not restart all Pods at once. It uses a rolling update strategy controlled by two parameters:

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxUnavailable: 0   # never take a pod down before a new one is ready
    maxSurge: 1         # allow one extra pod above the desired count during the rollout

With maxUnavailable: 0, Kubernetes starts a new Pod with the new image first. Only after that Pod passes its readiness probe — meaning it is actually serving traffic — does Kubernetes terminate one of the old Pods. This continues one Pod at a time until all replicas are on the new version. At no point does the number of healthy Pods drop below the desired count.

The result: an upgrade from v27.0.1 to v27.0.2 with two replicas proceeds as:

1. Start new Pod (v27.0.2) — 2 old + 1 new running
2. New Pod passes readiness check
3. Terminate one old Pod — 1 old + 1 new running
4. Start second new Pod — 1 old + 2 new running
5. Second new Pod passes readiness — terminate last old Pod
6. Rollout complete — 2 new Pods running, zero downtime

If the new Pod fails its readiness check at step 2, the rollout pauses. No old Pods have been terminated, so the old version continues serving 100% of traffic. With --atomic, Helm then rolls the release back automatically.

Running Kubernetes locally with Kind

Before deploying to a real cluster, it’s useful to test locally using Kind (Kubernetes in Docker). Kind runs an entire Kubernetes cluster — control plane and worker nodes — as Docker containers on your laptop. There is no cloud provider, no load balancer, and no cloud volumes; Kind uses your local filesystem for storage and NodePort services for external access.

./deploy/scripts/setup-kind.sh   # creates the Kind cluster
./deploy/scripts/deploy-kind.sh  # installs the Helm chart locally

The same chart that runs on EKS runs on Kind, with a different values-kind.yaml override file. This lets you iterate on chart changes without incurring cloud costs or waiting for node provisioning.

Summary

Next: Kubernetes Packaging and Deployment: Kustomize, Helm, and GitOps goes deeper into packaging manifests and GitOps with Flux.

Andrei Radulescu-Banu is the founder of DocRouter.AI (document processing with LLMs) and SigAgent.AI (Claude Agent monitoring). His company AnalytiqHub.com provides consulting services for cloud and AI engineering.

Table of Contents

• Why Use Stripe?
• How Stripe Payments Get Handled
• SPU Credits
• Pricing Strategy For AI Products
• DocRouter.AI Software Stack
• Free Tier, Plans, and A-La-Carte Credits
• Prices for Large vs. Small Customers
• Price Changing Flexibility
• Environment Variables
• The Stripe Product and Price Metadata
• Python APIs for Retrieving Products and Prices
• Stripe Checkout and Billing Portal
• Webhooks and Synchronization
• MongoDB Schema
• Tracking SPU Usage
• Development and Testing with Stripe
• Need Help with Your Pricing Strategy?

Why Use Stripe?

Stripe handles the credit card transactions, and handles global currencies/taxes. For an AI app with variable usage, it’s essential — manual billing would be error-prone and slow. Companies using Stripe don’t need to deal with credit cards. They only need to identify the customers by a unique customer ID managed by Stripe.

How Stripe Payments Get Handled

Stripe supports:

• subscriptions for recurring plans
• one-time charges for credits,
• webhooks for real-time updates.

It also supports metered charges, but we will not use the Stripe implementation for meters. It is more convenient to implement our own metered support, keeping track on our platform of usage, and charge through Stripe the monthly cost.

SPU Credits

On DocRouter.AI, customers purchase credits called SPUs (Service Processing Units) - this is our abstraction for document page processing, and for LLM token use. Many other SAAS companies use a credit-purchase based mechanism. For example, Databricks measures credits as DBUs (Databricks Processing Units), and charges hourly cluster usage a number of DBUs that depends on the cluster size.

As long as the credit units are tied to predictable units of operation - for example, number of pages processed in a document - a credit purchase mechanism is a good choice.

Pricing Strategy For AI Products

When setting up pricing through Stripe, you have to be strategic. You need to cover the needs of Enterprise customers, but also small companies and occasional users. Some customers prefer to purchase credits a-la-carte, while others prefer the predictability of a monthly subscription.

Pricing must be tailored to all types of customers you have at the current stage - and, has to be as simple as possible.

The diagram below describes different pricing strategies practiced in the industry:

Ideally, products would be priced with an Outcome-Base Model (top right quadrant). This works well if a business is vertical in an industry, and if product value has high attribution.

DocRouter.AI is a horizontal, data-layer product - and uses a Hybrid Pricing Model based on monthly subscriptions and/or a-la-carte SPU credit purchases.

DocRouter.AI Software Stack

• The DocRouter.AI front end is Next.JS, with Next.Auth user authentication
• The back end is Fast API
• Our database is MongoDB

DocRouter supports agentic Claude Code integration and MCP, allowing document workflows to be controlled through a simple chat interface.

Users control all DocRouter.AI functions either through the UI, or through REST APIs, using access tokens. A Python SDK and a Typescript SDK are available.

Having the flexibility to control DocRouter programmatically, either through agentic interfacing, or through APIs is great.

However, use tracking (aka metered billing) has to be automated, and the customer needs to be charged a small percentage above the underlying cost charged by LLM and cloud providers.

Stripe integration is, thus, an essential ingredient in making this kind of programmatic integration possible.

Free Tier, Plans, and A-La-Carte Credits

When you are starting, the best pricing is a simple one that your customer understands - especially for self-onboaded customers.

For DocRouter, we want users to start free, upgrade to plans, and be able to buy extra credits without friction. Here’s how we did it:

New orgs get 100 granted SPUs (no card needed). Additional credits can be purchased. Users can subscribe to an Individual or Team plan, at a discount over the a-la-carte credits price. Or, they can select the Enterprise plan, which is invoiced outside of Stripe where we can charge based on the customer outcomes (aka outcomes-based pricing).

Prices for large vs. small customers

The business challenge here is for the pricing scheme to be flexible enough to accommodate large enterprise usage, at custom prices - while also allowing self-onboarded customers.

Consumption waterfall: allowance first, then purchased, then granted. Keeps costs low for light users, upsell for heavy ones.

The prices need to be in line with what is usually charged for document AI processing - while also capturing the value of more advanced, custom document workflows.

Price changing flexibility

The engineering challenge is, on the other hand, in how to create this pricing structure in Stripe, and ensure the variable part of the config (amounts, utilization thresholds) resides in Stripe configuration rather than local DocRouter.AI code.

Updating amounts or utilization thresholds at a later time should not require coding changes in DocRouter.AI. These updates should be possible by merely chaging price configuration in Stripe.

Pricing updates, however, does not impact existing customers (aka grandfathering).

How does it all work?

Environment Variables

Three Stripe-related environment variables are configured for integration:

STRIPE_SECRET_KEY - Your Stripe API key for authentication. Required to enable Stripe integration.

STRIPE_WEBHOOK_SECRET - Secret for verifying webhook signatures. The DocRouter.AI webhook is called by Stripe when various events happen: a user started or stopped a subscription, or purchased a-la-carte SPU credits.

STRIPE_PRODUCT_TAG - The product identifier in metadata (default: "doc_router"). Allows filtering prices to find only those belonging to your product.

If STRIPE_SECRET_KEY is not set, Stripe integration is disabled and DocRouter operates in local-only mode.

The Stripe Product and Price metadata

Stripe uses the following ‘objects’: Products, Prices (multiple per product), Users (one per customer), and Subscriptions (each with one or more Prices.

We could identify the Products and the Prices by stripe IDs saved as environment variables, similar to how we use the STRIPE_SECRET_KEY. However, that is not an advantageous way to set things up.

Instead, we detect Products and Prices by reading their metadata in Stripe, and filtering for the Products and Prices configured for our company.

This way, a single Stripe account can be used as an umbrella for potentially multiple products, allowing for future extensibility.

• We create a Stripe DocRouter Product

• And we assign it a product=doc_router key/value in the price metadata. The DocRouter.AI software detects the product using the Stripe Python API, filtering all products to find specifically the one with this key/value.

• We create two recurring Prices we’ll use for monthly subscriptions: the Individual Price, and the Team Price. We again use metadata to auto-detect the prices:

  • The Individual Price has metadata included_spus=5000, price_type=base, tier=individual.
  • The Team Price has included_spus=25000, price_type=base, tier=team

The DocRouter.AI detects the prices and the tier limits from the metadata.

Python APIs for Retrieving Products and Prices

DocRouter.AI uses the Stripe Python SDK to dynamically fetch pricing configuration at startup. The complete implementation can be found in our payments.py file. Here’s how the key parts work:

Retrieving All Prices with Product Data

prices = stripe.Price.list(active=True, expand=['data.product'])

The expand=['data.product'] parameter loads the full product object (including metadata) alongside each price in a single API call.

Filtering by Product Metadata

product_prices = [
    price for price in prices.data
    if price.product.metadata.get('product') == 'doc_router'
]

This filters prices to only those belonging to our DocRouter product.

Parsing Price Metadata

for price in product_prices:
    metadata = price.metadata
    price_type = metadata.get('price_type')

    if price_type == 'base':
        tier = metadata.get('tier')
        included_spus = metadata.get('included_spus')
        # Store tier limits for subscription plans

All pricing configuration lives in Stripe—we can update prices and tier limits without code changes.

Wrapping Stripe APIs for Async

Since DocRouter.AI uses FastAPI (an async framework), we wrap Stripe’s synchronous API calls to run in a thread pool:

async def _run_in_threadpool(func, *args, **kwargs):
    loop = asyncio.get_event_loop()
    return await loop.run_in_executor(None, partial(func, *args, **kwargs))

This prevents blocking the event loop. In practice, we call:

prices = await _run_in_threadpool(
    stripe.Price.list,
    active=True,
    expand=['data.product']
)

The wrapper runs the synchronous stripe.Price.list() in a separate thread, keeping our async FastAPI endpoints responsive.

Stripe Checkout and Billing Portal

Purchasing Credits

When users buy a-la-carte credits, we create a Stripe Checkout session:

session = stripe.checkout.Session.create(
    customer=stripe_customer_id,
    payment_method_types=['card'],
    line_items=[{...}],
    success_url=success_url,
    cancel_url=cancel_url,
    metadata={'org_id': org_id, 'credits': credits}
)

Users are redirected to Stripe’s hosted checkout page—we never see their credit card details. Stripe handles all payment security.

Managing Subscriptions

For subscription management, we use Stripe’s Billing Portal:

session = stripe.billing_portal.Session.create(
    customer=stripe_customer_id,
    return_url=return_url
)

The portal lets users update payment methods, view invoices, and cancel subscriptions—all handled by Stripe.

Webhooks and Synchronization

Stripe sends webhooks for important events. We verify and process them:

event = stripe.Webhook.construct_event(
    payload,
    signature_header,
    webhook_secret
)

Key events we handle:

• checkout.session.completed - Add purchased credits
• customer.subscription.updated - Sync subscription changes
• customer.subscription.deleted - Clear subscription data
• invoice.payment_succeeded - Record successful payments

To prevent double-crediting, we track processed transactions in the db.payments_credit_transactions collection.

On startup and via webhooks, we sync Stripe data to MongoDB. This keeps local data fresh without constant API calls.

MongoDB Schema

We store payment data in MongoDB collections:

payments_customers - One document per organization:

{
  org_id: "...",
  user_id: "...",
  stripe_customer_id: "cus_...",
  user_name: "...",
  user_email: "...",

  // Subscription fields
  subscription_type: "individual" | "team" | "enterprise",
  subscription_spu_allowance: 5000,
  subscription_spus_used: 1234,  // Reset each billing period
  stripe_subscription_id: "sub_...",
  stripe_subscription_item_id: "si_...",
  stripe_subscription_status: "active",
  stripe_current_billing_period_start: 1234567890,
  stripe_current_billing_period_end: 1237246290,

  // Credit fields
  purchased_credits: 10000,
  purchased_credits_used: 5000,
  granted_credits: 100,
  granted_credits_used: 50,

  // Metadata
  created_at: ISODate(...),
  updated_at: ISODate(...),
  subscription_updated_at: ISODate(...)
}

Subscription SPU usage (subscription_spus_used) is atomically reset each billing period. Subscription allowances renew monthly. Purchased and granted credits persist until consumed.

payments_credit_transactions - Audit trail for credit purchases:

{
  session_id: "cs_...",
  org_id: "...",
  credits: 1000,
  processed_at: ISODate(...)
}

payments_usage_records - Log of all SPU usage:

{
  org_id: "...",
  spus: 42,
  operation: "document_processing",
  source: "backend",
  timestamp: ISODate(...),
  llm_provider: "anthropic",
  llm_model: "claude-3-5-sonnet-20241022",
  prompt_tokens: 1234,
  completion_tokens: 567,
  total_tokens: 1801,
  actual_cost: 0.023
}

Tracking SPU Usage

When LLM calls are made, we increment SPU usage:

async def record_payment_usage(org_id, spus):
    # Consumption order: subscription → purchased → granted
    balances = await get_current_balances(db, org_id)
    consumption = calculate_consumption_breakdown(spus, balances)

    # Update balances atomically
    await update_customer_balances(db, customer_id, consumption)

    # Save usage record
    await save_complete_usage_record(db, org_id, spus, consumption)

The consumption waterfall ensures subscription credits are used first, then purchased, then granted.

Users view their credit utilization on the usage page. All data comes from MongoDB — no Stripe API calls needed to track usage, keeping the UI fast.

Development and Testing with Stripe

Stripe provides separate test and production environments. During development, we use test mode keys:

# .env for development
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRODUCT_TAG=doc_router

Test mode keys (sk_test_*) access a completely separate sandbox with its own customers, subscriptions, and products. You can:

• Create test products and prices in the Stripe Dashboard
• Use test credit cards (like 4242 4242 4242 4242) for checkout
• Trigger webhooks manually to test event handling
• View all transactions without affecting production data

For production, swap to live keys (sk_live_*). The same code works in both modes—Stripe automatically routes API calls to the correct environment based on the key prefix.

This separation lets us develop and debug payment flows safely without risking real customer data or charges.

Need Help with Your Pricing Strategy?

Take what you are thinking and try 10x that price for a fixed price. If they say yes, everyone is happy. If they say no, you can talk about fair pricing for the value you are providing for their business (aka Outcome-based pricing) typically aligned of a cost/revenue metric that matters a lot to your customer.

If you’re implementing your own pricing strategy and need expert advice, Randy Carlton offers consultation on pricing for AI and SaaS businesses.

1. Create the runtime infrastructure for the agent itself
2. Add tools for the task
3. Planning: Making agent tackle the specific problem you’re aiming to solve
4. Create a knowledge base the agent can use to inform its execution steps
5. Set up an evaluation infrastructure to track progress and catch agent mistakes
6. Integrate the agent into the larger application

Whether the AI agent is fully autonomous or works with human-in-the-loop oversight, development includes roughly the steps outlined above. Each step calls for its own set of techniques and tools.

Examples: Windsurf, Cursor and Claude Code

Let’s start with some examples the reader may be familiar with:

• AI Editors like Windsurf, Cursor, Github Copilot
• Command line tools like Claude Code.

The latter, Claude Code, also has a VSCode extension by the same name.

In each case, the underlying AI agents are integrated with the text editor (our Step 6).

While Windsurf, Cursor and Claude Code each have their own agent infrastructure (our Step 1), the latter, Claude Code is different in that it is available as a command line tool which can be executed standalone, in interactive or non-interactive mode.

Anthropic has also developed a Claude Agent SDK, with Typescript, Python and shell command flavors. The Claude Agent SDK can be used both for coding tasks and for more general tasks - for example, for document processing, or for support message processing, or for marketing research and outreach.

An Agent SDK is not available for Windsurf or Claude Code.

The knowledge base (Step 3) for these agents is embedded into the language models themselves. These coding agents can code in Python, Typescript, C, C++ or Java. The language models are trained on these programming languages.

While these agents do not technically require an external knowledge base for pure coding skills, they use a web search tool to look up product and API documentation. The web search tool comes handy when implementing coding tasks against specific coding libraries and APIs.

Windsurf, Cursor, Github Copilot use multiple-vendor language models, in addition to models used in-house. Claude Code on the other hand, only uses Anthropic language models.

Custom AI Agents, though, don’t have all necessary knowledge baked into their LLM model - and often need an external knowledge base, adapted to their task (Step 3).

For example - one of our customer companies develops a lab information management system that uses a scripting language to define web forms. The forms are used to manage lab processes in Biotech, Food Manufacturing, or Forensics. The AI Agent we developed employs an external knowledge base to provide full documentation and examples for the scripting language. The generalist LLMs, while trained on Python, Typescript and other programming languages, would not have baked-in information about the custom scripting language for web forms.

Custom AI agents need to implement their own external knowledge base and problem-solving tools. These are both integrated into the Agent using an MCP Server.

MCP support is already available in all AI Editors. The editors can act as MCP Clients, and can, for example, read external Github repositories through a Github MCP Server. Any MCP Server is supported.

An MCP Server, thus, can be used to make your AI agent act on your specific tasks, and to access your external knowledge base.

But having the tools and the knowledge base is not sufficient. The agent must also be steered through task planning (our Step 4).

The approach each of the AI editors takes to steer their coding task is proprietary, and slightly different. A lot of the steering is done through proprietary system prompts. Some have reverse engineered these system prompts through intercepting API calls - but, for the most part, they remain hidden.

Each AI editor, however, supports extending the system prompt through a configuration file: CLAUDE.md for Claude Code, Cursor Rules for Cursor,Windsurf Rules for Windsurf. It is these configuration files - CLAUDE.md in particular - that will be used to steer our Custom AI Agent.

Windsurf, Cursor, Github Copilot also use a tab-completion model, which employs a smaller, faster LLM acting directly in the editor buffer. Claude Code does not have that feature.

Evaluation for these AI editors is also proprietary (Step 5). Custom AI Agents would need their own evaluation infrastructure developed from scratch.

Here is a Comparison Table for the AI editors we described:

Separation of concerns: Infrastructure vs. Task-Specific Planning

When it comes to building the agent, we separate out the Infrastructure design from the Task Planning, for a couple of reasons:

• Often times, the task solved by the agent needs to be flexible and can change in the product lifecycle. This calls for infrastructure to be separated out from the task customization. Sometimes, the task or its subtasks are not even fully known or understood at the outset of the AI Agent project.
• The infrastructure is now available ready-made, and may not have to be built from scratch.

Adopting a ready-made, battle tested AI Agent Infrastructure that is steerable for your task will accelerate your AI Agent design.

The AI Agent Infrastructure

As of this writing, our go-to stack for agent creation is the Claude Code shell command, complemented by the Claude Agent SDK. Its advantages:

• A suite of powerful features like CLAUDE.md customization, subcommands for modular execution, subagents for hierarchical delegation
• MCP server support, which lets you seamlessly extend the agent, and steer it to solve the task at hand.
• Built-in prompt caching, and discounted packaged price for utilization, when using a Claude subscription.

No agent is complete without a solid knowledge base, and without good evaluation infrastructure.

The Claude Agent SDK doesn’t ship with either out of the box. You’ll need to craft them yourself.

For the vector database powering the knowledge base, we’ve used Pinecone, prized for its straightforward SaaS model that gets you up and running quick. Pinecone documentation is also very accessible.

That said, there are multiple Vector DB alternatives: Weaviate, Qdrant, or ChromaDB. Even traditional players like Postgres or MongoDB have jumped on the vector bandwagon, now offering built-in support for vector tables or collections.

In our architecture, we centralize all custom interfaces for the agent within the MCP server. This ensures portability and testability across setups. The MCP server includes a vector_db_lookup() interface to let the agent look up the knowledge base.

Indexing Your Knowledge Base

To build the knowledge base, you need:

• A collection of knowledge base files - we usually convert them all to Markdown, and store them in an S3 bucket, or in a MongoDB collection
• A vector DB index in your DB of choice
• An indexing script, that runs periodically, and uploads the knowledge base markdown files into the vector DB index, mapped through an LLM embedding.

The lookup operation is what you’d expect - the searched text is mapped through the same LLM embedding, and looked up for similarity with existing chunks in the vector db index - returning the most closely similar chunks from the knowledge base.

Tuning AI Agent Actions via the MCP Server

With the knowledge base available, and searchable - we now let the AI agent use it through MCP Server tools.

These tools can:

• Look up knowledge base articles for similarity
• Perform file reads and edits that are specialised to your file format
• Validate file edits, and run unit tests

The tools take parameters, and are self-describing. The LLM model can figure out, to a good extent, which tools to call, and which parameters to pass - however, that is not sufficient for good agent design, because:

• The same operation may be solved by different tools.
• Or, the tools need to be called in a certain order.

This is why step is crucial: Task Planning, which steers the agent in how it uses the MCP Server tools.

Task Planning

Task planning is designed partly through editing CLAUDE.md, and partly through changing the system prompt.

• With the command-line Claude Code tool, its internal system prompt is not editable.
• But with Claude Agent SDK, it is.

In CLAUDE.md, we specify how to approach the various custom problems the agent might encounter. Claude Code has built-in support for the ToDoWrite tool. In CLAUDE.md, we specify what are the ToDo tasks, for each problem the AI Agent might encounter.

The Claude Code Event Loop

The Claude Code agent itself has a baked-in event loop, which takes user input, file attachments and screenshots - puts CLAUDE.md in context, determines its ToDo tasks, and iterates through MCP Server tools and other built-in tools to solve the task.

The user can interrupt the flow at any moment, and continue it with altered instructions.

From there, the agent marches forward, step by step. It can go solo or pause for human nods, calling on more MCP and built-in tools as needed to create new files, edit existing ones, or query the knowledge base.

Tuning the Agent through Evaluation

Once the infrastructure is stood up, the knowledge base available, the MCP server working, and the agent begins to be integrated in the larger application - you need to tune the agent and adapt it to the task at hand.

Tuning can mean:

• Adding or updating to the knowledge base
• Adding or updating the MCP server tools
• Improving the CLAUDE.md design, to steer the running agent through its __ToDo__s.

Evaluation is an essential step here.

Kick things off by:

• Assembling a ground-truth dataset — a curated set of benchmark problems mirroring real-world scenarios.
• Create an evaluation script that, for each item, spins up a fresh Claude Code instance to tackle the problem in pure automated mode, assuming no user intervention.
• Once the _Claude Code instance completes processing a dataset item, a second forked instance of Claude Code runs to evaluate and judge the output, for a number of metrics, as LLM Judge.

The metrics tracked by the LLM Judge are:

• Accuracy: How spot-on are the results?
• Completeness: Does it cover all requirements without omissions?
• For MCP interfaces leaning on vector DB retrieval: Accuracy and completeness of the chunks pulled back.
• Completion rate of the ToDo’s
• Drilling deeper, for select MCP tools: Per-tool breakdowns of response accuracy and completeness.
• Number of failed validations during the actual run
• Validation tests run by the LLM judge at eval time, using the same MCP validation tools you added
• Other statistics: number of steps to solve the question, LLM models used, in and out tokens, cached tokens, cost

Bringing Eval to Life: Visualization

Raw eval logs are hard to monitor without an at-a-glance view.

In our approach, we build a custom web visualiser of eval results, with:

• A quick-scan table, one row per question, for instant overviews.
• A radar chart aggregating metrics into a visual story of strengths and gaps.
• Distributions to reveal patterns across the board.
• Per-question deep dives on tool usage: At-a-glance summaries of which tools fired, what inputs they took, the outputs they spat, and any ToDo progress where relevant.

Iteration and Improvement

Here’s how the development loop flows in practice:

• Bootstrap your ground-truth dataset with questions to get baseline momentum.
• Start the evaluation suite and scrutinize the metrics
• For each metrics shortfall, triage the root cause:
  • Does the knowledge base require new or updated data?
  • Is the problem caused by Vector DB chunking, indexing, or retrieval?
  • Is an MCP tool not working properly? Or is a new MCP tool needed?
  • Or perhaps CLAUDE.md itself needs a refresh to better guide the agent?

As problems are discovered, and fixed, the ground truth dataset is expanded. Re-running over previously-working dataset items ensures the new fixes don’t break old functionality.

As regulations evolve rapidly — with frameworks like HIPAA, SOC2, FDA approvals, and GDPR becoming more stringent — startups must integrate compliance from the outset to avoid costly pitfalls.

In this blog post, we draw from insights shared at Startup Boston Week 2025’s Engineering with Guardrails panel, featuring Ilsa Webeck (Simbex), Marjan Monfared (Leaf Guardian), and myself (DocRouter.AI), moderated by Rabeeh Majidi (OrthoKinetic Track) - incorporating panel wisdom alongside other general best practices.

Whether you’re a technical founder or CTO, understanding these principles can help you build resilient products that scale without regulatory roadblocks.

How Do Regulatory Frameworks Differ From Each Other?

While all regulatory frameworks aim to promote safety, security, and accountability, it’s vital to understand their key differences, as advice applicable to one may not translate to others.

• HIPAA is a U.S. federal law mandating the protection of protected health information (PHI) through privacy and security rules, including breach notifications, for covered entities like healthcare providers and their business associates.
• FDA regulations for pharmaceuticals focus on ensuring drug safety and efficacy via rigorous processes like New Drug Applications (NDAs), which often involve extensive clinical trials and can take an average of 12 years.
• In contrast, FDA oversight for medical devices is risk-based, with devices classified into Class I (low risk, general controls), Class II (moderate risk, often requiring 510(k) clearance for substantial equivalence to existing devices), and Class III (high risk, needing Premarket Approval with clinical data), typically spanning 3-7 years.
• SOC2, developed by the AICPA, is an attestation framework for service organizations, evaluating controls across trust services criteria (security, availability, etc.) via Type 1 (design) or Type 2 (operational effectiveness) reports, and it’s not industry-specific or legally mandated like HIPAA.
• HITRUST is a voluntary, certifiable framework tailored to healthcare, incorporating HIPAA along with standards like NIST and ISO for comprehensive risk management, going beyond HIPAA’s requirements with prescriptive controls and global applicability.

For example, while FDA emphasizes product testing and recalls, HIPAA prioritizes data handling, and SOC2 focuses on organizational controls—highlighting why strategies must be customized to each framework’s unique scope and enforcement.

Common Compliance Mistakes - And How To Sidestep Them

One of the most frequent errors startups commit is treating compliance as an afterthought, leading to retrofits that drain resources and expose vulnerabilities.

As Ilsa Webeck noted, the biggest pitfall she sees is really around understanding what the compliance landscape is going to look like for your product. Startups often assume their product’s intended use and launch plan align with FDA expectations without researching requirements or establishing a quality management system (QMS). This lack of preparation can lead to costly pivots, as some clients she worked with had to change their product’s market approach after regulatory reviews revealed misaligned pathways.

• In healthcare, overlooking patient privacy under HIPAA can result in breaches from unsecured devices or inadequate employee training—issues like staff snooping on patient records are top violations that have fined organizations millions.
• Fintech startups often fail to address third-party risks in AI integrations, such as unvetted vendors handling sensitive data.
• A critical oversight is disregarding data quality. For multi-stage data processing, this can lead to “Garbage In, Garbage Out”. It can result in flawed fraud detection or biased models that regulators scrutinize.
• A typical mistake, for SOC2, is treating it as a one-time checkbox rather than an ongoing process, often skipping a readiness assessment or gap analysis.
• Broader pitfalls include underestimating documentation for SOC2 audits or assuming global regs like GDPR don’t apply early on.
• Other top reasons for failed audits are due to issues like poor vulnerability management or inconsistent employee onboarding/offboarding.

Non-Compliance Costs Can Be Staggering

HIPAA violations can reach $50,000 per incident, with cumulative fines up to $1.5 million annually; SOC2 lapses contribute to data breaches averaging $4.45 million; and GDPR penalties hit 4% of global revenue, starting at $20,500 for small startups but scaling to millions. Overall, non-compliance is 2.71 times more expensive than proactive programs. To avoid this, conduct an early gap analysis and prioritize compliance by design.

How Do You Balance Moving Fast with Staying Compliant?

Startups thrive on velocity, but rushing without guardrails invites failure. General best practices:

• Adopt a phased compliance approach, like starting with SOC2 Type 1 for quick foundational controls before Type 2.
• Aim for HIPAA-ready cloud services (e.g., AWS with Business Associate Agreements) to prototype compliantly.

“For the early traction, you need to work with the hospitals”, Marjan says. “So how we did that is we make sure all the first prototype equipment that we are providing is off-the-shelf but is HIPAA compliant itself. For example, for data collection, we used a device that was already on the list of HIPAA-compliant units.”

• Use automation tools like Vanta or Drata for cloud compliance monitoring (10-15 similar vendors available). These tools help avoid duplicate effort between HIPAA, SOC2, HITRUST and GDPR, and have relationships with familiar auditors.
• Integrate “shift-left security” into CI/CD pipelines for real-time compliance scans, ensuring innovations roll out without rework.
• Designate a compliance point person to handle audits without halting engineering.

And bring external expertise early on:

“I talk a lot to clinicians and patients about new technology just when they’re even kind of napkin sketches or little graphic representations,” says Ilsa Webek.

“That’s where you get feedback from the potential users about how this is actually going to work in the real world. You can adjust again to understand what could be commercially viable and then reflect back on the regulatory pathway that you need to be successful in moving it down the line. Get many advisors in, and feedback in from all of your main stakeholders. “

Innovating Within Strict Rules: Turning Constraints into Opportunities

While AI offers significant innovation potential in the highly regulated healthcare industry, startups should avoid superficially integrating AI just because it’s trendy.

• Understand the regulatory frameworks first.
• Also, study existing FDA-approved AI applications.
• AI solutions must address genuine unmet needs and be tailored to specific problems, rather than being forced into products without clear purpose.

The AI revolution has dramatically accelerated development. With AI editors like Claude Code and Cursor, projects that used to take three months now take a week or half a week. Code review with AI and enhanced development workflows make innovation much faster for engineers.

“There’s huge wave of innovation coming and I don’t know how it’s going to impact regulations as a framework, but for sure it’s going to be impact it”, says Andrei. “The companies that build software stacks to help with regulatory evaluation already embed AI in the document processing. It’s now simpler to see of whether you’re on track with your compliance.”

“For the DocRouter.AI”, says Andrei, “being a horizontal platform means that you can have customers with different security requirements. Supply Chain requirements are going to be different than for Insurance or Medical or Legal. You can make a lot of progress with customers with lesser requirements. Then, the feature you develop is portable to other domains.”

“It’s a game of figuring out how to work with customers sharing their data, and how to find the right product pilots, so that when you go to a strictly regulated environment with HIPAA data, for example, then you can make quick progress.”

Tips for enabling innovation:

• For HIPAA, use modular architectures where sensitive PHI is isolated in compliant modules, allowing rapid iteration on non-sensitive features.
• Adopt privacy-by-design principles, like anonymizing data for external AI testing, and leverage compliant cloud services (e.g., AWS with BAAs) to experiment securely.
• For SOC2, focus on relevant Trust Services Criteria (e.g., Security and Privacy for data-heavy innovations) to avoid over-scoping.

Recommended Tools:

• Snyk or Dependabot: Scan for vulnerabilities in code dependencies.
• Trivy or Aqua Security: Check container images for misconfigurations.
• AWS Config or Azure Policy: Enforce compliant cloud configurations (e.g., HIPAA-eligible services). Implement infrastructure scanning.
• Write unit tests to confirm API endpoints enforce role-based access control (RBAC).
• Ensure all automated checks generate logs for audit trails (critical for HIPAA and SOC 2).
• Store results in a centralized compliance dashboard (e.g., Vanta) for easy review during audits.

Best Practices for Healthcare Documentation

• Establish Robust Communication with Healthcare Clients
  • Engage Early with Hospitals: Initiate and maintain open, consistent communication with hospital clients to understand their unique, often non-public internal regulations. This is critical during both preclinical and clinical phases to align your product or service with their specific requirements.
  • Engage Hospital Ethical Committees: Prior to formal collaboration, ensure discussions with the hospital’s ethical committee are part of the process. Submitting proposals to these committees is a mandatory step post-contract, as their approval is essential to proceed. Be prepared for potential rejections and plan accordingly.
• Tailor Documentation to Hospital Needs
  • Customize Documentation: Recognize that documentation requirements vary across hospitals. Avoid assumptions about universally accepted formats (e.g., PDFs or specific applications). Actively consult with each hospital to determine their preferred reporting formats and classifications to ensure compliance and usability.
  • Leverage Technology for Compliance: For products like those using thermal temperature mapping to detect early signs of pressure injuries (e.g., ischemia or blood flow disruption), integrate AI-driven, physics-informed solutions to enhance accuracy beyond traditional methods. Ensure all patient data logging includes visual components to meet hospital documentation standards.
• Resource Management for Startups
  • Optimize Limited Resources: As a startup with constrained resources, prioritize partnerships with hospitals where your product or service can be delivered effectively within your capabilities. This strategic focus mitigates risks associated with overextension.
  • Proactive Inquiry: Regularly ask hospitals for feedback on documentation and reporting needs to avoid costly missteps. Tailoring solutions to specific hospital requirements enhances compliance and strengthens client relationships.

Best Practices for Engineering Documentation

• Leverage modern AI tools: Claude Code and Cursor have significantly improved. Use them to streamline the engineering documentation process.
• Prioritize Design Phase: Use these tools to first create BRDs and PRDs, then Architecture and System Docs. Creating unit tests ahead of code implementation allows AI agents to iterate efficiently.

When to Bring in Outside Help (vs. In-House Management)

Bootstrap until you can’t — then scale expertise. Bring in external help for HIPAA when your startup lacks internal expertise. Consultants are ideal for mapping controls. Outsource when scaling rapidly or facing overlapping frameworks (e.g., HIPAA + SOC2).

Keep it in-house for maintenance once policies are set, using a dedicated officer. Engage outsiders early for readiness assessments ($10,000–$15,000 for HIPAA mocks) if pre-seed, but only for audits (mandatory external for SOC2 Type 2). Costs vary: SOC2 full compliance runs $15,000–$50,000 in 2025, HIPAA certification $40,000+ for complex setups. For global operations, hire fractional experts versed in GDPR overlaps to align frameworks efficiently, preventing siloed efforts.

Designing Tech for Evolving Rules

Regulations shift — your stack must adapt. Design tech for evolving regulations by adopting modular, scalable architectures. Build with compliant platforms (e.g., HIPAA-eligible AWS services). For SOC2, focus on flexible controls and ‘shift-left’ integration: embed compliance checks in DevOps pipelines.

Use AWS Bedrock for compliant LLMs and conduct quarterly control mappings. In 2025, anticipate AI ethics updates—implement audit trails for traceability. Multi-framework tools like Drata unify HIPAA, SOC2, and GDPR monitoring, reducing adaptation costs. Regular third-party pentests keep you ahead of cyber evolutions.

Talking Risk and Compliance with Investors: Building Credibility

Investors probe compliance to gauge risks — be ready. Focus on understanding the highest risk areas and putting the best plan in place. Show progress as you fill in knowledge gaps. Always include a slide about your compliance with crystal clear understanding and explanation based on all the regulations why you fall into this category and the ROI.

Quantify costs (e.g., validation budgets) and mitigations. Pitch to sector-savvy VCs to skip basics. Highlight how compliance enables expansion—e.g., SOC2 certification boosts trust, closing deals 2x faster.

One Tip for Your First Regulatory Submission

Facing FDA or HIPAA? Start informed. For complicated problems—look aside and see how others do it. Research vendor SOC2 selection guidance available through industry resources. Understand your pathway and have a clear description of your intent of use.

Know your FDA class early via 513(g) requests; document thoroughly (treat it as strategic communication); collaborate via Pre-Sub meetings. For HIPAA, assess applicability first—many apps aren’t covered. Aim narrow for initial submissions to iterate later, avoiding common failures like incomplete indications.

Why Compliance Pays Off: The Bigger Picture

Non-compliance isn’t just risky—it’s ruinous, with breaches costing tens and hundreds of thousands of dollars for unprepared firms. Yet, proactive startups see ROI: Faster market entry, investor confidence, and scalable innovation. As regs like AI guidelines tighten, embed compliance now. Resources like FDA’s “breakthrough” designated programs lower barriers. For more, revisit the panel recording or consult experts—your guardrails today fuel tomorrow’s breakthroughs.

Insights blend panel discussions from September 9, 2025, with industry best practices. Always seek tailored legal advice.

📢 Join the Analytiq Pages discussion on LinkedIn

Why Analytiq Pages?

After building numerous company websites and helping startups establish their web presence, we’ve distilled the best practices into a reproducible system that delivers:

• Zero hosting costs with GitHub Pages
• Professional design with Tailwind CSS
• Easy content creation using Markdown
• Git sandbox edited with Claude Code, Cursor to create content and visualizations
• Fast deployment with git-based workflows
• Enterprise reliability backed by GitHub’s infrastructure

The Analytiq Pages Stack

Setting Up Your Company Website

The fastest way to get started is by using our reference implementation at analytiqhub.com as your starting point. This site demonstrates all the Analytiq Pages features in action and serves as a complete template for your company website. You’ll clone this proven foundation and customize it with your branding, content, and specific requirements.

Let’s walk through creating a professional company website using the Analytiq Pages approach.

Step 1: Repository Setup

Start by forking the Analytiq Pages reference implementation:

1. Fork the repository: Go to https://github.com/analytiq-hub/analytiq-hub.github.io and click “Fork”
2. Rename your fork: In your forked repository settings, rename it to your-company.github.io
3. Clone for local development:

# Clone your forked repository
git clone https://github.com/your-company/your-company.github.io.git
cd your-company.github.io

Step 2: Customize for Your Company

Replace all Analytiq Hub references with your company information:

Key files to update:

1. _config.yml - Site configuration:

   title: Your Company Name
   email: contact@yourcompany.com
   description: Your company description
   baseurl: ""
   url: "http://your-company.github.io"
   github_username: yourcompany
   

2. index.md - Homepage content
3. about.md - Company information
4. _posts/ - Replace sample blog posts with your content
5. assets/images/ - Replace logos and images
6. CNAME - Update with your custom domain (if using one)

GitHub Pages setup:

• Go to your repository Settings → Pages
• Set source to “Deploy from a branch” → main
• Add custom domain if you have one

The forked template already includes Tailwind CSS configuration, so your site is ready to run locally with make dev or deploy immediately to GitHub Pages.

Step 3: Local Development Setup

Install local development prerequisites and start developing locally:

# Install dependencies
make install

# Start development server
make dev

For complete setup instructions including Ruby, Bundler, and troubleshooting, see the full Local Development Setup guide.

Point your web browser to the local development server at http://localhost:4000.

After editing files in the sandbox, manually or with Claude Code, Cursor or the preferred AI editor, they are automatically refreshed on the development server.

• Changes to the menu or the footing require a restart of the local development server.
• When later the github pages pipeline is setup, a push of local changes will trigger the web site update at https://your-company.github.io

Step 4: Essential Company Pages

Update the core pages with your company information:

• index.md - Homepage with compelling hero section and company value proposition
• about.md - Company story, team information, and mission
• contact.md - Contact information and inquiry forms

Step 5: Header and Footer Customization

Start by configuring your site navigation in _config.yml:

# Header navigation menu
header_pages:
  - title: "Services"
    url: "#"
    children:
      - title: "Consulting"
        url: "/consulting"
      - title: "Development"
        url: "/development"
  - title: "Case Studies"
    url: "/case-studies"
  - title: "Blog"
    url: "/blog"
  - title: "About"
    url: "/about"
  - title: "Contact"
    url: "/contact"
    button_style: "solid"

# Footer sitemap
site_map:
  - title: "Services"
    links:
      - title: "Consulting"
        url: "/consulting"
      - title: "Case Studies"
        url: "/case-studies"
  - title: "Company"
    links:
      - title: "About"
        url: "/about"
      - title: "Contact"
        url: "/contact"

Then customize the visual elements:

• _includes/custom-header.html - Company logo, announcements, search
• _includes/custom-footer.html - Contact info, social links, legal pages

Step 6: Blog Setup

Jekyll’s blog functionality is ready out of the box:

• Create posts in _posts/ using the format: YYYY-MM-DD-post-title.md
• Posts automatically appear on your homepage and /blog page
• Use front matter to set title, author, categories, and featured images

Step 7: Case Studies

Showcase your work with detailed case studies:

• Add case studies to the _case_studies/ collection
• Use the case study template for consistent formatting
• Include client results, project images, and key outcomes

Step 8: (Advanced) Custom Components

The template includes Tailwind-powered components for:

• Call-to-action sections
• Team member profiles
• Service feature cards
• Client testimonials

Your AI editor can help create custom components by combining Jekyll’s liquid templating with Tailwind’s utility classes.

Step 9: (Advanced) Custom Layouts

Create specialized page layouts by extending the base templates:

• _layouts/landing.html - For marketing campaigns and product launches
• _layouts/portfolio.html - Showcase projects with image galleries
• _layouts/team.html - Team member profiles with bios and photos

Copy existing layouts as starting points and modify with your specific content structure and Tailwind styling.

Deployment and Domain Setup

GitHub Pages Configuration

1. Enable GitHub Pages in repository settings
2. Set source to “Deploy from a branch” → main
3. Custom domain: Add your company domain in settings

Domain Configuration

DNS Setup:

# For apex domain (company.com)
A record: 185.199.108.153
A record: 185.199.109.153
A record: 185.199.110.153
A record: 185.199.111.153

# For www subdomain
CNAME record: your-company.github.io

CNAME File:

echo "your-company.com" > CNAME

Analytiq Pages Best Practices

Content Strategy

• Homepage: Clear value proposition and call-to-action
• About: Company story and team credibility
• Services/Products: Detailed offering descriptions
• Blog: Regular insights to build authority
• Contact: Multiple ways to reach you

SEO Foundation

• Meta descriptions: Add to each page’s front matter
• Google Analytics: Add tracking code to _includes/custom-head.html

Maintenance and Updates

The beauty of Analytiq Pages is its simplicity:

# Update content
git add .
git commit -m "Update company blog post"
git push origin main
# Site updates automatically within minutes

Why Companies Choose Analytiq Pages

• Startups: Get online fast without burning budget on hosting or developers
• Agencies: Deliver professional sites quickly for clients
• Enterprise: Maintain security and compliance with git-based workflows
• Content Teams: Edit in Markdown without technical dependencies

Conclusion

Analytiq Pages combines the best of modern web development - GitHub’s reliability, Markdown simplicity, and Tailwind’s design power - into a streamlined system perfect for company websites. Whether you’re launching a startup or refreshing an enterprise web presence, this approach delivers professional results without the complexity.

Ready to build your company website? Check out our Analytiq Pages starter template or contact us for custom implementation support.

Want to see Analytiq Pages in action? This very website was built using these exact techniques. View the source code to see how we implement our own recommendations.

The Challenge with Minima

For years, I’ve been running my personal knowledge repository on Jekyll with the default Minima theme. While Minima served its purpose, it had several limitations. The look and feel was outdated, and layouts were especially rigid.

Enter Tailwind CSS

Tailwind CSS has become the go-to utility-first CSS framework for modern web development, and for good reason:

• It is much simpler than CSS
• It is responsove out of the box, built with mobile-first principles
• AI editors like Claude Code and Cursor are very fluent with Tailwind.

The Migration Process

What surprised me most was how seamless the migration turned out to be.

Development Environment Setup

The migration was performed on Fedora Linux using a simple but effective workflow:

1. Repository Setup: Checked out the Git repository from the command line:

   git clone https://github.com/bitdribble/bitdribble.github.io.git
   cd bitdribble.github.io
   

2. IDE Integration: Loaded the project in Cursor (this works equally well in VSCode):

3. Claude Code Extension: Enabled the Claude Code add-in, which, like Cursor, provides:
   • Intelligent code suggestions and refactoring
   • Context-aware assistance with Jekyll and Tailwind
   • Seamless understanding of project structure and dependencies

How Claude Code Transformed the Migration

The AI assistant proved exceptionally capable at understanding both Jekyll’s architecture and Tailwind’s utility-first approach. Here’s what made it work so well:

1. Jekyll’s Markdown Flexibility

Almost all Jekyll pages can be written in pure Markdown. Take a look at my markdown example page - it’s a full demonstration of how Jekyll processes Markdown content beautifully, even with the new Tailwind styling.

• Content creators don’t need to know HTML or CSS
• Blog posts remain simple and focused on content

2. Inline HTML When Needed

When you need more sophisticated layouts or Tailwind-specific components, Jekyll’s Markdown processor allows you to embed HTML+Tailwind directly in your Markdown files. For example, I was able to create a sophisticated three-column layout for my about page by simply adding:

<div class="bg-white rounded-lg shadow-lg p-8">
  <div class="grid md:grid-cols-3 gap-8 items-start">
    <!-- Column content here -->
  </div>
</div>

Live Example: Here’s that same three-column layout in action with actual content:

This flexibility gives you the best of both worlds - simple content editing in Markdown, with the power to create complex layouts when needed.

3. Enhanced Features with Jekyll

The Jekyll + Tailwind combination also preserves and enhances Jekyll’s powerful features. Take a look at the markdown example page which demonstrates:

Code Syntax Highlighting: Jekyll automatically highlights code blocks with proper syntax coloring for multiple languages:

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

MathJax Integration: Mathematical formulas can be enabled by adding mathjax: true to the page front matter:

---
layout: page
title: Your Page Title
mathjax: true
---

Then you can write beautiful mathematical expressions:

• Inline math: $E = mc^2$
• Display equations: \(\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}\)

Page Headers: Jekyll’s front matter system makes it easy to configure pages with metadata, layout selection, and feature toggles like MathJax - all while maintaining the flexibility to use Tailwind styling throughout the content.

The Payoff

The transformation has been dramatic. Here’s a side-by-side comparison of the old Minima theme versus the new Tailwind-powered design:

Before: Jekyll Minima Theme

The original site using Jekyll's Minima theme with dark styling

After: Tailwind CSS Design

The modern site with Tailwind CSS featuring improved navigation and visual hierarchy

The site now boasts:

• Modern visuals: Professional and polished
• Performance: Purged CSS for leaner loads
• Flexibility: I can create any layout I can imagine without fighting the framework

Why Jekyll + Tailwind Rocks

• Content Teams: Edit in Markdown, no CSS needed.
• Developers: Modern tooling, reusable components
• Businesses: Fast, SEO-friendly, low-cost hosting (GitHub Pages, Netlify)

Technical Implementation

The migration involved several key technical steps that Claude Code helped orchestrate seamlessly:

1. Tailwind CSS Integration

Adding the Tailwind CLI:

# Downloaded the standalone Tailwind CLI binary
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64
chmod +x tailwindcss-linux-x64
mv tailwindcss-linux-x64 tailwindcss

Created Tailwind Configuration:

// tailwind.config.js
module.exports = {
  content: [
    './_includes/**/*.html',
    './_layouts/**/*.html', 
    './_posts/**/*.md',
    './*.html',
    './*.md',
    './**/*.md'
  ],
  theme: {
    extend: {
      // Custom colors and styling
    },
  },
  plugins: [],
}

Build Process Integration: Created a Makefile to streamline development with proper process management: make dev starts the web server locally, and Ctrl-C stops it:

# Development with live reload and signal handling
dev:
	@echo "Starting development environment..."
	@trap 'echo "Stopping all processes..."; kill 0' INT; \
	./tailwindcss -o assets/css/tailwind.css --watch & \
	TAILWIND_PID=$$!; \
	bundle exec jekyll serve & \
	JEKYLL_PID=$$!; \
	echo "Development server running. Press Ctrl+C to stop both processes."; \
	wait

# Production build
build:
	./tailwindcss -o assets/css/tailwind.css --minify
	bundle exec jekyll build

2. Replacing the Minima Theme

Removed Theme Dependency:

# _config.yml - Commented out the minima theme
# theme: minima  # Removed - using Tailwind CSS instead

Layout System Redesign:

• _layouts/default.html: Created a new base layout with Tailwind styling
• _layouts/home.html: Redesigned blog listing with card-based design
• _layouts/page.html: Clean page layout with proper typography
• _layouts/post.html: Enhanced blog post layout with better readability

3. Component Migration Strategy

Navigation System: Replaced Minima’s navigation with a modern Tailwind-based header featuring:

• Responsive dropdown menus
• Clean typography and spacing

4. Content Preservation

Front Matter Compatibility: All existing blog posts and pages continued to work without modification. Jekyll’s front matter system remained unchanged:

---
layout: post
title: "My Blog Post"
date: 2025-01-20
categories: [webdev, jekyll]
---

Conclusion

Jekyll + Tailwind is a powerhouse for blogs and company sites, blending content simplicity with design flexibility. Claude Code nailed the migration, delivering a stunning result with minimal effort. Check the source code or live site to see it in action!

DocRouter.AI User Experience

We’re developing DocRouter.AI as open source because experience shows it leads to better-designed, more resilient code over time. Business value comes from our SaaS version at app.docrouter.ai and enterprise on-VPC installations. We also offer consulting to help other companies build software using similar styles and tools.

GitHub Repository: github.com/analytiq-hub/doc-router

A revolution is underway in software development with tools like Cursor and Claude Code. I’ll dive into how we built DocRouter.AI, sharing lessons that could apply to your projects. (I’ve detailed my tool usage in a previous LinkedIn post, so I won’t repeat it here.)

My Background: From Embedded Systems to AI-Driven Front Ends

I come from a world of cloud, back-end, and embedded work, starting long ago with Linux kernel programming, computer networks, then high performance computing for Wall St, followed by robotics/ROS/computer vision.

In short, my expertise is embedded back-end, and data science. When starting DocRouter.AI, I had zero hands-on experience with front-end development— no JavaScript, TypeScript, or React.

But tools like GitHub Copilot (which helped me learn Apache Spark and Terraform from scratch in prior roles) paved the way.

By fall of last year, Cursor enabled me to build DocRouter.AI with a Next.js front end, FastAPI back end, and AWS via Terraform. Claude Code exploded about a month ago, and I’ve began using it intensively.

Lessons from AI Coding Tools: What Works and What Doesn’t

We often hear engineers claiming they can “zero-shot vibe code” entire apps from scratch. That’s possible for simple, UI-focused apps, but for anything complex, the human engineer must stay in the loop. Knowing when to let AI take over and when to intervene is becoming a black art.

For DocRouter.AI, we use FastAPI on the back end, with all functions in a single file (main.py) to simplify AI editing—easier for pattern searching and consistency. If designing for humans, I’d split it into 8-10 files. But, for AI editors, a single large file simplifies things.

AI agents have “personalities.” Claude Code Agent outperforms Cursor Agent right now. I use Cursor in manual mode, attaching specific files. Keeping FastAPI in one file reduces attachment hassle.

AI editors love “improving” code inconsistently. Most of main.py, our FastAPI interface, was built with Cursor. But for web form support (more on why below), I tasked Claude Code with creating similar FastAPI endpoints (create, list, get, update, delete) to our existing schema ones.

Claude did great but switched to identifying things with UUIDs instead of our MongoDB _id scheme. I almost did not notice it. I caught it by asking Claude Code to explain in practice how the new APIs are used.

Why Schemas, Web Forms, and MongoDB?

I’m a fan of the simplest tool for the job. DocRouter.AI stores documents, LLM prompts, and extraction schemas—MongoDB collections are ideal. Mongo handles blobs via GridFS, avoiding external storage like S3 (which Postgres would require).

Schemas: LLMs can output free-form or structured JSON. Providers support JSON schemas for precise LLM output. For docs, we classify types (e.g., via LLM prompt) then extract a specific schema—like date, patient name, DOB, address, diagnostics, doctor details in a medical prescription.

DocRouter.AI lets users configure extraction schemas for all doc types.

Web Forms: Schemas are too abstract for end users accustomed to ERPs (e.g., Epic for EHR, Salesforce for CRM). End users are instead familiar with entering data into web forms tailored to their process.

We had to add web form support to DocRouter.AI: LLM extractions map to pre-populated form fields. LLM-as-judge scores confidence, so users focus on low-confidence fields—cutting effort by up to 90%.

To stay horizontal (not vertical-specific), we avoid hard-coding web forms. Instead, we integrate a schema builder, and a web form builder.

The web form builder was pretty complicated.

But the schema builder was vibe-coded in Cursor (manual mode, incremental development: first do the FastAPI back end, then the Axios APIs, then the UI components, and the unit testers). It worked out of the box!

For comparison, Base44 solo entrepreneur Maor Shlomo (podcast interview) uses MongoDB too, seeing it as AI-era friendly over SQL. He uses plain React and JavaScript; I use Next.js and TypeScript. His simpler stack might ease things—worth pondering.

Note that Next.js has server-side capabilities, but we use FastAPI for most back-end functions.

DocRouter.AI Document Processing

The Need for Human-in-the-Loop

LLMs are precise with context, but humans must correct rare errors.

The goal is to make human reviews simple - and focus them on likely mistakes.

Ease of adoption is also key. We must adapt to existing workflows, — and plug DocRouter gradually in the customer process.

Our multi-vertical approach gets many more use cases compared to a vertical approach - but demands flexibility and portable software design.

How DocRouter.AI Works

Here is an example DocRouter.AI use from one of our pilots with an insurance company:

We process Acord forms for personal/commercial insurance: We extract insured name/address, insurance type, and can extract coverage limits, loss runs, etc.

• Files arrive as email attachments; tools like n8n upload via REST APIs to DocRouter workspace.
• We configure the extraction formats (e.g., insured details) and prompts (descriptions, examples, counter-examples).
• These are stored as JSON schemas
• We upload representative datasets of documents, and iterate schema & prompt design, as well as vendor-agnostic LLM choice, for best accuracy/cost.
• We monitor accuracy, and tweak prompts (add examples/counter-examples) for edge cases.

Extracted data can be corrected by the human-in-the-loop, and is available via REST APIs for ERP upload (e.g., TMS for insurance, Epic for hospitals).

The User Perspective: Streamlining Reviews

Before DocRouter, users had to manually enter PDF data into ERP web/UI forms—a laborious process!

DocRouter pre-fills 90%+ fields with LLM extractions and, when configured, with confidence scores from LLM-as-Judge. Users then focus on low-confidence fields, ensuring perfect accuracy with minimal effort.

The human-in-the-loop is critical in regulated fields (healthcare, insurance, fintech, supply chain, legal) where errors in amounts, inventories, or obligations are unacceptable.

Achieving Accuracy and Flexibility

But direct LLM review is impractical. Users prefer familiar web forms.

We are designing the system so project managers can configure tailored web forms linked to extractions and confidences. For each doc, users review pre-populated forms flagged by confidence metrics.

Implementing the Web Form Builder: CSS Adventures

Vibe coding couldn’t handle this yet—AI tools aren’t ready for complex builders.

FormIO Builder in DocRouter.AI

We integrated FormIO (nice UI npm package). But issues arose:

• FormIO elements didn’t display right. Cursor/Claude couldn’t fix immediately.
• Root cause: FormIO uses Bootstrap; DocRouter uses Tailwind. Global CSS conflicts.

Added @tsed/react-formio (React support) and @tsed/tailwind-formio (Bootstrap-Tailwind fix). Forms showed, but Tailwind broke—AI couldn’t diagnose.

Expert friends suggested including FormIO components through iframes or a shadow DOM.

• Shadow DOM: Claude iterated but drag-and-drop failed across the boundary with the thin DOM (FormIO incompatibility).
• iframes: Overkill with API messaging for config/state.

Stuck, I fiddled with CSS via browser inspector. Solution: Redefine Tailwind breakpoints last in global.css order:

// FormIO + Bootstrap
@import 'formiojs/dist/formio.full.min.css';

// Tailwind
@tailwind base; 
@tailwind components;
@tailwind utilities;

// Correction so Bootstrap works in FormIO
@import "~@tsed/tailwind-formio/styles/index.css"; 

// Correction to correction 
// so Tailwind responsiveness works
@import './formio-custom.css'; 

Key Takeaway: AI Tools Are Game-Changers, But Humans Are Essential

The programmer must guide AI—tools are amazing, but tough problems (like CSS conflicts) need human expertise. We’re not fully autonomous coding yet, especially for intricate integrations.

If you’re building AI-accelerated tools or facing similar challenges, let’s connect! What are your experiences with Cursor, Claude Code, or CSS headaches? Share in the comments.