Project Structure

Navigate and understand OneApp's organized monorepo structure designed for scalability and team collaboration.

Already familiar with monorepos?

Why structured organization matters

Navigating a large codebase without clear organization creates problems:

Lost code — Can't find where functionality lives
Unclear ownership — Don't know which team owns what
Duplicated work — Developers reimplement existing features
Merge conflicts — Multiple teams editing the same poorly-structured files

OneApp's structure uses a hierarchical organization with packages/ (shared code), teams/ (team workspaces), personal/ (individual experiments), and platform/ (infrastructure apps) — making it crystal clear where code belongs and who owns it.

Production-ready with 40+ workspaces organized by purpose, clear naming conventions, and consistent configuration patterns across all packages.

Use cases

OneApp's structure is ideal for:

Finding code quickly — Predictable locations for components, utilities, and configurations
Team autonomy — Each team has isolated workspaces for their applications and packages
Safe experimentation — Personal workspaces for prototypes without affecting production code
Shared infrastructure — Platform apps (docs, storybook, mobile) available to all teams

How it works

OneApp organizes code into four top-level directories:

monorepo/
├── apps/          # Core deployable applications
├── packages/      # Shared code (components, utilities, types, configs)
├── teams/         # Team-specific workspaces
├── personal/      # Individual developer workspaces
└── platform/      # Infrastructure applications (docs, storybook, etc.)

Each directory serves a specific purpose and follows consistent patterns.

Directory overview

Core structure

monorepo/
├── apps/web/                  # Main Next.js 16 application (port 3000)
│
├── packages/                  # Shared internal packages
│   ├── ui/                    # React components (@repo/ui)
│   ├── types/                 # TypeScript utilities (@repo/types)
│   ├── utils/                 # Common functions (@repo/utils)
│   ├── config/                # Shared configs (@repo/config)
│   ├── auth/                  # Better Auth integration (@repo/auth)
│   ├── db-prisma/             # Prisma ORM client (@repo/db-prisma)
│   ├── email/                 # React Email templates (@repo/email)
│   ├── analytics/             # Analytics with emitters (@repo/analytics)
│   ├── observability/         # Logging and monitoring (@repo/observability)
│   ├── feature-flags/         # Feature flag management (@repo/feature-flags)
│   ├── internationalization/  # i18n with next-intl (@repo/internationalization)
│   ├── seo/                   # SEO utilities (@repo/seo)
│   ├── security/              # Security utilities (@repo/security)
│   ├── storage/               # File storage (@repo/storage)
│   └── uni-ui/                # Universal UI (web + native) (@repo/uni-ui)
│
├── teams/                     # Team workspaces
│   ├── ai/
│   │   ├── apps/              # AI team applications
│   │   ├── packages/          # AI team shared packages
│   │   └── infra/             # AI team infrastructure
│   ├── istudio/
│   │   ├── apps/
│   │   ├── packages/
│   │   └── infra/
│   └── engineering/
│       ├── apps/
│       ├── packages/
│       └── infra/
│
├── personal/                  # Personal workspaces
│   ├── andy/
│   │   ├── apps/
│   │   ├── packages/
│   │   └── infra/
│   ├── torin/
│   ├── michael/
│   ├── vinay/
│   └── jeff/
│
├── platform/                  # Platform applications
│   └── apps/
│       ├── docs/              # Documentation site (port 3003)
│       ├── oneapp-onstage/    # Main consumer app (port 3000)
│       ├── oneapp-backstage/  # AI workflow designer (port 3001)
│       ├── oneapp-api/        # REST API server (port 3002)
│       ├── storybook/         # Component library (port 6006)
│       ├── mobile-app/        # Expo + React Native app
│       └── email/             # React Email templates (port 3004)
│
├── .github/                   # GitHub configuration
│   ├── workflows/             # CI/CD pipelines
│   ├── agents/                # AI agent instructions
│   └── copilot-templates/     # Code templates
│
├── docs/                      # Project documentation
│   └── adr/                   # Architecture Decision Records
│
└── Configuration files
    ├── pnpm-workspace.yaml    # Workspace configuration
    ├── package.json           # Root package.json
    ├── turbo.json             # Turborepo configuration
    └── .npmrc                 # npm configuration

Key directories explained

`packages/` — Shared Code

Shared internal packages used across the monorepo:

