Architecture

Small businesses asking "what does a modern AI-ready website actually look like under the hood" deserve a real answer, not a list of buzzwords. This piece is the architecture guide we use when we build Velocity X sites for clients in 2026 — the stack, the conventions, the integrations, and the reasons behind each choice. It's opinionated because opinions are what produce sites that ship.

The Canonical Stack

One sentence: Astro 5 + React 19 + Tailwind 3 + Supabase + Netlify. Each piece is mature, each piece is well-known by AI assistants, each piece has been in production at scale for over two years.

The breakdown:

Astro 5 is the framework. Astro compiles to static HTML by default — fast to load, free to host on CDN edge. When a page needs interactivity, you mark a component as a client island and that component (and only that component) becomes a JavaScript bundle. The rest of the page stays static. The result is a site with the SEO and speed of a static site and the interactivity of a SPA, without choosing between them.

React 19 handles the interactive bits — the data dashboards, the form-with-state, the modal-with-keyboard-trap. Inside an Astro project, React components run as islands. They get hydrated when they need to. They don't slow down the rest of the page.

Tailwind CSS 3 for styling. Utility-first, no CSS files to manage, plays well with AI (AI assistants are very fluent in Tailwind class names). The minor downside of Tailwind 3 vs 4 is the lack of @theme at-rules; we work around it with custom CSS classes for the type scale.

Supabase for the database, auth, file storage, and edge functions. Postgres-based, row-level security (RLS) for access control, generated TypeScript types, real-time subscriptions, and an excellent JavaScript client. For a small business website with a CRM or dashboard component, Supabase is the right call — you get a fully managed Postgres with no DevOps cost.

Netlify for hosting, build pipeline, branch previews, edge functions, and the free SSL. Connects to your GitHub repo directly. Every push deploys. Every PR gets a preview URL. Rollbacks are one click. No DevOps team required.

Optional additions: Stripe (payments), Resend (transactional email), and Anthropic API (for the AI features baked into the dashboard).

The Three-File Foundation

Every AI-ready website has three files at the project root that act as the foundation for everything else. Get these right and the rest writes itself.

brand.json — the canonical brand-context file (covered in detail in our brand.json piece). Every component, every page, every AI conversation reads from this single source of truth.

CLAUDE.md — the AI assistant briefing document. Tells Claude what the project is, what the conventions are, what to avoid, and where to find brand context. Without this, AI sessions start cold every time; with it, they show up already oriented.

README.md — the human briefing document. Same role but for new developers joining the project. Often has significant overlap with CLAUDE.md but kept separate because they evolve at different speeds and serve different audiences.

JSON-Driven Page Templates

The architectural pattern that makes the whole AI workflow work: pages on the site are templates, content is JSON.

Concretely: instead of writing a new Astro file for every service page, you write one [category].astro template that consumes a JSON definition. The JSON for the "Web Design" page might look like:

{`{
  "slug": "web-design",
  "title": "Custom Web Design — Built for Conversion",
  "hero": {
    "headline": "Websites your customers actually use.",
    "subhead": "Bespoke layouts, Core Web Vitals 100/100, your repo.",
    "cta": "/get-started"
  },
  "features": [
    { "title": "Custom layouts", "description": "..." },
    { "title": "Performance first", "description": "..." },
    { "title": "Brand systems", "description": "..." }
  ],
  "testimonials": ["alice-quote", "bob-quote"],
  "pricingHighlight": "small"
}`}

The template reads this JSON, renders the hero, renders the features, pulls in the named testimonials from a shared testimonials file, and highlights the linked pricing tier from brand.json. Adding a new service page is a new JSON file. Done.

This pattern unlocks AI workflows. Telling Claude "add a service page for commercial cleaning" produces a working page in one PR because Claude just writes a new JSON file matching the schema. The template is fixed and tested. Nothing breaks elsewhere. The blast radius of every edit is contained.

The Admin Dashboard Layer

Most small business websites stop at marketing pages and a contact form. AI-ready sites add an admin dashboard that integrates with the business's existing tools. Two views, role-gated:

Ops view — for staff and reps. CRM map, route optimisation, calendar sync, AI follow-up drafts, lead pipeline. The thing the people doing the work actually use.

SLT view — for management. Multi-channel traffic rollup (GSC + GA + Meta), conversion funnel, campaign performance, revenue, jobs. The thing the people running the business actually use.

Both views share the same Supabase backend, gated by row-level security so each user sees only what their role allows. OAuth-pre-wired integrations pull data from Google Calendar, Microsoft 365, HubSpot, Pipedrive, Attio, Meta Ads, Google Ads, LinkedIn Ads, and Google Search Console.

This is the part of the architecture that pushes a "website" into "business operating system" territory. For service businesses, this layer pays back the cost of the whole project within the first six months.

OAuth Integrations: The Pre-Wired Set

Building a OAuth integration from scratch is a non-trivial engineering exercise — token storage, refresh logic, encryption at rest, scopes, callback URLs, error states. Doing it well takes a senior engineer a day or two per provider. Doing it wrong leaks tokens.

An AI-ready website built on this stack ships with the OAuth integrations pre-wired so the small business doesn't have to engineer any of this. The Velocity X package includes:

