Mono Repo Structure

Overview

The MOOD MNKY ecosystem uses a mono repository architecture to organize all codebase components and ensure consistency across our digital products. This approach allows us to share code, maintain unified standards, and streamline development workflows.

Our mono repo is managed with Turborepo, providing parallel execution, incremental builds, and a structured development experience.

Repository Organization

Apps

Next.js app (MNKY VERSE + Dojo + LABZ) in apps/web/

Shopify

Liquid theme and theme app extension

Supabase

Migrations and Edge Functions at repo root

Extensions

Theme app extension (blocks, embed)

Config

Root package.json, turbo.json, pnpm-workspace

Directory Structure

The mood-mnky-command monorepo uses a single Next.js application (apps/web/) that hosts MNKY VERSE, The Dojo, and MNKY LABZ via route groups:

mood-mnky-command/
├── apps/
│   └── web/                 # Single Next.js app (MNKY VERSE + Dojo + LABZ)
│       ├── app/
│       │   ├── (storefront)/verse/  # MNKY VERSE routes
│       │   ├── dojo/                # The Dojo routes
│       │   └── (dashboard)/         # MNKY LABZ routes
│       ├── components/
│       └── lib/
│
├── Shopify/
│   └── theme/               # Liquid theme (Dawn-derived)
│
├── extensions/
│   └── mood-mnky-theme/     # Theme app extension (blocks, embed)
│
├── supabase/
│   ├── migrations/          # Database migrations
│   └── functions/           # Edge functions (optional)
│
├── packages/                # Shared packages (workspace supports; add as needed)
│
├── docs/                    # Repo docs (design system, runbooks)
├── mnky-docs/               # Mintlify documentation (this site)
├── .github/                 # GitHub workflows
├── turbo.json               # Turborepo configuration
└── package.json             # Root package.json

The Supabase config lives in supabase/ at the repo root. Migrations, Edge Functions, and config are in that directory. Run supabase start and supabase db reset from the repo root.

Application Structure

The apps/web/ Next.js app uses the App Router with route groups:

apps/web
Shopify Theme

apps/web/
├── app/
│   ├── (storefront)/verse/  # MNKY VERSE
│   ├── dojo/                # The Dojo
│   ├── (dashboard)/         # MNKY LABZ
│   └── api/                 # API routes
├── components/
│   ├── verse/
│   ├── dojo/
│   ├── dashboard/
│   └── labz/
├── lib/
├── public/
└── ...

Shopify/theme/            # Dawn-derived Liquid theme
├── sections/
├── snippets/
├── templates/
├── config/
└── assets/

extensions/mood-mnky-theme/  # Theme app extension
├── blocks/               # App blocks (Blending CTA, etc.)
└── ...                   # App embed (MNKY CHAT)

Package Structure

Shared packages follow a consistent structure to make them easy to consume:

packages/[package-name]/
├── src/
│   └── index.ts            # Main entry point
├── dist/                   # Built output (generated)
├── tests/                  # Tests
├── package.json            # Package metadata and dependencies
└── tsconfig.json           # TypeScript configuration

Infrastructure and Data Organization

Our infrastructure and data follow a clear organization:

Supabase
Agent Integration

# At repo root
supabase/
├── migrations/           # Database migration scripts
├── functions/            # Edge functions (optional)
└── config.toml           # Supabase configuration

Agent logic (MOOD MNKY, CODE MNKY, SAGE MNKY) is integrated in apps/web/ via Flowise (MNKY CHAT), CODE MNKY in LABZ, and the agents documentation in mnky-docs/agents/.

Dependency Management

We use a combination of tools to manage dependencies in our mono repo:

Package Manager

pnpm is our primary package manager, chosen for its efficient handling of dependencies in a mono repo structure.

# Installing a dependency in the web app
pnpm --filter web add react-query

# Installing a root-level dev dependency
pnpm add -w typescript

# Installing in a workspace package (when packages exist)
pnpm --filter web add @repo/ui

Workspace Configuration

Our workspaces are configured in pnpm-workspace.yaml:

packages:
  - 'apps/*'
  - 'packages/*'

And the root package.json:

{
  "name": "mood-mnky",
  "private": true,
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint"
  }
}

Build System