Package	Name	Purpose
`ui`	`@repo/ui`	React components
`types`	`@repo/types`	TypeScript utilities
`utils`	`@repo/utils`	Common helper functions
`config`	`@repo/config`	ESLint, TS, Prettier configs
`auth`	`@repo/auth`	Better Auth integration
`db-prisma`	`@repo/db-prisma`	Prisma ORM client
`email`	`@repo/email`	React Email templates
`analytics`	`@repo/analytics`	Analytics with emitters
`observability`	`@repo/observability`	Logging and monitoring
`feature-flags`	`@repo/feature-flags`	Feature flag management
`internationalization`	`@repo/internationalization`	i18n with next-intl
`seo`	`@repo/seo`	SEO utilities
`security`	`@repo/security`	Security utilities
`storage`	`@repo/storage`	File storage (Vercel Blob, R2)
`uni-ui`	`@repo/uni-ui`	Universal UI (web + native)

Usage:

apps/web/app/page.tsx

import { Button } from "@repo/ui";
import { formatDate } from "@repo/utils";
import type { UserId } from "@repo/types";

`teams/` — Team Workspaces

Each team gets isolated workspaces:

teams/{team-name}/
├── apps/        # Team's applications
├── packages/    # Team's shared packages
└── infra/       # Team's infrastructure (configs, scripts)

Benefits:

Isolation — Teams don't step on each other's toes
Autonomy — Teams control their own dependencies and tooling
Sharing — Teams can still consume shared @repo/* packages

Example: AI team workspace

teams/ai/
├── apps/
│   ├── ai-playground/     # AI experimentation app
│   └── prompt-studio/     # Prompt engineering tool
├── packages/
│   └── ai-utils/          # AI-specific utilities (team-only)
└── infra/
    └── scripts/           # AI team scripts

`personal/` — Individual Workspaces

Individual developer spaces for experimentation:

personal/{username}/
├── apps/        # Personal applications
├── packages/    # Personal packages
└── infra/       # Personal infrastructure

Use cases:

Prototyping — Test new ideas without affecting production
Learning — Experiment with new technologies
Side projects — Build tools for personal use

`platform/` — Infrastructure Applications

Platform applications available to all teams:

App	Description	Port
`docs`	Documentation site	3003
`oneapp-onstage`	Main consumer app	3000
`oneapp-backstage`	AI workflow designer	3001
`oneapp-api`	REST API server	3002
`storybook`	Component library	6006
`mobile-app`	Expo + React Native app	N/A
`email`	React Email templates	3004

Usage:

# Run docs site
pnpm --filter=docs dev

# Run Storybook
pnpm --filter=storybook dev

# Run OneApp ecosystem
pnpm dev:oneapp

Configuration patterns

Package configuration

Each package follows a consistent structure:

packages/{name}/
├── package.json           # Package manifest
├── tsconfig.json          # TypeScript config (extends @repo/config)
├── eslint.config.mjs      # ESLint config (extends @repo/config)
├── vitest.config.ts       # Test config (if applicable)
├── src/
│   ├── index.ts           # Package entry point
│   └── ...                # Source files
└── dist/                  # Build output (after build)

App configuration

Each app includes:

apps/{name}/
├── package.json           # App manifest
├── tsconfig.json          # TypeScript config
├── eslint.config.mjs      # ESLint config
├── next.config.mjs        # Next.js config (if Next.js app)
├── tailwind.config.ts     # Tailwind config (if using Tailwind)
├── vitest.config.ts       # Test config
├── .env.example           # Example environment variables
├── .env.local             # Local environment variables (gitignored)
└── app/                   # Next.js app directory
    └── ...

Workspace protocol

Internal packages use the workspace:* protocol:

apps/web/package.json

{
  "name": "web",
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@repo/types": "workspace:*",
    "@repo/utils": "workspace:*"
  }
}

Benefits:

✅ Automatic linking during development
✅ Consistent versioning across workspaces
✅ Proper resolution in CI/CD

Finding code quickly

By functionality

UI components → packages/ui/src/
Utilities → packages/utils/src/
Types → packages/types/src/
Configurations → packages/config/
Authentication → packages/auth/
Database → packages/db-prisma/
Email templates → packages/email/templates/

By team

AI team apps → teams/ai/apps/
iStudio team packages → teams/istudio/packages/
Engineering team infra → teams/engineering/infra/

By platform

Documentation → platform/apps/docs/
Component library → platform/apps/storybook/
API server → platform/apps/oneapp-api/

Next steps

Master commands: Essential Commands →
Understand workspaces: Workspace Architecture →
Explore packages: Shared Packages →

Project Structure

On this page