• Google (Calendar, Search Console, Analytics 4, Ads)
• Microsoft 365 (Calendar, Mail, Teams)
• Meta (Ads, Pages, Instagram)
• LinkedIn (Ads, Company Page)
• HubSpot, Pipedrive, Attio (CRMs)
• Stripe (payments)
• Resend (email)

Each integration uses AES-256-GCM token encryption, RLS-gated token storage, and a refresh-on-401 retry pattern. None of this needs to be re-invented per project; it ships in the template and just works.

The Type Scale

A surprisingly underrated piece of AI-ready architecture: a fluid type scale defined once in CSS. The Velocity X type scale uses CSS clamp() so headers scale smoothly from 360px phone to 1920px desktop with no breakpoint jumps:

{`.h-hero    { font-size: clamp(2.5rem, 7vw + 1rem, 7.5rem); }
.h-section { font-size: clamp(2rem,   4vw + 1rem, 5rem); }
.h-sub     { font-size: clamp(1.5rem, 1.2vw + 1.15rem, 2.5rem); }
.h-eyebrow { font-size: clamp(0.7rem, 0.5vw + 0.6rem, 0.8125rem); }`}

One source of truth. AI assistants asked to add a new section heading apply .h-section and don't need to remember 5-stop responsive variants. Re-tune the whole site's typography by changing four lines of CSS.

Performance Targets

A 2026-grade business website should hit these numbers on a real production deployment:

• Lighthouse Performance: 95+ on mobile, 100 on desktop
• Largest Contentful Paint: under 1.5s on 4G
• Cumulative Layout Shift: 0.0 (Astro static-first makes this easy)
• Total Blocking Time: under 50ms
• Initial JS bundle: under 30KB (Astro islands + selective hydration)

These aren't aspirational; they're table stakes for a custom site in 2026. Hit them and Google rewards you with better rankings. Miss them and you're competing for SEO with one hand tied.

SEO Architecture

The AI-ready website includes structured data, sitemap generation, OpenGraph tags, and JSON-LD by default. brand.json feeds all of it. A schema.org ProfessionalService object is generated from brand.json on every page. An OpenGraph card is rendered with the right image and tagline. The sitemap auto-includes every page generated from every JSON file.

For LLM SEO (answer-engine optimisation) — which is its own emerging discipline in 2026 — the site uses semantic HTML, clear H2/H3 hierarchy, FAQ schema for question-style blog posts, and avoids JavaScript-rendered content for primary copy. AI crawlers can read the content without executing JavaScript, which most non-Google crawlers either don't do or do badly.

Security & Auth

Supabase Auth handles user accounts on the dashboard side. Row-level security policies gate which user sees which data. Email/password, Google OAuth, and magic-link auth are all supported out of the box. Sessions are JWT-based, stored in a secure HTTPOnly cookie when used from the web, or a token from the Supabase JS client when used from a React island.

Service-level secrets (Stripe, Resend, OpenAI/Anthropic, OAuth client secrets) live in Netlify environment variables. They never touch the repo. Token refresh logic for OAuth integrations is encapsulated in Netlify Functions so the front-end never sees a refresh token.

Frequently Asked Questions

Why Astro instead of Next.js?

For content-driven business websites, Astro's static-first model is faster, cheaper to host, and easier to reason about. Next.js is the better choice when the site is mostly an application (SaaS dashboard, real-time tool). Velocity X uses Astro for the marketing site and would use Next.js if it were a different kind of product.

Why Supabase instead of Firebase?

Supabase is Postgres under the hood. Postgres is the most well-known database in the AI training corpus, which means Claude and Cursor write better SQL for Postgres than they do for Firestore. Postgres queries are also more powerful and more portable. Firebase still wins on real-time mobile, but for a business website with a dashboard, Supabase is the right call.

Why Tailwind 3 not Tailwind 4?

Velocity X predates the Tailwind 4 upgrade and the migration cost (different theming model, different config) wasn't worth it for this generation. New Aidxn projects use Tailwind 4. Both versions are well-supported by AI assistants. Whichever you choose, stick with it across the whole project.

Why not use a headless CMS like Contentful or Sanity?

JSON files at the project root work better for small business websites because they're versioned with the code, AI-readable, and require no extra service to maintain. Headless CMS makes sense for large content teams with dozens of editors. For a small business with one or two people updating the site, the CMS overhead exceeds the benefit.

What does this cost to host?

Netlify free tier covers most small business sites (100GB bandwidth/month, generous build minutes). Supabase free tier covers small databases (500MB Postgres, 2GB storage, 50k monthly active users on auth). Real-world cost for a typical small business: $0/month for the first year, possibly $25-$45/month as you scale into Supabase Pro and Netlify Pro. Cheaper than any SaaS website builder over a multi-year horizon.

How do I add a new feature later?

If it's a content page: write a JSON file. If it's a new component: write one Astro or React component and reference it. If it's a new dashboard view: write the SQL, the policies, and the component. Claude Code can scaffold any of these in plain English. The architecture is designed to make extension cheap.

The Bottom Line

The AI-ready website architecture for small business in 2026 is opinionated, simple, and ship-fast. Astro + React + Tailwind + Supabase + Netlify, with brand.json, CLAUDE.md, and a JSON-driven page templating system. Everything else flows from those choices. Build on this stack and you can iterate with Claude Code in real time, scale to mid-size without re-platforming, and pay essentially nothing for hosting until you're well past where small business ends and growth-stage begins.