Project structure

widgets.pro is a Turborepo monorepo with Yarn 4 workspaces. The architecture separates platform shells from shared business logic.

Directory layout

widgets.pro/
├── apps/
│   ├── web/          # Next.js web shell (routing only)
│   ├── mobile/       # Expo native shell (routing only)
│   ├── api/          # NestJS backend (GraphQL + Drizzle)
│   ├── admin/        # Admin dashboard (Next.js + Tailwind)
│   ├── cli/          # CLI tool (Commander.js)
│   └── chrome-extension/  # Browser extension
├── packages/
│   ├── core/         # All business logic, screens, navigation
│   ├── ui/           # Generic Tamagui UI components
│   ├── blueprint/    # Widget Blueprint Protocol
│   ├── trust/        # Provider Trust Protocol
│   ├── dto/          # Shared DTOs (frontend ↔ backend)
│   └── config/       # Tamagui theme/token configuration

Key packages

`packages/core`

All feature code lives here, organised by feature:

core/features/
├── auth/             # Authentication flows
├── dashboard/        # Dashboard rendering and editor
├── widget/           # Widget management
├── widget-designer/  # Visual widget editor
├── ai-agent/         # AI chat panel
├── brand-kit/        # Org branding (logo, colours, fonts)
├── explore/          # Marketplace browsing
├── files/            # File upload UI
├── hotkeys/          # Keyboard shortcuts
├── notification/     # In-app notifications
├── settings/         # Settings tabs (account, org, API keys, sessions)
├── subscriptions/    # Stripe billing UI
├── theme/            # Theme picker
├── tv/               # TV pairing screens
└── user/             # User profile

Rule: apps/web and apps/mobile are empty shells. All screens and navigation code live in packages/core.

`packages/blueprint`

The Widget Blueprint Protocol — platform-agnostic widget description format with types, expression engine, and template processing. Zero UI dependencies.

`packages/trust`

Provider Trust Protocol — certificate-based verification for widget data providers.

`apps/api`

NestJS backend with Code-First GraphQL and Drizzle ORM. Database schema lives at apps/api/src/database/schema.ts.

Conventions

Features export via index.ts — no deep cross-feature imports.
Pure JS dependencies install in packages/core; native dependencies in apps/mobile.
Styled components use @wdg/ui, not raw design props on screens.
All entity IDs use prefixed nanoid format: {prefix}_{nanoid16} — see Entity IDs.

Next steps

Widget Blueprint Protocol — deep dive into how widgets render.
Installation — set up your dev environment if you haven't already.

On this page