revealui-architecture-guide

title	RevealUI Architecture Guide
visibility	internal
status	verified
audience	agent
name	revealui-architecture-guide
description	RevealUI monorepo architecture and package organization guide
version	0.1.0
author	RevealUI Team
tags	["architecture","monorepo","packages"]
compatibility	["claude-code","universal"]
allowedTools	["Read","Glob","Grep"]

RevealUI Architecture Guide

Understanding RevealUI's monorepo structure and architectural decisions.

Monorepo Structure

RevealUI uses pnpm workspaces for monorepo management with Turborepo for build orchestration.

RevealUI/
├── apps/                    # Applications (4)
│   ├── server/             # REST API (Hono, port 3004)
│   ├── admin/              # Admin dashboard (Next.js 16, port 4000)
│   ├── docs/               # Documentation site (Vite/React)
│   └── marketing/          # Marketing site (Vite/React)
├── packages/               # Shared packages
│   ├── ai/                 # AI/LLM integration
│   ├── auth/               # Authentication
│   ├── config/             # Configuration management
│   ├── contracts/          # API contracts
│   ├── core/               # Core (admin engine)
│   ├── db/                 # Database schemas (Drizzle)
│   ├── dev/                # Development tooling
│   ├── security/           # Security utilities
│   └── presentation/       # Native UI components (Tailwind v4, zero ext UI deps)
├── scripts/                # Build & maintenance scripts
└── docs/                   # Documentation

Package Roles

Core Packages

@revealui/core - RevealUI admin core

• RevealUI singleton instance
• Collection definitions (Users, Posts, Pages, etc.)
• Global configurations (Header, Footer, etc.)
• Database integration
• Status: Critical path, stable

@revealui/db - Database layer

• Drizzle ORM schemas
• PostgreSQL/PGlite adapters
• Migration management
• Status: Stable

@revealui/auth - Authentication & Authorization

• Session-based auth: database-backed sessions, no JWT (stateless JWT is explicitly not used)
• Password reset, rate limiting, brute-force protection (bcrypt, 12 rounds)
• Role-based access control (RBAC/ABAC, enforced in @revealui/core)
• Status: Stable

Feature Packages

@revealui/ai (Pro) - AI Integration

• AI agents + orchestration
• CRDT-based agent memory
• LLM provider abstractions (open-model first; external LLMs via MCP)
• Embeddings + vector queries (pgvector on the same Neon database)
• Status: Active development

@revealui/security - Security utilities

• Input sanitization
• CSRF protection
• Rate limiting
• Status: Stable

Infrastructure Packages

@revealui/config - Configuration

• Environment variable management
• Type-safe config with Zod validation
• Multi-environment support
• Status: Stable

@revealui/contracts - Type contracts

• Shared TypeScript interfaces
• API response types
• Domain models
• Status: Stable

@revealui/presentation - UI Components

• Native UI components (Tailwind CSS v4, zero external UI deps: only clsx + CVA)
• Accessible primitives, dark mode + tenant-brand theming
• Status: Active development

@revealui/dev - Development tooling

• TypeScript configurations
• Build scripts
• Testing utilities
• Status: Stable

Dependency Flow

apps/admin
  ├─→ @revealui/core
  │    ├─→ @revealui/db
  │    ├─→ @revealui/auth
  │    └─→ @revealui/config
  ├─→ @revealui/presentation
  └─→ @revealui/ai

Dependency Rules

1. No circular dependencies between packages
2. Packages import from packages, never from apps
3. Apps import packages, not other apps
4. Core utilities (db, auth, config) are foundational
5. Feature packages (ai, security) depend on core

Technology Stack

Frontend

• React 19 - UI library with Server Components
• Next.js 16 - admin app (App Router)
• Vite/React - docs + marketing apps
• Tailwind CSS v4 - Styling
• TypeScript 6 - Type safety

Backend

• Hono - REST API (apps/server, OpenAPI + Swagger)
• RevealUI Core - admin engine + content management
• Drizzle ORM - Type-safe database queries
• PostgreSQL (NeonDB) - Production database, pgvector for embeddings
• PGlite - in-process Postgres for tests

Development

• pnpm - Package manager
• Turborepo - Build orchestration
• Vitest - Testing framework
• Biome - Linting & formatting

