Clairo

AI Governance & Digital Compliance platform for German SMEs. Active modules: EU AI Act and GDPR (DSGVO).

Repository Structure

clairo/
├── apps/
│   ├── web/           # clairo.de — marketing site (Next.js + next-intl)
│   └── dashboard/     # app.clairo.de — SaaS frontend (Next.js + Clerk)
├── packages/          # shared packages (added when needed)
└── docs/              # product, architecture, brand, client docs

A separate repository (clairo-api) hosts the Kotlin + Spring Boot backend. See ADR-002 in clairo-api/docs/architecture/ for the full architecture.

Getting Started

pnpm install

# Marketing site (port 3000)
pnpm dev

# Dashboard (port 3001)
pnpm dev:dashboard

Commands

Command	Scope
pnpm dev	Marketing site (port 3000)
pnpm dev:dashboard	Dashboard (port 3001)
pnpm build	Marketing site
pnpm build:dashboard	Dashboard
pnpm test	All workspaces
pnpm --filter @clairo/dashboard test	Dashboard tests only
pnpm lint	All workspaces
pnpm type-check	All workspaces

Dashboard (apps/dashboard/)

The SaaS dashboard at app.clairo.de is a Next.js 16 App Router application for digital compliance management, targeting German SMEs. Two modules are active: EU AI Act (risk classification, prohibition screening, FRIA, high-risk obligations, incidents, AI literacy, works council agreements) and GDPR/DSGVO (processing activities, data processor agreements, data subject requests, data breaches). The UI is German-only with hardcoded strings.

Key Features

Area	Details
Pages	Hub overview (module cards, summary strip, quick-access shortcuts), AI Systems under /ai-act/ (list / detail / create / edit), GDPR sub-modules under /datenschutz/ (VVT, AVV, DSAR, breaches — each with list / detail / create), Compliance overview, Compliance calendar, Employees (list / detail / create), Activity log, Settings
Sub-pages	Classification wizard, Prohibition screening (with speed mode), Provider checklist, FRIA, High-risk obligations, Transparency obligations, Incidents (list / detail / create), AI literacy, Works council agreements (list / detail / create)
Components	260px 3-zone accordion Sidebar (pinned top, module accordions from registry, pinned bottom), Header with breadcrumb, AppShell, KPI cards, Risk donut chart (Recharts), Status badges, Empty states, Wizard step indicator, Data table (TanStack React Table)
Auth	Clerk integration with theme-aware sign-in/sign-up pages (client components, dark-mode-adaptive colorPrimary) and middleware protection
Design	Dark/light mode with FOUC prevention, OKLCH design tokens, GitHub-Midnight dark palette with full brand token overrides, dashboard-specific semantic tokens (risk levels, compliance status)
API layer	Service registry (lib/api/index.ts) dynamically selects between real HTTP clients (when NEXT_PUBLIC_API_BASE_URL is set) and stub fallbacks (when empty). 18 HTTP service implementations in lib/api/http/ use native fetch() with Clerk JWT auth. Server actions in app/actions/ bridge client components to the server-only service layer. Typed error hierarchy (ApiError, NetworkError, AuthError, ValidationError, ServerError) in lib/api/errors.ts. Module registry (lib/modules/registry.ts) defines 6 compliance modules (AI Act, Datenschutz, NIS2, Barrierefreiheit, E-Rechnung, Hinweisgeberschutz) with 2 active

Tech Stack

Next.js 16, React 19, TypeScript, Tailwind CSS v4, shadcn/ui (Radix), Clerk, Recharts, TanStack React Table, React Hook Form + Zod, Sonner (toasts).

Environment Variables

Copy the example file and fill in your Clerk credentials:

cp apps/dashboard/.env.example apps/dashboard/.env.local

Required variables are documented in apps/dashboard/.env.example. At minimum you need NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY from the Clerk dashboard.

API Connection (NEXT_PUBLIC_API_BASE_URL)

The NEXT_PUBLIC_API_BASE_URL variable controls whether the dashboard connects to the real Spring Boot backend or uses in-memory stub fallbacks:

Value	Mode	Behavior
(empty or absent)	Stub	Service registry uses stub implementations. Reads return empty/zero data; mutations throw. No backend required.
http://localhost:8080	Local	Connects to the clairo-api backend running locally via Docker Compose.
https://api-staging.clairo.de	Staging	Connects to the staging backend.
https://api.clairo.de	Production	Connects to the production backend.

Environment validation via Zod runs at application startup (lib/api/env.ts). If NEXT_PUBLIC_API_BASE_URL is set but is not a valid URL, the application throws a ZodError immediately.

The environment naming convention (local / staging / production) is documented in clairo-api/docs/guides/environment-naming.md.

Environment-specific .env files:

apps/dashboard/.env.local         # Local development (stub or local API)
apps/dashboard/.env.staging       # Staging deployment
apps/dashboard/.env.production    # Production deployment

Running

# Development server (port 3001)
pnpm dev:dashboard

# Production build
pnpm build:dashboard

Testing

The dashboard has ~185 test files with approximately 4,500+ tests using Vitest, React Testing Library, and jsdom.

# Run dashboard tests
pnpm --filter @clairo/dashboard test

Documentation

• Architecture decisions — in clairo-api/docs/architecture/ (ADR-001 through ADR-004)
• Go-to-market strategy
• Environment naming convention — in clairo-api/docs/guides/environment-naming.md
• Marketing site details