Architecture

Understand the system design and components of BDSF Adventure OS.

Overview

BDSF is a monorepo architecture with clear separation of concerns:

  • Apps – User-facing web applications
  • Workers – Backend services on Cloudflare
  • Packages – Shared code and design system

Monorepo Structure

bdsf-adventure-os/
├── apps/
│   ├── app-shell/      # Main dashboard app
│   ├── marketing/      # Public marketing site
│   └── docs/           # Documentation (this site)
├── workers/
│   ├── api-gateway/    # Central API router
│   ├── auth/           # Authentication service
│   └── registry/       # Widget & data registry
├── packages/
│   ├── ui/             # React component library
│   ├── tokens/         # Design system
│   └── types/          # Shared types
└── infra/              # Infrastructure as code

Tech Stack

Framework & Platform

  • Next.js 15 – React framework with App Router
  • Cloudflare Pages – Static site hosting
  • Cloudflare Workers – Serverless backend
  • Cloudflare D1 – SQLite database
  • Cloudflare KV – Key-value storage

Language & Tooling

  • TypeScript – Type-safe JavaScript
  • pnpm – Fast, efficient package manager
  • Vitest – Unit testing
  • TailwindCSS – Utility-first CSS framework
  • Turborepo – Monorepo orchestration

Core Components

@bdsf/ui

Reusable React components with consistent styling:

  • Button – CTA and action buttons
  • Card – Content containers
  • WidgetHost – Dynamic widget system

@bdsf/tokens

Design system foundation:

  • Colors – 5 semantic color palettes
  • Spacing – 4px base unit system
  • Typography – Font families, sizes, weights

@bdsf/types

Shared TypeScript definitions:

  • Domain entities (User, Adventure, etc.)
  • API schemas
  • Utility types