One Workspace Convention

A simple, AI-friendly project layout for product monorepos.

One Workspace Convention is a lightweight directory convention for projects that may grow beyond a single app: web, API, docs, mobile, desktop, shared packages, deployment config, and AI assistant guidance.

It is designed to make a repository easier to understand for humans, scripts, and AI coding agents.

The Layout

repo/
  apps/        # runnable applications
  services/    # backend services and workers
  packages/    # shared libraries and reusable modules

A typical workspace may look like this:

repo/
  apps/
    web/
    docs/
    mobile/
  services/
    api/
    worker/
  packages/
    ui/
    config/
    sdk/

Why This Exists

Many repositories start simple and then slowly become ambiguous.

Where should the API live?
Is web an app or a package?
Should shared code go under libs, shared, common, or packages?
Can an AI assistant safely infer the structure?

This convention gives the workspace a small, predictable shape.

• apps/ contains things users or operators run directly.
• services/ contains server-side processes.
• packages/ contains reusable code consumed by apps or services.

That is the core idea.

Directory Meaning

apps/

Use apps/ for runnable user-facing or operator-facing applications.

Examples:

apps/web
apps/admin
apps/docs
apps/mobile
apps/desktop

Good fits:

• Next.js apps
• React/Vite SPAs
• Astro or documentation sites
• Expo mobile apps
• Electron desktop apps

services/

Use services/ for backend workloads.

Examples:

services/api
services/billing
services/worker
services/webhook

Good fits:

• HTTP APIs
• background workers
• scheduled jobs
• queue consumers
• backend-for-frontend services

packages/

Use packages/ for reusable modules.

Examples:

packages/ui
packages/config
packages/db
packages/sdk
packages/types

Good fits:

• shared UI libraries
• TypeScript packages
• Go libraries
• config packages
• generated clients
• domain schemas

What This Is Not

This is not a framework.

It does not require a specific language, package manager, deployment platform, or frontend stack.

It is only a small workspace convention:

apps / services / packages

Everything else should be chosen by the project.

AI-Friendly By Default

AI coding agents work better when a repository has stable meaning.

This convention helps agents answer simple questions without guessing:

• “Where is the frontend?”
• “Where is the backend?”
• “Where should a shared library go?”
• “Which parts are deployable?”
• “Which parts are imported by other parts?”

For AI-assisted development, predictable structure is not cosmetic. It reduces wrong edits, misplaced files, and fragile assumptions.

Recommended Workspace Metadata

A workspace may also include a machine-readable manifest:

one.manifest.json

The manifest records the project map:

{
  "version": 1,
  "workspace": {
    "name": "my-product"
  },
  "projects": [
    {
      "name": "web",
      "relativeDir": "apps/web",
      "type": "app"
    },
    {
      "name": "api",
      "relativeDir": "services/api",
      "type": "service"
    },
    {
      "name": "ui",
      "relativeDir": "packages/ui",
      "type": "package"
    }
  ]
}

The directory layout is for humans.
The manifest is for tools and agents.

Recommended Rules

1. Put runnable applications in apps/.
2. Put backend workloads in services/.
3. Put reusable modules in packages/.
4. Give every project a clear, short name.
5. Avoid creating new top-level folders for product code unless the meaning is truly different.
6. Keep generated files separate from source files.
7. Document project-specific exceptions in the workspace README.

Example

acme/
  apps/
    web/
    admin/
    docs/
  services/
    api/
    jobs/
  packages/
    ui/
    eslint-config/
    tsconfig/
    database/
  one.manifest.json
  README.md

In this example:

• apps/web is the customer-facing web app.
• apps/admin is the internal admin console.
• apps/docs is the documentation site.
• services/api is the main backend API.
• services/jobs runs background tasks.
• packages/ui is shared by web and admin.
• packages/database contains database schema and shared data access helpers.

Relationship With One CLI

One CLI uses this convention as its default workspace layout.

When you create or extend a One CLI workspace, new projects are placed according to their role:

frontend  -> apps/
backend   -> services/
library   -> packages/

The convention can also be used without One CLI.

Status

This convention is intentionally small.

The goal is not to standardize every detail of a repository. The goal is to provide a clear default that works well for growing product teams and AI-assisted development.

Small surface area. Stable meaning. Easy to explain.