Overview
Waldium is a SaaS platform for creating and managing AI-optimized blogs. The codebase is a pnpm + Turbo monorepo with multiple applications and shared packages, designed for multi-tenancy, programmatic deployment, and AI-driven content.
Monorepo Structure
The repo is organized into:
- Applications:
app(main dashboard),cms(Payload CMS admin),landing,sites(tenant blogs),docs,wiki - Packages: Shared libraries under
packages/*(db, cms client, posts/AI, storage, webhooks, etc.) - Agents: Scripts and agent definitions (e.g.
blog-agent) that use the@waldium/sandboxpackage for snapshot-based sandboxes
Turbo handles task pipelines: build depends on ^build, dev on ^generate:prisma, and the app build also depends on generate:openapi for the public API spec.
Main Application (app)
The primary product is a Next.js 15 (App Router) app that provides:
- Auth: Clerk for organizations and users
- Data: PostgreSQL (Neon) via Prisma in
@waldium/db - Storage: AWS S3 for content and assets
- Editor: TipTap for rich content; posts store both editor JSON and metadata
- API: REST v1 under
/api/(external)/v1/with API key auth, plus internal and admin routes - Billing: Stripe; subscription and usage tracked per site
- Deployment: Vercel with programmatic deployment for tenant sites
Route groups include (admin), (app) (dashboard), (auth), (docs), and API segments. Services such as PostService, StorageService, AIService, WebhookService, and DomainService encapsulate business logic.
CMS (Payload)
The cms app is a Payload CMS instance with:
- Database: PostgreSQL via
@payloadcms/db-postgres - Storage: S3 for media
- Multi-tenancy:
@payloadcms/plugin-multi-tenant - Collections: Users, Tenants, Media, Posts, Authors
It serves as the content backend and admin UI, with type generation into payload-types.ts. The @waldium/cms package provides a typed client and helpers for authors, posts, content, media, and tenant context.
Sites (Multi-Tenant Blogs)
The sites app is a Next.js 15 multi-tenant front-end for published blogs:
- Subdomain routing (e.g.
tenant.waldium.app) via middleware - Upstash Redis (KV) for tenant/data lookups
- Tailwind 4 and shadcn/ui; compatible with Vercel previews and custom domains
Tenant content is isolated per site; the main app and CMS manage the data that sites consume.
Shared Packages
Key packages:
- @waldium/db: Prisma schema and client (Site, Post, Author, Knowledge, ApiKey, and other core entities)
- @waldium/cms: Payload client, generated types, and helpers for posts, authors, media, tenant
- @waldium/posts: AI pipeline via Vercel AI SDK;
AIServiceruns operations (blog-post, site-crawl, site-description, topic-generation, diagram-generation, etc.) with structured schemas and prompts - @waldium/sandbox: Sandbox and snapshot management for agents (e.g. fast-boot from snapshots)
- Others:
api-keys,authors,storage,webhooks,vector-store,knowledge,traffic-metrics,content-metrics,email,firecrawl,domains,tasks,utils,kv,admin,sites-service
The app uses these for a single source of truth (DB, CMS, AI, storage) and consistent behavior across dashboard, API, and jobs.
AI and Agents
AI content is centralized in @waldium/posts: operations define input/output schemas and prompts, and AIService uses the Vercel AI SDK (OpenAI) for structured generation. Knowledge base and vector store packages support RAG and context for generation.
The agents directory contains the blog-agent and scripts (setup-agent, refresh-snapshots, upload-to-db) to build and maintain sandbox snapshots. Sandboxes boot from snapshots for fast, reproducible agent runs (e.g. in cron or queue jobs).
Data and Deployment Flow
Sites and orgs are modeled in Prisma (e.g. Site with clerkOrgId, stripe fields, and relations to Post, Author, Knowledge, ApiKey). The main app and API create/update posts and authors; the CMS can manage the same content for editors. Tenant sites are deployed per site/custom domain (e.g. Vercel), and the sites app serves them with subdomain or domain-based routing and Redis-backed tenant config.
Summary
Waldium’s architecture combines a Turbo monorepo, Next.js 15 apps (dashboard, CMS, tenant sites, docs/wiki), shared Prisma and Payload packages, and an AI/agent layer with sandbox snapshots. Multi-tenancy is enforced at the data layer (site-scoped collections and DB models) and at the edge (sites app + KV), with a single external API (v1) and unified AI pipeline for content generation.