Turborepo orchestrates our build process, enabling incremental builds and task caching.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "public/dist/**"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Supabase Integration

The Supabase integration follows our structured organization:

Migrations

Migrations live in supabase/migrations/ at the repo root. Each migration is a timestamped SQL file applied in sequence:

-- supabase/migrations/20240401000000_create_users_table.sql
CREATE TABLE public.users (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  full_name TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT now()
);

Run supabase db reset from the repo root to apply all migrations.

Supabase Client

The app uses @supabase/supabase-js from apps/web/lib/. Create clients with NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY (or SUPABASE_SERVICE_ROLE_KEY for server-side).

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

Development Workflow

Developing in our mono repo follows these principles:

Task Isolation: Work on isolated features or bugfixes in dedicated branches
Local Development: Use Turborepo’s filtering to run only relevant applications and packages
Dependency Management: Add shared code to appropriate packages rather than duplicating across apps
Testing: Write tests for shared packages to ensure reliability across applications
Documentation: Document shared components and utilities to facilitate reuse

Setting Up Supabase for Development

To set up Supabase for local development:

Install the Supabase CLI

npm install -g supabase

Start Supabase Local Development

# From repo root
supabase start

This will start a local Supabase instance with PostgreSQL, Auth, Storage, and other services.

Apply Migrations

# Apply all migrations to the local database
supabase db reset

This will apply all migrations in the migrations directory and reset the database to a clean state.

Seed Data (Optional)

# Run seed script if present in supabase/seed.sql
supabase db reset

This will populate the database with seed data for development and testing.

Typical Development Commands

# Start development server (runs apps/web via turbo)
pnpm dev

# Start development for the web app only
pnpm --filter web dev

# Run lint
pnpm lint

# Create a new Supabase migration (from repo root)
supabase migration new add_new_feature

CI/CD Integration

Our continuous integration pipeline is configured to handle our mono repo structure efficiently:

Change Detection

The pipeline detects which packages and apps have changed to determine what needs to be built and tested.

Dependency Analysis

It analyzes dependencies to ensure that changes to shared packages trigger builds and tests for dependent apps.

Parallel Execution

Build and test jobs run in parallel for independent packages and apps to minimize pipeline time.

Deployment

After successful tests, affected applications are deployed to their respective environments.

Best Practices

Code Organization

Keep apps and packages focused on specific concerns
Extract shared code into dedicated packages
Maintain consistent file structure across apps

Dependencies

Minimize dependencies between packages
Avoid circular dependencies
Properly declare all dependencies in package.json

Performance

Use Turborepo’s caching for faster builds
Implement code splitting within apps
Optimize package sizes

Testing

Write tests for shared packages
Use mocks for complex dependencies
Ensure tests run in isolation

Documentation

Document package APIs and component usage
Maintain README files for all packages
Use TypeScript for type safety

Versioning

Follow SemVer for all packages
Document breaking changes
Keep package versions in sync when appropriate

Resources

Turborepo Documentation

Official documentation for our build system

pnpm Workspaces

Documentation for pnpm workspace features

Internal Architecture Docs

Detailed architecture documentation for the MOOD MNKY ecosystem

Supabase Documentation

Official Supabase documentation

For questions about our mono repo structure, please contact the MOOD MNKY development team.

Overview

Applications

Packages

Technology Stack

Design Systems & Architecture

Infrastructure

Data Center (Proxmox)

Development Guides

Database & Backend

Integration & SDKs

​Mono Repo Structure

​Overview

​Repository Organization

Apps

Shopify

Supabase

Extensions

Config

​Directory Structure

​Application Structure

​Package Structure

​Infrastructure and Data Organization

​Dependency Management

​Supabase Integration

​Development Workflow

​Setting Up Supabase for Development

​Typical Development Commands

​CI/CD Integration

​Best Practices

Code Organization

Dependencies

Performance

Testing

Documentation

Versioning

​Resources

Turborepo Documentation

pnpm Workspaces

Internal Architecture Docs

Supabase Documentation

Mono Repo Structure

Overview

Repository Organization

Directory Structure

Application Structure

Package Structure

Infrastructure and Data Organization

Dependency Management

Supabase Integration

Development Workflow

Setting Up Supabase for Development

Typical Development Commands

CI/CD Integration

Best Practices

Resources