Build System

Turborepo Configuration

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "cache": false
    },
    "lint": {},
    "typecheck": {
      "dependsOn": ["^build"]
    }
  }
}

Build Order

1. Core packages (db, auth, config, contracts)
2. Feature packages (ai, security, presentation, router)
3. Applications (server, admin, docs, marketing)

Commands

# Build everything
pnpm build

# Build specific package
pnpm --filter @revealui/core build

# Watch mode for development
pnpm dev

# Run tests
pnpm test

# Type check all packages
pnpm typecheck

Package Development

Creating a New Package

# 1. Create package directory
mkdir -p packages/my-package/src

# 2. Create package.json
{
  "name": "@revealui/my-package",
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "test": "vitest run"
  }
}

# 3. Create tsconfig.json
{
  "extends": "@revealui/dev/ts/base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

# 4. Create src/index.ts
export * from './my-feature'

# 5. Update root pnpm-workspace.yaml (if needed)

Package Best Practices

1. Single Responsibility: Each package does one thing well
2. Clear Exports: Export only public API
3. Type Safety: Comprehensive TypeScript types
4. Documentation: README.md with examples
5. Tests: Unit tests for core functionality

Common Patterns

Importing Between Packages

// ✅ GOOD: Import from package
import { getRevealUI } from '@revealui/core'
import type { User } from '@revealui/contracts'

// ❌ BAD: Relative imports across packages
import { getRevealUI } from '../../../core/src/instance'

Shared Types

// packages/contracts/src/user.ts
export interface User {
  id: string
  email: string
  role: 'admin' | 'user'
}

// Used everywhere
import type { User } from '@revealui/contracts'

Configuration

// packages/config/src/index.ts
export const config = {
  database: {
    url: process.env.DATABASE_URL,
  },
  auth: {
    secret: process.env.REVEALUI_SECRET,
  },
}

// Used in packages
import { config } from '@revealui/config'

File Organization

Package Structure

packages/my-package/
├── src/
│   ├── index.ts           # Public API
│   ├── core/              # Core functionality
│   ├── utils/             # Utilities
│   └── __tests__/         # Tests
├── dist/                  # Build output (gitignored)
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

App Structure

apps/admin/
├── src/
│   ├── app/               # Next.js App Router
│   │   ├── (frontend)/    # Public pages
│   │   ├── (backend)/     # Admin pages
│   │   └── api/           # API routes
│   ├── lib/               # admin configuration
│   │   ├── collections/   # RevealUI collections
│   │   ├── globals/       # RevealUI globals
│   │   ├── blocks/        # Content blocks
│   │   └── components/    # React components
│   └── __tests__/         # Tests
├── public/                # Static assets
└── next.config.mjs

Key Architectural Decisions

1. Monorepo Benefits

• Code sharing: Shared packages across apps
• Consistent tooling: Unified build/test/lint
• Atomic commits: Changes across packages
• Type safety: Compiler enforces contracts

2. Package Boundaries

• Clear interfaces: Explicit exports
• Testability: Packages tested independently
• Reusability: Can extract to external packages
• Maintainability: Easy to locate code

3. TypeScript First

• Type safety: Catch errors at compile time
• Documentation: Types serve as docs
• Refactoring: Safe to change code
• Developer experience: IntelliSense everywhere

4. Test Strategy

• Unit tests: Per package
• Integration tests: In apps
• E2E tests: Critical user flows
• Test database: PGlite for speed

Performance Considerations

Build Performance

• Incremental builds: Turborepo caching
• Parallel execution: Multiple packages at once
• Selective builds: Only changed packages

Runtime Performance

• Code splitting: Dynamic imports
• Tree shaking: Dead code elimination
• Server Components: Reduce client bundle
• Edge deployment: Vercel Edge Network

Migration Guide

Adding Dependencies

# Add to specific package
pnpm --filter @revealui/core add package-name

# Add to root (dev tools)
pnpm add -D -w package-name

Moving Code Between Packages

1. Create new file in target package
2. Move & update imports
3. Export from target package index
4. Update consuming packages
5. Run pnpm build to verify
6. Delete old file

Resources

• pnpm Workspaces
• Turborepo
• Next.js App Router
• Drizzle ORM

Understanding this architecture enables effective RevealUI development! 🏗️