Monorepo Structure

Status: Accepted

Goal

ByteBite uses a TypeScript monorepo with clear boundaries between deployable applications, shared packages, infrastructure, and documentation.

The structure is optimized for:

• independent deployments
• strict separation of frontend and backend responsibilities
• shared schemas and domain logic
• Docker-based development and production
• straightforward future extraction of services only when justified

Current structure

This is what exists now. The first product slice is Tenant → Restaurant → Domain → Storefront. Menu, cart, checkout, payments, and orders are not implemented.

Empty feature folders are not created in advance. Modules are added when the feature exists.

bytebite/
├── apps/
│   ├── storefront/          # Next.js App Router: tenant storefront + not-found
│   ├── dashboard/           # Vite SPA + shadcn/ui demo + /admin placeholder
│   ├── api/                 # Fastify: health, tenant plugin, storefront restaurant
│   └── docs/                # Fumadocs (canonical documentation)
├── packages/
│   ├── db/                  # Drizzle client, restaurants + restaurant_domains, migrations, seeds
│   ├── domain/              # Hostname normalization, tenant context, order/payment/delivery vocabularies
│   ├── auth/                # Role vocabulary; Better Auth not wired
│   ├── schemas/             # Shared Zod contracts (health, storefront restaurant)
│   ├── types/               # Brands / staff roles not inferred from Zod
│   ├── config/              # parseEnv + base env schema
│   └── observability/       # pino + Sentry init
├── infrastructure/
│   ├── docker/              # App Dockerfiles (dev + prod targets)
│   ├── traefik/dev/         # Local file-provider routing
│   ├── traefik/prod/        # Placeholder for Dokploy Traefik
│   ├── dokploy/             # Placeholder
│   └── scripts/             # Placeholder
├── compose.yml
├── compose.dev.yml
└── README.md

API modules that exist

• apps/api/src/modules/health/ — /health, /health/db
• apps/api/src/modules/storefront/ — GET /storefront/restaurant
• apps/api/src/modules/tenancy/ — hostname lookup against restaurant_domains

What is explicitly not implemented yet

• Auth login/session flows
• Menu, cart, checkout, payments, delivery engines, realtime, jobs
• Custom-domain verification / onboarding UI

Intended structure as features are added

The following is target architecture. Do not treat it as a file checklist of the current repo.

As slices land, expect feature modules under the API (modules/restaurants, modules/domains, …), Storefront app/ + features/, Dashboard src/features/, and Drizzle tables under packages/db/src/schema/. Integrations (Stripe, Twilio, SES, Mapbox, object storage) stay backend-side, out of packages/domain.

Dashboard routing lives at apps/dashboard/src/app/router.tsx (not a src/routes/ tree).

A future apps/admin or packages/ui extraction is allowed only when actual complexity or duplication justifies it. Neither exists today, by design.

Boundaries

Storefront

Next.js for SSR, SEO, tenant branding, menu, cart, checkout, account and tracking UI. It calls the API (same-origin /api in the browser) and does not own ByteBite business rules.

Dashboard

React + Vite SPA for restaurant operations and the initial ADMIN area. shadcn/ui lives directly under apps/dashboard/src/components/ui. Browser API calls use same-origin /api.

API

Fastify is the central backend and business-logic application layer. Integrations with Stripe, Twilio, AWS SES, Mapbox and object storage stay backend-side.

Docs

Fumadocs is the only maintained documentation source (apps/docs/content/docs). Development uses docs.bytebite.test; production will use docs.getbytebite.co behind Traefik BasicAuth.

Shared packages

• packages/domain: framework-independent business rules
• packages/db: Drizzle schema, migrations, client and seeds
• packages/schemas: shared Zod contracts
• packages/auth: Better Auth and role/guard concepts
• packages/types: only types not sensibly inferred from schemas
• packages/config: shared config conventions
• packages/observability: logging/Sentry

Explicit decisions

• No packages/ui initially.
• Dashboard uses shadcn/ui locally.
• Storefront owns its own UI components.
• ADMIN starts as a protected section of Dashboard.
• Backend structure is feature/domain oriented.
• A future apps/admin or packages/ui extraction is allowed only when actual complexity or duplication justifies it.