Monorepo Structure

All applications and packages are organized in a single repository using Turborepo for orchestration. This structure enables shared code, consistent tooling, and simplified dependency management across frontend and backend applications.

Overview

All applications and packages coexist in one repository with clear organizational boundaries:

• apps/ - Applications (API, Web, Docs, etc.)
• packages/ - Shared packages (core, react, ui, etc.)
• tools/ - Shared tooling configurations (ESLint, TypeScript)

Why Monorepo?

We chose a monorepo over standalone repositories for several key benefits:

• ✅ Code reuse - Shared UI components, types, and utilities across apps
• ✅ Unified tooling - Consistent linting, formatting, and build standards
• ✅ Faster CI/CD - Turborepo caching speeds up builds and tests
• ✅ Simplified dependencies - Automatic synchronization across workspace packages
• ✅ Better DX - Single repository, consistent developer experience

Package Dependency Graph

Organization

Applications (apps/)

Each application is self-contained but can import shared packages:

• apps/fastify - Fastify backend API
• apps/next - Next.js frontend application
• apps/docu - Documentation site (Fumadocs)

Packages (packages/)

Packages follow strict dependency rules and use different dependency strategies based on package type:

• core - Generated runtime-agnostic API client + types (via hey-api from OpenAPI) - no runtime dependencies
• react - React-specific hooks and TanStack Query integration (generated via hey-api) - peer dependencies for framework deps
• ui - Shared UI components (Shadcn/ui based) - bundles dependencies for simplicity
• email - Email template library (React Email) - bundles dependencies for consistency
• notif - Notification service - bundles tightly-coupled deps, peer for config/env
• error - Error handling utilities with Sentry integration (platform-specific exports) - peer dependencies for optional platform deps
• utils - Shared utilities (logger, async helpers, web3 utilities) - peer dependencies for flexibility

Dependency Direction

Strict one-way dependencies prevent circular references:

core → react
  ↑
apps/fastify (OpenAPI)
  ↓
apps/next

Workspace Configuration

The monorepo uses pnpm workspaces for dependency management:

• workspace:* protocol for internal package dependencies
• Symlink-based resolution for fast local development
• Proper hoisting of shared dependencies

Development Workflow

1. Local development - Direct TypeScript imports (no build step)
2. Package builds - tsup compiles packages to ESM for publishing
3. CI/CD - Turborepo orchestrates builds with intelligent caching
4. Publishing - prepack scripts switch exports to dist/ for npm